Segundo a documentação oficial de habilidades Claude Code, uma habilidade é uma pasta contendo um arquivo SKILL.md com frontmatter YAML e instruções em markdown. Claude carrega o nome e descrição na inicialização, depois puxa o corpo completo apenas quando a habilidade é necessária. Esse design de divulgação progressiva mantém o contexto enxuto. O que você recebe aqui: uma habilidade original para auditar links internos, escrita do zero, com casos de teste de gatilho, uma rubrica de resultados e os passos de empacotamento para torná-la repetível.
Um Exemplo Funcional de SKILL.md
Vamos começar com o artefato finalizado para que você veja para onde estamos indo. Abaixo está uma habilidade que audita links internos em um site. Copie-a, instale-a e depois leia o resto do post para entender todas as decisões.
description: >
Audits internal links in a project's HTML or Markdown output.
Use when the user asks to check broken links, find dead anchors,
audit site links, or review internal navigation before a deploy.
``
## Internal Link Audit
``
Run a link audit against the built output or source files.
``
### Steps
``
1. Collect all internal links (href or markdown link targets starting
with / or a relative path).
2. Resolve each link against the project root.
3. Check whether the resolved target file or anchor exists on disk.
4. Report broken links grouped by source file. For each broken link,
show: source file, link text, href, and the reason it fails
(missing file, missing anchor, or redirect loop if detectable).
5. List passing links only in a summary count, not individually.
6. If zero broken links are found, say so explicitly.
``
### Output format
``
- Broken links: grouped table per source file.
- Summary line: "X of Y internal links are broken."
- If scripts/ contains check-links.sh, run it first and append
Claude's analysis below the script output.
Essa é uma habilidade real e funcional. Salve-a em ~/.claude/skills/internal-link-audit/SKILL.md e ela fica imediatamente disponível em todo projeto.
Uma coisa a notar: a documentação oficial confirma que comandos personalizados se fundiram com habilidades. Ambos podem ser invocados com /name. Então /internal-link-audit funciona como um comando direto, e Claude também o corresponderá automaticamente a partir de uma requisição em linguagem natural. Esses não são dois mecanismos separados.
Escolha uma Tarefa Estreita e Escreva a Descrição
O campo description não é documentação. É o gatilho. Cada palavra nele ajuda Claude a corresponder a habilidade ao momento certo ou adiciona ruído que piora a correspondência.
O guia de Hidekazu Konishi coloca claramente: uma descrição vaga é a razão mais comum para uma habilidade nunca disparar. Escreva em terceira pessoa. Comece com o caso de uso principal. Depois liste as frases reais que os usuários digitam, porque a correspondência acontece contra essas frases, não contra sua ideia interna da habilidade.
Descrição ruim: Ajuda com links e coisas relacionadas em projetos web.
Melhor: Audita links internos na saída HTML ou Markdown de um projeto.
Use when the user asks to check broken links, find dead anchors,
audit site links, or review internal navigation before a deploy.
Observe que a segunda versão coloca em primeiro plano a ação ("Audita links internos"), nomeia os tipos de arquivo e depois fornece quatro frases de gatilho concretas na cláusula Use when. Cada frase é algo que um desenvolvedor digitaria de verdade.
Estreito é melhor
Resista à tentação de construir um "verificador de links geral". Uma habilidade que faz uma coisa bem dispara com confiabilidade. Uma habilidade que promete verificar links, validar redirecionamentos e relatar velocidade de página dispara com pouca confiabilidade e produz saída inconsistente. Escolha a fatia mais útil. Você sempre pode escrever uma segunda habilidade para o resto.
Para a auditoria de links internos, as decisões de estreitamento foram:
- Apenas links internos, não externos (ferramentas diferentes, modos de falha diferentes)
- Verifica existência de arquivo e existência de âncora, não status HTTP
- Relata links quebrados agrupados por arquivo de origem, não como uma lista simples
Cada decisão de estreitamento torna as frases-gatilho mais específicas e o formato de saída mais fácil de validar.
Controle de Invocação e Arquivos de Suporte
As skills carregam automaticamente quando Claude coincide com a descrição, e também respondem aos comandos explícitos /nome-da-skill. Conforme a documentação oficial, Claude verifica quatro locais na inicialização: pessoal (~/.claude/skills/), projeto (.claude/skills/), plugin e empresa. Empresa sobrescreve pessoal, pessoal sobrescreve projeto. Conhecer a hierarquia importa quando você está implantando uma skill em um time onde personalização local pode entrar em conflito.
Para invocação, você tem dois caminhos:
- Automático: Claude lê sua solicitação, a compara com descrições carregadas e executa a skill. Nenhum comando barra é necessário.
- Explícito: Você digita /internal-link-audit. Claude carrega o corpo completo
SKILL.mde a executa. Útil para testes e para momentos em que a correspondência automática não é acionada.
Ambos os caminhos executam as mesmas instruções. A distinção não é "manual versus automático", é sobre qual sinal Claude usa para decidir que a skill se aplica.
Arquivos de suporte
Uma pasta de skill pode conter mais do que apenas SKILL.md:
scripts/: Código executável (Bash, Python) que o corpo da skill referencia. A skill internal-link-audit referenciascripts/check-links.shse existir, então você pode colocar um script real de verificação de links depois sem alterar as instruções.references/: Documentação detalhada que Claude carrega sob demanda, não a cada invocação. Bom para regras de casos extremos que você não quer bagunçando as instruções principais.assets/: Modelos e formatos de saída.
Para uma primeira skill, SKILL.md sozinho é suficiente. Adicione scripts/ quando você tiver um comando que realmente quer executar. Adicione references/ quando suas instruções começarem a parecer longas porque você está lidando com uma dúzia de casos extremos inline.
Se você já está gerenciando um CLAUDE.md para instruções em nível de projeto, skills ficam ao lado disso, não são um substituto. O post Claude.md para agências cobre como estruturar esse arquivo separadamente; skills lidam com tarefas estreitas e reutilizáveis que não pertencem a um arquivo de instrução global.
Execute Testes de Gatilho Positivo e Negativo
Escrever é a parte fácil. Testar é onde a maioria das pessoas para cedo demais. Conforme o guia Towards Data Science sobre skills de Claude Code prontos para produção, "testar" aqui significa jogue prompts reais na skill e verifique se ela se comporta corretamente, não testes unitários no sentido de software.
Você precisa de dois tipos de casos de teste: positivo (deve acionar) e negativo (não deve acionar).
Casos de gatilho positivo para internal-link-audit
Estes prompts devem invocar a skill automaticamente:
- "Verifique links internos quebrados antes que eu implante."
- "Encontre âncoras mortas na minha saída de markdown."
- "Faça auditoria dos links do site na pasta de build."
- "Há algum link quebrado no site?"
- "Revise a navegação interna em todo o projeto."
Casos de acionamento negativo
Estes prompts NÃO devem acionar a skill. Se acionarem, você tem um problema de sobre-acionamento.
- "Verifique se os links externos no meu README ainda funcionam." (links externos, território de skill diferente)
- "Valide meu sitemap.xml." (tarefa completamente diferente)
- "Encontre imagens quebradas na página." (imagens, não links)
- "Verifique o status HTTP dos meus endpoints de API." (HTTP, não sistema de arquivos)
Rubrica de resultado
A boa saída de /internal-link-audit deve satisfazer todos os seguintes critérios:
| Critério | Condição de aprovação |
|---|---|
| Agrupa links quebrados por arquivo de origem | Sim, com uma tabela por arquivo |
| Mostra arquivo de origem, texto do link, href e motivo da falha | Todos os quatro campos presentes para cada link quebrado |
| Links funcionando aparecem apenas na contagem de resumo | Sem lista longa de links que funcionam |
| Mensagem explícita "zero links quebrados" quando limpo | Presente quando aplicável |
| Saída do script anexada se check-links.sh existir | Script executado primeiro, análise anexada abaixo |
| Não verifica links externos | Links externos ausentes do relatório |
Execute os casos positivos primeiro. Se a skill acionar em todos os cinco, passe para os casos negativos. Se acionar em algum caso negativo, você tem um problema de descrição.
Corrija o Disparo Excessivo, Disparos Perdidos e Saída Fraca
Três modos de falha, três correções. São problemas separados e cada um tem uma solução diferente.
Disparo excessivo significa que a skill dispara quando não deveria. Geralmente causado por uma descrição muito ampla. A correção é adicionar linguagem de exclusão à cláusula Use when:
Do NOT use for external link checks, HTTP status checks,
sitemap validation, or image audits.
Adicionar exclusões explícitas estreita a superfície de correspondência sem remover os gatilhos positivos.
Disparos perdidos significam que a skill existe mas nunca dispara automaticamente. A descrição não está correspondendo com a linguagem real do usuário. A correção é adicionar mais frases de gatilho que refletem como as pessoas realmente perguntam, não como você descreveria formalmente a tarefa. "Há links mortos?" é diferente de "auditar navegação interna", mas ambas devem disparar a mesma skill.
O guia Towards Data Science descreve um loop de otimização: dividir casos de teste, medir taxa de disparo, gerar descrições melhoradas, escolher o melhor resultado. Você pode fazer isso manualmente com alguns prompts, ou usar a skill criadora de skills do Anthropic para semi-automatizar.
Saída fraca significa que a skill dispara mas a saída é inconsistente ou incompleta. Este é um problema do corpo, não um problema de descrição. Olhe para a rubrica que você definiu. Quais critérios estão falhando? Adicione instruções de formatação mais específicas. Se a saída está perdendo a coluna razão-da-falha, diga explicitamente nas instruções. Se está listando todos os links funcionando (o que você não quer), adicione "Não liste links funcionando individualmente."
Se você está gerenciando uma pilha de automações Claude Code e quer entender melhor que skills se encaixam, o post superpoderes Claude Code cobre o fluxo de trabalho ao redor.
Para equipes em crescimento ou agências lidando com múltiplos projetos de clientes, a página dedicada de configuração Claude Code para agências vale a pena conferir, aborda como organizar skills em um ambiente multi-projeto.
Empacote a Skill e Mantenha-a
Uma vez que a skill passa em todos os testes positivos e falha em nenhum dos negativos, empacote-a apropriadamente.
Estrutura final de pasta
~/.claude/skills/internal-link-audit/
├── SKILL.md
├── scripts/
│ └── check-links.sh (optional, referenced in instructions)
└── references/
└── anchor-edge-cases.md (optional, for edge-case rules)
Compartilhamento entre projetos e pessoas
Skills pessoais em ~/.claude/skills/ estão disponíveis em todos os projetos da sua máquina. Para distribuição em equipe, mova a skill para um repositório compartilhado e tenha membros da equipe criar symlink ou copiar para sua pasta de skills pessoal, ou faça commit em .claude/skills/ em um repositório de projeto compartilhado para acesso com escopo de projeto.
O formato de skill é um padrão aberto. De acordo com o guia de compilação do freeCodeCamp, a mesma estrutura SKILL.md funciona em Claude Code, GitHub Copilot, Cursor e Gemini CLI, os caminhos de instalação diferem mas o formato do arquivo não. Para Claude Code, o caminho é ~/.claude/skills/. Para Copilot, é ~/.copilot/skills/. Mesmo arquivo, home diferente.
Manutenção
Skills se desviam. A estrutura do projeto muda, o formato de saída precisa ser atualizado, ou as frases de gatilho param de corresponder com como a equipe fala sobre a tarefa. Trate SKILL.md como qualquer outro documento no seu repositório: versione-o, revise-o quando o fluxo de trabalho subjacente muda, e re-execute os testes de gatilho após qualquer edição da descrição.
Uma checklist de manutenção numerada:
- Re-execute todos os testes de gatilho positivos e negativos após qualquer mudança de descrição.
- Atualize a rubrica de resultado se os requisitos de formato de saída mudarem.
- Se você adicionar um script em
scripts/, referencie-o explicitamente no corpoSKILL.mdpara que Claude saiba usá-lo. - Ao promover uma skill pessoal para uma skill de equipe, revise as frases de gatilho, membros da equipe podem usar linguagem diferente da sua.
- Delete skills that are no longer used. Stale skills that fire unexpectedly are worse than no skill at all.
FAQ
Onde exatamente o arquivo SKILL.md precisa ficar?
Para skills pessoais disponíveis em todos os projetos, o caminho é ~/.claude/skills/your-skill-name/SKILL.md . O nome do diretório se torna o comando slash. Para skills com escopo de projeto (disponíveis apenas em um repo), use .claude/skills/your-skill-name/SKILL.md dentro da raiz do projeto. Skills Enterprise seguem um caminho separado gerenciado pelo admin Claude Code da sua organização.
O skill carrega seu conteúdo completo toda vez que Claude inicia?
Não. Segundo a documentação oficial, Claude escaneia os diretórios de skills na inicialização mas carrega apenas o nome e a descrição no contexto. O corpo completo do SKILL.md carrega apenas quando o skill é correspondido a uma requisição. Esse é o design de progressive-disclosure: descrições ficam no contexto, instruções completas carregam sob demanda.
Posso ter mais de um skill disparado para a mesma requisição?
Skills são correspondidos individualmente. Se dois skills têm descrições que ambas correspondem à mesma requisição, a hierarquia de prioridade se aplica: enterprise sobrescreve personal que sobrescreve project. Dentro do mesmo nível, você gostaria de distinguir as descrições com mais cuidado para que apenas o skill pretendido dispare. Gatilhos duplicados geralmente indicam que dois skills têm escopo sobreposto e devem ser mesclados ou estreitados.
O que acontece se a descrição diz "Use when" mas o usuário digita o comando slash diretamente?
O skill executa independentemente. Invocação explícita via /skill-name contorna a correspondência automática inteiramente e carrega o corpo completo direto. A cláusula Use when do campo description se aplica apenas à correspondência automática. Então um comando slash direto sempre funciona, mesmo que a frase do usuário não tivesse disparado detecção automática.
Como sei quando usar um skill versus adicionar instruções ao CLAUDE.md?
CLAUDE.md é para contexto sempre ativo: estrutura do projeto, convenções de código, coisas que Claude deve saber em todas as sessões. Skills são para tarefas sob demanda: coisas que você faz às vezes, nem sempre, e quer saída consistente. Se você se vê adicionando um workflow multi-step ao CLAUDE.md, provavelmente pertence a um skill.
O campo description faz o trabalho que a maioria das pessoas pensa que o corpo faz. Escreva frases de gatilho do vocabulário real da sua equipe, mantenha a tarefa estreita, e o resto segue.