Como criar Skills corretamente para o Claude Code: da arquitetura aos testes

1. O que é uma Skill e por que ela é um artefato de software completo

Uma Skill (habilidade) no Claude Code é um pacote modular padronizado de conhecimento, contendo a descrição do fluxo de trabalho (workflow), um conjunto de regras de domínio, procedimentos ou scripts executáveis que o agente de IA carrega automaticamente para resolver uma classe específica de tarefas. Em vez de o engenheiro copiar manualmente longas instruções em cada nova sessão, o agente reconhece autonomamente a intenção do usuário e ativa a Skill correspondente.

A principal diferença entre uma Skill e código tradicional reside no fato de que a decisão de ativá-la é tomada pelo próprio modelo de linguagem com base na correspondência semântica entre a descrição da habilidade e a consulta do usuário. Essa decisão é probabilística: não há compilador nem tipagem estrita, portanto, a precisão na formulação dos metadados determina diretamente se a habilidade será ativada no momento certo.

Por que a Skill é um artefato de engenharia, e não apenas texto comum

1. Versionamento e modularidade: A habilidade consiste em arquivos padrão de repositório, é armazenada no git e evolui sob as mesmas leis que o código da aplicação.
2. Separação entre interface e implementação: O campo description no frontmatter atua como a interface pública da habilidade, enquanto o corpo do arquivo SKILL.md e os scripts anexos constituem sua implementação interna.
3. Composicionalidade: Uma habilidade pode chamar ferramentas externas via MCP, executar utilitários de console e delegar subtarefas a outras habilidades ou subagentes.
4. Vulnerabilidade a regressões: Uma descrição alterada incorretamente pode levar a uma "recusa silenciosa" (a habilidade deixa de ser ativada) ou a alucinações durante a execução das etapas.

2. Estrutura de arquivos e diretórios: SKILL.md, scripts e recursos de referência

Uma habilidade é representada por uma pasta estruturada no sistema de arquivos, cujo núcleo obrigatório é o arquivo SKILL.md. Dependendo da complexidade da tarefa, a habilidade pode ser complementada por scripts auxiliares, manuais e templates.

Arquitetura da habilidade: interface, implementação, recursos no bundle e ferramentas externas ЗбільшитиArquitetura da habilidade: interface, implementação, recursos no bundle e ferramentas externas

Níveis de armazenamento de habilidades no Claude Code

• Habilidades globais (~/.claude/skills/): Disponíveis para o desenvolvedor em todos os projetos na máquina atual. Ideais para utilitários pessoais, templates de commit personalizados ou scripts analíticos.
• Habilidades de projeto (.claude/skills/): Armazenadas diretamente no repositório do projeto e versionadas no git. Disponíveis para todos os membros da equipe, garantindo padrões únicos de arquitetura e testes.

Estrutura recomendada para uma habilidade complexa

Uma habilidade mínima pode consistir em apenas um arquivo SKILL.md. Sistemas maiores empacotam seus próprios scripts de automação e documentação dentro do diretório da habilidade, permitindo manter a lógica compacta e autossuficiente.

3. Regras de formatação do Frontmatter: name e description

O arquivo SKILL.md deve começar obrigatoriamente com um bloco de metadados no formato YAML Frontmatter. Esta é a única parte da habilidade que o Claude lê durante a inicialização da sessão para construir o catálogo de ações disponíveis.

Restrições formais para o nome (name)

• Comprimento máximo de 64 caracteres.
• Permitidos apenas letras minúsculas latinas, dígitos e hífens ([a-z0-9-]).
• Proibido o uso de qualquer tag XML/HTML.
• Proibido usar nomes reservados da empresa (claude, anthropic).

Restrições formais para a descrição (description)

• Campo obrigatório e não vazio.
• Comprimento máximo de 1024 caracteres.
• Proibido o uso de tags XML.
• Deve descrever claramente tanto a funcionalidade da habilidade quanto os gatilhos contextuais para sua ativação.

4. Carregamento progressivo (Progressive Disclosure) e janela de contexto

As Skills não são carregadas totalmente na janela de contexto do modelo no início da sessão. O Claude Code utiliza o princípio de carregamento progressivo (Progressive Disclosure), dividido em três níveis distintos.

Pipeline linear de processamento da consulta pelo modelo e janela de contexto ЗбільшитиPipeline linear de processamento da consulta pelo modelo e janela de contexto

Os três níveis de carregamento

1. Nível 1 — Metadados (Metadata): Nomes e descrições de todas as habilidades disponíveis são carregados no contexto do sistema no início da sessão. O custo é de aproximadamente 100 tokens por habilidade. Isso permite conectar dezenas de habilidades ao projeto sem risco de esgotar o limite de contexto.
2. Nível 2 — Corpo do arquivo (Body): Quando o modelo decide que a consulta do usuário corresponde à descrição da habilidade, ele lê o conteúdo do SKILL.md. O tamanho recomendado do corpo é de até 500 linhas, para não deslocar o histórico operacional do diálogo.
3. Nível 3 — Arquivos anexos e scripts (Resources): Arquivos de referência (references/) são lidos somente quando a instrução faz referência direta a eles. Os scripts geralmente são executados através do interpretador bash: seu código não entra na janela de contexto; apenas o resultado final da execução é retornado.

5. Formulação da description: criação de gatilhos de ativação robustos

Como a description é o principal gatilho para o disparo probabilístico, sua formulação merece atenção especial.

Regras para construir uma descrição eficaz

• Somente terceira pessoa: Escreva a descrição na terceira pessoa (Generates, Performs, Audits). O modelo interpreta a descrição como uma especificação de sistema da ferramenta; pronomes na primeira ou segunda pessoa (I will, You can) degradam a qualidade da correspondência.
• Fórmula "O quê + Quando": A descrição deve responder claramente a duas perguntas: o que exatamente a habilidade faz e em quais situações ela deve ser aplicada.
• Palavras-chave reais: Inclua termos técnicos específicos, nomes de arquivos ou comandos que o usuário certamente mencionará em sua consulta.

6. Anatomia de uma Skill ideal: análise passo a passo do pipeline release-notes

Vamos examinar a arquitetura prática de uma habilidade de automação de documentação de releases chamada release-notes.

Pipeline de execução passo a passo da habilidade release-notes com argumentos e recursos ЗбільшитиPipeline de execução passo a passo da habilidade release-notes com argumentos e recursos

Componentes do fluxo de trabalho

• Parâmetros de entrada: Argumentos do usuário (intervalo de tags v1.2.0..v1.3.0), guia de estilo de referência changelog-style.md e script auxiliar gather-prs.py.
• Sequência de etapas no SKILL.md:
  1. Determinar o intervalo de tags de release no git.
  2. Executar o script python scripts/gather-prs.py para obter uma lista estruturada de commits.
  3. Agrupar as mudanças por categorias (Features, Fixes, Performance, Breaking Changes).
  4. Preparar o rascunho de acordo com o estilo definido em changelog-style.md.
  5. Gravar o bloco atualizado no CHANGELOG.md e exibir um resumo breve.
• Artefatos de saída: Arquivo CHANGELOG.md atualizado e mensagem concisa para a equipe.

Regras arquiteturais para o corpo do arquivo

1. Não repita o óbvio: Assuma que o Claude já é um engenheiro qualificado. Descreva apenas as especificidades do seu projeto e os requisitos corporativos rigorosos.
2. Profundidade de referências — apenas um nível: Arquivos de referência não devem encadear referências a outros arquivos. Todo o material deve estar vinculado diretamente ao SKILL.md.
3. Caminhos multiplataforma: Utilize sempre barras inclinadas (/) em todos os caminhos de arquivos e configurações.

7. Panorama de customizações: Skills, CLAUDE.md, Slash-commands, MCP, hooks e plugins

No Claude Code existem várias ferramentas para controlar o comportamento do agente. A escolha incorreta do mecanismo é a causa mais comum da instabilidade do sistema.

Matriz de mecanismos de customização do Claude Code: quem define a execução versus força de impacto ЗбільшитиMatriz de mecanismos de customização do Claude Code: quem define a execução versus força de impacto

8. Skills vs Hooks: equilíbrio entre recomendações e garantias do runtime

Iniciantes frequentemente tentam usar Skills para tarefas de segurança ou formatação obrigatória de código. Isso é um erro conceitual: a habilidade não garante a execução, ela apenas ensina o modelo sobre a abordagem correta.

Ciclo de vida da execução da sessão do Claude Code e pontos de integração de hooks e habilidades ЗбільшитиCiclo de vida da execução da sessão do Claude Code e pontos de integração de hooks e habilidades

Pontos do ciclo de vida da execução

• SessionStart (Hook): Dispara na abertura da sessão. Garante a inicialização de variáveis de ambiente ou verificação prévia da branch do git.
• Raciocínio do modelo (Possível leitura da Skill): O modelo analisa a tarefa e toma a decisão sobre carregar o corpo do SKILL.md.
• PreToolUse (Hook, bloqueante): Executa imediatamente antes da chamada de qualquer ferramenta. Pode verificar um comando bash e bloquear sua execução (código de retorno 2) se violar regras de segurança.
• PostToolUse (Hook): Analisa o resultado da execução do comando ou modificação do arquivo (por exemplo, executa automaticamente o Prettier após gravar um arquivo).
• Stop (Hook): Dispara após a conclusão da geração da resposta pelo modelo.

9. Processo de desenvolvimento orientado por avaliação (Evaluation-Driven Development)

Criar uma habilidade robusta exige testes iterativos em cenários reais antes mesmo de escrever o texto final das instruções.

Quatro etapas para criar uma habilidade

1. Fixação do nível base (Baseline): Execute o Claude Code em tarefas típicas de trabalho sem a habilidade. Registre onde exatamente o modelo erra, pula etapas ou solicita esclarecimentos adicionais.
2. Criação de casos de teste (Eval Suite): Converta os erros registrados em uma lista de tarefas de controle com resultados esperados claramente definidos.
3. Escrita do texto mínimo (MVP): Formule o conjunto mínimo de instruções no SKILL.md suficiente para passar nos testes.
4. Refinamento iterativo: Adicione regras e exceções apenas em resposta a falhas específicas nos casos de teste, evitando o inchaço do contexto.

Fluxo de trabalho com duas instâncias do modelo

Durante o design da habilidade, recomenda-se utilizar dois terminais paralelos:

• Instância editora: Sessão onde você colabora com o Claude para formular, complementar e estruturar o texto da nova habilidade.
• Instância testadora: Sessão limpa onde você executa consultas de teste e verifica: se a habilidade é capturada automaticamente, se as etapas são interpretadas corretamente e se os arquivos resultantes são válidos.

10. Padrões de projeto comuns e antipadrões na criação de Skills

A experiência prática da comunidade identificou diversos templates comprovados e erros comuns que devem ser evitados.

Padrões de engenharia eficazes

• Sequências numeradas determinísticas: Para ações complexas e multifacetadas, estruture sempre as etapas como 1. ..., 2. ..., 3. ....
• Checklists de validação embutidos: Para operações críticas, adicione um checklist que o modelo deve copiar na resposta e marcar conforme a execução.
• Loops de auto-verificação (Verify & Fix): Defina a regra: "Executar o linter -> corrigir erros -> verificar novamente até a saída limpa".
• Planejamento antes de ações destrutivas: Para operações de exclusão em lote ou sobrescrita de arquivos, exija primeiro a formação de um plano de mudanças em uma tabela markdown e solicite confirmação.

Antipadrões comuns

• Paralisia da escolha: Descrição excessiva de bibliotecas ou abordagens alternativas sem indicar a opção padrão.
• Dependências sistêmicas não declaradas: Uso de utilitários CLI de terceiros ou pacotes npm sem instrução prévia sobre sua instalação ou verificação de existência.
• Barras invertidas em caminhos: Uso de backslashes no estilo Windows (src\utils\), causando falhas no Linux e macOS.
• Números mágicos não explicados: Uso de constantes ou timeouts sem comentário sobre sua origem.

11. Segurança e auditoria de Skills de terceiros antes da instalação

Qualquer habilidade de terceiros é código executável em seu ambiente de trabalho. Como o Claude Code tem acesso ao sistema de arquivos, terminal e rede, uma Skill não verificada representa sérios riscos de segurança.

Checklist de auditoria de uma habilidade de terceiros antes do uso

• Análise do corpo do SKILL.md: Verifique o texto quanto à presença de instruções ocultas com prompt injection, tentativas de roubar arquivos .env ou desativar mecanismos de proteção.
• Auditoria de scripts anexos: Estude cuidadosamente todos os arquivos no diretório scripts/. Certifique-se de que os scripts não realizam requisições de rede suspeitas para servidores externos.
• Verificação de URLs externas: Preste atenção em quaisquer links para download de binários externos ou configurações dinâmicas.
• Teste isolado: A primeira execução de uma habilidade de terceiros deve ocorrer sempre em um repositório de teste ou sandbox sem acesso a segredos de produção.