Claude Code: o que tirar do CLAUDE.md e levar para skills em times

A fonte parte de um problema comum em times: o CLAUDE.md cresce a cada contribuição (checklist de release, passos de migração de banco, regras de endpoints de API) até passar do ponto em que o agente o segue bem. A documentação do Claude Code sugere manter cada CLAUDE.md abaixo de 200 linhas, porque o arquivo inteiro é carregado em toda sessão e arquivos longos são seguidos com menos confiabilidade.

A divisão proposta é simples. CLAUDE.md fica com o que todo mundo precisa todo dia. Uma skill, uma pasta com um SKILL.md (frontmatter mais instruções), guarda procedimentos de uma tarefa específica. Só a descrição fica no contexto até a skill ser acionada, seja por comando (como /add-migration), seja pelo Claude quando o pedido bate com a descrição. Arquivos em .claude/commands/ continuam funcionando, pois os comandos customizados foram incorporados às skills.

Onde a skill mora define quem a recebe: .claude/skills/<name>/SKILL.md no repositório (a opção de time), ~/.claude/skills/ no uso pessoal, ou configurações gerenciadas no nível enterprise. Em nomes iguais, enterprise vence pessoal, que vence projeto. Por isso um /deploy pessoal antigo pode sobrepor o do time, e a fonte recomenda nomes específicos, como deploy-web. Em monorepos, um pacote pode ter seu próprio .claude/skills/, carregado na primeira leitura ou edição de arquivo ali.

No controle de execução, disable-model-invocation: true vale para tudo com efeito colateral (deploy, release, mensagem em canal), e a descrição nem entra no contexto. user-invocable: false serve para conhecimento de fundo. Sobre allowed-tools, a documentação alerta que uma skill versionada no repositório pode conceder a si mesma acesso amplo, inclusive em execução não interativa numa pasta nunca confiada, então o campo deve passar por revisão em pull request. Por fim, a listagem corta a descrição em 1.536 caracteres, e o SKILL.md deve ficar abaixo de 500 linhas, com material longo em arquivos separados.

A cobertura anterior tratava skills de forma mais conceitual. Em 18 de março de 2026, o CEVIU noticiou "Construindo o Claude Code: Como a Anthropic Utiliza 'Skills' para Otimizar o Desempenho da IA", sobre skills como pastas funcionais com scripts e assets, usando o sistema de arquivos para engenharia de contexto. Em 17 de agosto de 2026, "Gestão de Contexto: Otimizando o Uso do Claude Code para Desenvolvedores" abordou eficiência de contexto em geral. A matéria de hoje desce ao uso em equipe: o que sai do CLAUDE.md, onde versionar e quem pode executar cada skill.

Para quem mantém o CLAUDE.md de um time, a leitura prática é tratar o arquivo como código: toda seção que só vale para um tipo de tarefa é candidata a skill. Para quem opera pipelines, restringir deploy ao acionamento manual e revisar allowed-tools em PR são decisões de segurança, não de conveniência.