Uma Biblioteca Central para a Sua Config .claude

Dez repositórios na sua máquina. Cada um com uma pasta .claude cheia de agentes, skills, comandos, hooks e um CLAUDE.md. Uns poucos estão atualizados. A maioria começou a divergir há semanas. O agente de code review que você corrigiu no mês passado está em um projeto, não nos outros nove. Seu colega criou um comando de planeamento que você nunca viu porque ele só existe no repo dele.

Esse é o problema de distribuição da pasta .claude. Adicione um projeto e o problema cresce.

Solução Rápida: Crie um repositório Git privado que guarda todo o seu conteúdo .claude em um só lugar, com um map.json que decide quais itens vão para qual projeto:

{
  "projects": {
    "~/projects/webapp": {
      "claude-md": "web-full",
      "skills": ["git-commits", "react", "frontend-design"],
      "agents": ["visual-explainer"],
      "commands": ["team-plan", "build"]
    }
  }
}

Um comando executa a sincronização, e a pasta .claude dentro de cada projeto fica igual à entrada do mapa. Ajuste uma skill ou agente no local, envie de volta para o upstream, e todos os outros projetos que referenciam esse item herdam a correção na próxima sincronização.

Por Que a Gestão da Pasta .claude Importa

Trabalhando em um único repositório? As suas skills, agentes e comandos ficam ao lado do código. Tudo está ao alcance e tudo está atualizado.

Cruzando cinco ou seis projetos, as coisas desmoronam:

• Duplicação em todo o lado. Oito repos cada um com a própria cópia de git-commits, e nenhumas duas são iguais.
• Divergência de versões. A atualização da semana passada no comando de planeamento só chegou a um único repo. O resto ainda roda o código antigo.
• Sem coordenação. O seu colega criou um agente de migração de banco de dados. Você criou o seu próprio porque a versão dele era invisível para você.
• Espalhamento de configuração. Skills são só o começo. Hooks, settings.json, CLAUDE.md, definições de agentes e slash commands se acumulam. Cada projeto quer uma combinação diferente.

Copiar arquivos é o primeiro instinto. Parece rápido e funciona por um momento, depois cai dentro de um mês. Todo engenheiro rodando agentes em muitos repos vive essa história.

IndyDevDan percebeu isso cedo e criou uma solução puramente agêntica construída em torno de um catálogo YAML cheio de referências a repos externos e caminhos. Essa abordagem provou que a ideia funciona. Rodar em 10+ projetos com 30+ skills e 19 agentes revelou a próxima necessidade: estrutura mais forte. Gestão de arquivos de verdade. Suporte a variantes. Cobertura total da pasta .claude. Um motor de sincronização que vale o seu peso.

A Arquitetura da Biblioteca

A biblioteca é um repositório Git privado que guarda toda a configuração .claude. Não ponteiros ou referências a outros repos. Os arquivos em si. Uma fonte de verdade para cada pasta de skill, cada definição de agente, cada slash command, cada hook, cada CLAUDE.md e cada settings.json.

Um map.json na raiz diz qual projeto recebe quais itens. Um script de sincronização copia os arquivos certos para os lugares certos. Um manifesto dentro de cada projeto registra o que a biblioteca possui, para que arquivos locais fiquem seguros.

your-library/
├── map.json                    # Which projects get what
├── sync.mjs                    # Node.js sync engine
│
├── skills/                     # All skill folders
│   ├── git-commits/
│   ├── agentic-builder/
│   ├── react/
│   ├── growth-kit/
│   ├── session-management/
│   └── ... (31 skills in my library)
│
├── agents/                     # All agent .md files
│   ├── frontend-specialist.md
│   ├── backend-engineer.md
│   ├── security-auditor.md
│   ├── master-orchestrator.md
│   └── ... (19 agents in my library)
│
├── commands/                   # All slash commands
│   ├── team-plan.md
│   ├── build.md
│   ├── team-build.md
│   └── ... (16 commands in my library)
│
├── hooks/                      # All hook folders
│   ├── SkillActivationHook/
│   ├── ContextRecoveryHook/
│   └── Validators/
│
├── claude-mds/                 # CLAUDE.md variants (full replacement per project)
│   ├── CLAUDE--web-full.md
│   └── CLAUDE--product.md
│
├── settings/                   # settings.json variants
│   ├── settings--web.json
│   └── settings--product.json
│
└── rules/                      # .claude/rules/ files
    ├── repo-primer--webapp.md
    └── repo-primer--product.md

Oito categorias de conteúdo (skills, agentes, comandos, hooks, regras, claude-mds, settings e arquivos arbitrários), todos gerenciados a partir de um único repo. Numa sincronização, o motor abre o map.json, encontra a entrada do projeto e copia exatamente o que a entrada lista. Nada a mais, nada faltando.

O Mapa: Controlando O Que Vai Para Onde

O map.json é o cérebro. Cada entrada de projeto define os itens que aquele projeto recebe:

{
  "$schema": "library-map-v1",
  "projects": {
    "C:/Github/my-webapp": {
      "claude-md": "CLAUDE--web-full",
      "settings": "settings--web",
      "skills": [
        "git-commits",
        "react",
        "frontend-design",
        "session-management"
      ],
      "agents": ["frontend-specialist", "quality-engineer"],
      "commands": ["team-plan", "build", "team-build"],
      "hooks": ["SkillActivationHook", "Validators"],
      "rules": [],
      "files": {}
    }
  }
}

Outro projeto pode escolher uma mistura completamente diferente. Um repo SaaS puxa os agentes backend-engineer, supabase-specialist e security-auditor junto com skills postgres-best-practices e auth. Um repo focado em marketing troca esses por growth-kit, seo-specialist e content-writer. Um repo de produto recebe um conjunto mais enxuto com um CLAUDE.md diferente e hooks diferentes. A biblioteca guarda o catálogo completo e cada projeto escolhe a sua própria fatia.

Profiles agrupam configurações compartilhadas que vários projetos querem usar:

{
  "profiles": {
    "web-default": {
      "claude-md": "CLAUDE--web-full",
      "settings": "settings--web",
      "skills": [
        "git-commits",
        "react",
        "frontend-design",
        "session-management"
      ],
      "agents": ["frontend-specialist", "quality-engineer"],
      "commands": ["team-plan", "build"],
      "hooks": ["SkillActivationHook", "Validators"]
    }
  }
}

Execute --profile web-default ao iniciar um novo projeto e toda a stack web chega em um único comando.

Variantes: Quando Uma Versão Não Basta

Profiles deixam uma lacuna. A sua skill git-commits roda bem na maioria dos repos, enquanto o repo do blog precisa de uma versão ajustada que reconhece padrões extras ligados à escrita MDX. Dividir em uma skill completamente nova é pesado demais. O que você realmente quer é a mesma skill com um chapéu por projeto.

O padrão de nomenclatura é name--variant, com um traço duplo entre o nome base e a tag da variante:

skills/
├── git-commits/                    # Base version
│   └── SKILL.md
├── git-commits--blog/              # Variant for blog projects
│   ├── SKILL.md                    # Modified version
│   └── references/
│       └── mdx-patterns.md         # Extra file this variant needs

No map.json, a referência usa o nome completo:

{
  "skills": ["git-commits--blog", "react", "frontend-design"]
}

Na sincronização, git-commits--blog se instala em .claude/skills/git-commits/. O sufixo --blog fica apenas dentro da biblioteca. Nada disso chega ao projeto. A variante é uma pasta autossuficiente. Arquivos diferentes, estrutura diferente, conteúdo diferente. A única coisa que ela compartilha com a base é o nome de deploy.

O push é onde o benefício aparece. Edite .claude/skills/git-commits/ dentro do seu projeto de blog. Durante o push, o motor abre o manifesto, descobre que o git-commits local está mapeado para git-commits--blog, e encaminha as edições para essa pasta. Os outros projetos continuam puxando da base simples.

Operações

O motor de sincronização é um script Node.js sem dependências externas. Oito operações cobrem o ciclo de vida completo:

O bootstrap roda pelo seed. Aponte para qualquer repo cuja pasta .claude já está em bom estado, e toda a pasta chega à biblioteca. Uma entrada é adicionada ao map.json. Um manifesto é gravado. A partir daí, a propriedade canônica fica na biblioteca.

O hash de conteúdo alimenta a operação diff. Ela compara as versões da biblioteca e do projeto e rotula cada item como in-sync, local-changes ou library-ahead, para que a divergência fique visível antes de qualquer sincronização ou push.

O Manifesto: Rastreando O Que a Biblioteca Possui

Cada projeto sincronizado recebe um .claude/.library-manifest.json:

{
  "library_path": "/path/to/your-library",
  "synced_at": "2026-03-24T10:30:00Z",
  "library_commit": "abc123",
  "managed": {
    "skills": {
      "git-commits": "git-commits--blog",
      "react": "react",
      "frontend-design": "frontend-design"
    },
    "agents": {
      "frontend-specialist": "frontend-specialist"
    },
    "claude-md": "CLAUDE--web-full",
    "settings": "settings--web"
  }
}

Dentro do manifesto, cada nome de deploy fica ao lado do seu nome na biblioteca. O push funciona contra esse mapeamento. Uma pasta git-commits/ local flui de volta para git-commits--blog/ em vez de sobrescrever a base simples.

Arquivos que o manifesto não lista estão completamente fora da visão da biblioteca. Notas pessoais, backups, experimentos pontuais dentro de .claude/ passam por uma sincronização sem nenhum arranhão. Apenas os itens que a biblioteca colocou são de propriedade da biblioteca.

Interface de Linguagem Natural

O sistema vem com mais do que uma CLI. Um slash command /library é implantado em cada projeto sincronizado. Esqueça as flags e pergunte em inglês simples:

/library sync
/library I modified the blog command, push it back
/library add the payment-processing skill to this project
/library what's out of sync?
/library create a variant of react for this project
/library show me everything available

Do outro lado do comando, Claude abre o manifesto, vai até a biblioteca, extrai a intenção da frase e dispara o motor de sincronização. Qualquer coisa destrutiva (exclusões, sobrescritas) recebe um prompt de confirmação primeiro.

Esse é o modelo de interação que torna tudo usável no dia a dia. A sessão Claude Code nunca precisa fechar para trabalho na biblioteca. Fale a necessidade em voz alta e a biblioteca reage.

Começando

Construir a sua própria biblioteca leva cerca de 30 minutos:

1. Crie um repositório privado com estas pastas: skills/, agents/, commands/, hooks/, claude-mds/, settings/

2. Faça seed do seu melhor projeto. Escolha o repo que tem a pasta .claude mais rica hoje e puxe seu conteúdo para a biblioteca. Esse conjunto se torna o catálogo inicial.

3. Escreva o seu map.json. Comece com um único registro de projeto. Para esse registro, liste todos os itens que o projeto precisa: cada skill, cada agente, cada comando, cada hook e qualquer arquivo de configuração.

4. Construa o script de sincronização. O núcleo é simples. Carregue o map.json. Analise os nomes dos itens, dividindo em -- onde aparecem variantes. Copie os arquivos para os destinos. Grave um manifesto. Puxe do Git antes de sincronizar. Faça commit e push depois de um push.

5. Adicione o comando /library dentro da própria biblioteca. Cada projeto sincronizado automaticamente o recebe, para que o controle em linguagem natural esteja disponível desde o início.

6. Adicione um segundo projeto com uma mistura diferente. Dois repos compartilhando uma biblioteca é onde o benefício aparece. Mesma fonte, configurações distintas, sem divergência em nenhum dos dois lados.

Uma decisão de design importa mais: guarde os arquivos reais no repo, não ponteiros. A indireção adiciona uma camada que transforma variantes em trabalho extra e pushes em um nó. Com os arquivos sentados diretamente dentro da biblioteca, sincronizar é copiar, fazer push é copiar ao contrário e fazer diff é uma verificação de hash.

Por Que Isso Importa em Escala

Uma vez que a biblioteca está rodando, os hábitos mudam. Para referência, o setup usado neste post cobre 31 skills, 19 agentes, 16 comandos, 4 sistemas de hooks e arquivos CLAUDE.md e settings.json por projeto em 3 projetos ativos. Veja como isso funciona na prática:

Melhorias se propagam. Uma correção no seu agente de code review entra uma vez. A partir da próxima sincronização, cada projeto que lista esse agente herda o patch. Chega de caçar em qual repo uma correção pode estar.

Novos projetos começam rápido. Inicialize um repo novo com um profile e toda a equipe de agentes, bundle de hooks, settings e CLAUDE.md chegam em segundos. O ritual da primeira hora de copiar arquivos de configuração acabou.

Variantes evitam forks. Um projeto que precisa de uma versão ajustada agora recebe uma variante em vez de divergir em silêncio. Base e variante se relacionam através de um link explícito dentro da biblioteca. Doze meses depois, rastrear quais projetos dependem de quais versões ainda é um trabalho de uma consulta.

A biblioteca se autodistribui. O comando /library vive na própria biblioteca. Melhore-o e o upgrade vai junto na próxima sincronização em cada projeto. O sistema de distribuição se distribui por si mesmo.

O problema de distribuição da pasta .claude é um sinal de uma mudança mais profunda. À medida que a engenharia agêntica cresce, toda a sua configuração .claude se torna infraestrutura real: skills, agentes, comandos, hooks, regras, CLAUDE.md e settings. Eles merecem o mesmo cuidado que você dá ao código da aplicação. Uma forma de fazer isso: uma biblioteca compartilhada, ciente de variantes, com sincronização que flui em ambas as direções.

Para um ponto de partida do que uma biblioteca pode distribuir, o ClaudeFast Code Kit vem com 20+ skills de produção, 18 agentes especializados (frontend-specialist, backend-engineer, security-auditor, quality-engineer e mais), um sistema de orquestração de equipes e 5 hooks de produção prontos para catalogar e sincronizar em seus projetos.

Perguntas Frequentes

O que é um sistema de biblioteca Claude Code?

Um repositório Git privado que possui cada parte do seu conteúdo .claude em um único lugar: skills, agentes, comandos, hooks, CLAUDE.md e settings. O map.json decide quais itens chegam a qual projeto. Um motor de sincronização leva os arquivos certos para os diretórios certos.

Como isso é diferente do the-library do IndyDevDan?

O setup do IndyDevDan mantém referências dentro de um catálogo YAML, com ponteiros alcançando repos GitHub ou caminhos locais. O padrão coberto aqui guarda os arquivos reais diretamente dentro de um repo. Um esquema de nomenclatura de variantes suporta versões por projeto. Um manifesto habilita sincronização bidirecional. Cada categoria de conteúdo .claude está no escopo: skills, agentes, comandos, hooks, regras, CLAUDE.md, settings e arquivos arbitrários.

A biblioteca precisa ser open source?

Não. Um repo privado é o lugar certo. A biblioteca carrega skills especializadas, CLAUDE.md por projeto e instruções de agentes que podem ser sensíveis. Mantenha as coisas privadas por padrão. Uma única skill que você queira publicar depois sempre pode ser extraída para o seu próprio repo.

Como as variantes funcionam?

O padrão de nomenclatura name--variant é a ideia central. Uma pasta chamada react--strict/ dentro da biblioteca chega em .claude/skills/react/ dentro do projeto. Cada variante é uma cópia independente com seus próprios arquivos e layout. O manifesto registra a relação para que operações de push carreguem edições de volta para a variante correspondente.

Várias pessoas podem compartilhar uma biblioteca?

Sim. Como é um repositório Git, uma equipe pode cloná-lo e puxar dele. Melhorias de skills voltam no push. Cada colega pega essas correções na próxima sincronização. O map.json pode listar entradas cobrindo os projetos de todos.