O que são skills do Claude Code e como usar no time

O que é uma skill do Claude Code

Uma skill é conhecimento de procedimento empacotado: o passo a passo que alguém do time explicaria a um colega novo, escrito uma vez e lido pelo agente sempre que a tarefa aparece. O formato segue o padrão aberto Agent Skills, que outras ferramentas além do Claude Code também leem.

• Frontmatter: O name e a description, que dizem o que a skill faz e quando usá-la; é a parte que o agente vê em toda sessão.
• Corpo: As instruções em Markdown, carregadas quando a skill é usada.
• Arquivos de apoio: Referências, modelos e scripts na mesma pasta, lidos ou executados só quando a instrução pede.
• Local: Em ~/.claude/skills, a skill vale para uma pessoa em todos os projetos; em .claude/skills, dentro do repositório, ela é versionada com o código e chega ao time inteiro.

Ferramentas de Spec-Driven Development como Spec Kit e OpenSpec já se instalam como skills: cada etapa do método vira uma skill que o agente chama no chat.

Progressive disclosure: por que uma skill quase não pesa no contexto

A janela de contexto é limitada, e tudo o que entra nela custa tokens e atenção do modelo. As skills carregam em três níveis, cada um só quando é necessário.

Há duas consequências práticas. A descrição decide se a skill dispara: vaga demais, o agente não a encontra; ampla demais, ela carrega na hora errada. E, depois de carregada, a skill fica no contexto pelo resto da conversa, então cada linha do corpo vira custo recorrente; a documentação recomenda manter o SKILL.md abaixo de 500 linhas.

Skills, hooks e CLAUDE.md: o que vai em cada um

Os três guardam conhecimento do time para o agente, mas entram em momentos diferentes. Escolher o lugar errado gasta contexto ou deixa uma regra importante sem garantia.

Uma regra da documentação do Claude Code resolve a maior parte das dúvidas: instrução em CLAUDE.md ou em skill é um pedido, não uma garantia. Se algo precisa acontecer toda vez, como impedir a edição de um arquivo .env, isso vira hook. E quando o CLAUDE.md passa de 200 linhas, o material de consulta deve migrar para skills.

Como testar e versionar skills

Ver uma skill disparar só prova que o agente a encontrou. Para saber se ela funciona, é preciso medir duas coisas em separado: se dispara nos pedidos certos e se o resultado melhora quando ela está ativa.

1. Monte os casos: Pedidos reais que devem disparar a skill e pedidos parecidos que não devem.
2. Compare com e sem a skill: Rode cada caso em uma sessão nova, uma vez com a skill e outra com ela desligada, e compare os resultados.
3. Automatize a comparação: O plugin skill-creator guarda os casos em evals/evals.json e mede taxa de acerto, tempo e tokens; para skills distribuídas em plugin, o comando claude plugin eval pode reprovar o CI abaixo de uma nota mínima.
4. Versione como código: A skill fica em .claude/skills, muda por pull request com revisão e vira plugin quando vários repositórios precisam dela.

Testes e versionamento fazem parte de como escrevemos skills, junto com gatilhos claros e o carregamento sob demanda.

Governança: skills no time, com segurança

Uma skill pode mandar o agente executar código, então instalar uma skill é parecido com instalar software. A documentação da Anthropic recomenda usar só skills de fontes confiáveis e auditar todos os arquivos de uma skill de terceiros antes do uso.

• Permissões dentro da skill: O campo allowed-tools libera ferramentas sem pedir aprovação durante o turno em que a skill roda, mesmo em pastas não confiáveis; revise esse campo em toda skill que entra no repositório.
• Ações com efeito colateral: Skills que fazem deploy, commit ou enviam mensagens levam disable-model-invocation: true, para que só uma pessoa possa chamá-las.
• Regras de permissão: Skill(deploy *) em uma regra de bloqueio impede o agente de usar a skill, sem editar o arquivo dela.
• Inventário: O comando /skill-doctor mostra o custo de contexto e o uso de cada skill e ajuda a desligar as que ninguém usa.

No programa em que atuamos para a The Hackett Group, o modelo operacional usa 12 agentes e 25 skills com hooks de quality gate, em Claude Code e OpenCode.