# Como criar Skills corretamente para o Claude Code: da arquitetura aos testes
> Guia de engenharia abrangente sobre a criação de Skills para o Claude Code: anatomia de pastas e SKILL.md, carregamento progressivo (progressive disclosure), diferenças em relação aos hooks e abordagem evaluation-driven.
## 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.
```mermaid
flowchart TD
subgraph Invocation ["Активація навички"]
Prompt["Запит користувача"] --> Matcher{"Семантичне зіставлення (LLM)"}
Meta["Frontmatter name + description
(~100 токенів на старті)"] --> Matcher
Matcher -->|Збіг наміру| Load["Підвантаження SKILL.md у контекст"]
Matcher -->|Немає збігу| Normal["Стандартне виконання без навички"]
end
subgraph Execution ["Пайплайн виконання"]
Load --> Steps["Виконання покрокових інструкцій"]
Steps --> Scripts["Запуск локальних скриптів (bash/python)"]
Steps --> Refs["Читання довідкових файлів (references/)"]
Scripts & Refs --> Result["Фінальний артефакт / код"]
end
```
### 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.
> [!NOTE]
> A especificação **Agent Skills**, proposta pela Anthropic, é um formato aberto. Habilidades estruturadas de acordo com esse padrão são compatíveis não apenas com o Claude Code, mas também com outras ferramentas avançadas de automação de desenvolvimento.
---
## 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.
### 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
```text
.claude/skills/release-notes/
├── SKILL.md # Obrigatório: metadados e instruções
├── changelog-style.md # Recurso: regras de formatação do registro de alterações
└── scripts/
└── gather-prs.py # Script executável: coleta de PRs mesclados via API
```
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.
```yaml
---
name: release-notes
description: Drafts release notes from merged pull requests between two git tags. Use when cutting a release or updating the changelog.
---
```
### 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.
| Campo | Exemplo válido | Exemplo inválido | Motivo da proibição |
| :--- | :--- | :--- | :--- |
| `name` | `db-migrate-helper` | `Claude-DB-Helper!` | Letras maiúsculas, caracteres especiais e palavra reservada `claude` |
| `name` | `deploy-staging` | `deploy_` | Símbolos proibidos: underscore e colchetes angulares |
| `description` | `Generates API documentation from Express routes. Use when updating docs.` | `A tool for API` | Descrição muito curta e vaga; ausentes os gatilhos de execução |
> [!WARNING]
> Se a habilidade deve ser executada exclusivamente mediante comando explícito do usuário e não deve disparar automaticamente, seu chamado automático pode ser restringido convertendo-a em um comando de barra (/command) determinístico.
---
## 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.
```mermaid
flowchart LR
L1["Рівень 1: Метадані
(~100 токенів, читається завжди)"] -->|Тригер збігу| L2["Рівень 2: Тіло SKILL.md
(~1-3k токенів, читається за потреби)"]
L2 -->|Посилання у кроках| L3["Рівень 3: Ресурси та скрипти
(0 токенів до виклику або запуску)"]
```
### 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.
:::tabs
@tab Descrição fraca
```yaml
---
name: release-notes
description: Handles project releases and writes updates.
---
```
*Problema: Ausência de gatilhos contextuais concretos. O modelo não sabe quais arquivos ler nem quando ativar a habilidade.*
@tab Descrição ideal
```yaml
---
name: release-notes
description: Drafts release notes from merged pull requests between two git tags. Use when cutting a release, updating the changelog, or summarizing what changed in a version.
---
```
*Vantagem: Entidades de entrada claramente definidas (git tags, pull requests) e cenários de ativação (cutting a release, updating changelog).*
:::
---
## 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`.
### 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.
| Mecanismo | Quem inicia a execução | Força de impacto | Cenário de uso ideal |
| :--- | :--- | :--- | :--- |
| **CLAUDE.md (Memory)** | Runtime (sempre no contexto) | Recomendativa | Regras gerais curtas do projeto, stack tecnológica, comandos básicos |
| **Skill** | Modelo (semanticamente) ou humano | Recomendativa | Procedimentos complexos de domínio, fluxos de trabalho com scripts anexos |
| **Slash-command** | Usuário (via `/comando`) | Recomendativa | Templates de prompts interativos salvos, chamados manualmente |
| **Subagent** | Modelo ou usuário | Isolada | Delegação de uma tarefa volumosa independente para uma janela de contexto separada |
| **MCP Tool** | Modelo (via Tool Call) | Executiva | Interação direta com bancos de dados externos e APIs de nuvem |
| **Hook** | Runtime (deterministicamente) | **Bloqueante** | Verificações rígidas de segurança, linters antes do commit, validação de ações |
| **Plugin** | Usuário (instalação) | Complexa | Distribuição em lote de conjuntos de habilidades, servidores MCP e hooks para a equipe |
> [!IMPORTANT]
> Apenas os mecanismos gerenciados diretamente pelo runtime (como **hooks**) podem fornecer garantia absoluta de execução e bloqueio de ações indesejadas. Instruções textuais dentro de uma Skill permanecem recomendações que o modelo segue probabilisticamente.
---
## 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.
### 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.
```text
Regra de ouro para a escolha:
- Se a ação exige pensamento de engenharia flexível e contexto ──► Crie uma SKILL
- Se a ação deve ser executada incondicionalmente e sem exceções ──► Configure um HOOK
```
---
## 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.