Entendendo as skills do Claude Code: o que é carregado, quando é ativado e como escrever uma

Removendo a marca, uma skill é um diretório com um arquivo obrigatório. O SKILL.md começa com um frontmatter YAML contendo um name e uma description, seguido por instruções comuns em Markdown. A pasta também pode conter scripts invocados pelas instruções, documentos de referência e templates de assets. Esse é todo o formato, e ele é deliberadamente simples: uma skill é um procedimento documentado, empacotado para que um agente possa encontrá-lo.

---
name: brand-audit
description: Check UI code against the project design system. Use when reviewing components, screens, or PRs for hardcoded colors, off-scale spacing, or fonts that bypass the tokens in DESIGN.md.
---

# Brand audit

1. Read DESIGN.md at the repo root before judging anything.
2. Flag any literal hex value, arbitrary Tailwind color, or font-family
   that does not come from the token set.
3. Report violations as file:line with the token that should be used.

O mesmo formato agora funciona além do Claude Code: ele evoluiu para uma convenção aberta de agent-skills que o Codex da OpenAI e o Cursor adotaram com seus próprios caminhos de descoberta, razão pela qual uma skill que você escreve uma vez passa a acompanhá-lo em diferentes ferramentas. Abordamos a parte do Codex em Codex skills.

O Claude Code não lê suas skills em todas as conversas. No início da sessão, ele indexa apenas o frontmatter: cada skill contribui com seu nome e descrição para o contexto — algumas linhas, nada mais. O corpo completo, os scripts e os arquivos de referência são carregados apenas quando o Claude decide que a tarefa atual corresponde a uma descrição, ou quando você invoca a skill explicitamente. A Anthropic chama isso de divulgação progressiva (progressive disclosure), e essa é a decisão de design na qual todo o recurso se baseia.

Disso decorrem duas consequências práticas. Primeiro, instalar cinquenta skills quase não custa nada em termos de contexto, então acumular é barato; cem descrições pesam menos do que o corpo de uma única skill carregada. Segundo — e esta é a parte que os posts de listas ignoram — uma skill com uma descrição fraca está *instalada, mas é inalcançável*. O Claude não consegue associar uma tarefa a "Ajuda com coisas de frontend". As reclamações que enchem as threads do Reddit, do tipo "instalei vinte skills e nada mudou", geralmente são isso: os corpos estavam corretos, mas as descrições nunca deram ao modelo um motivo para abri-los.

• ~/.claude/skills/<skill-name>/SKILL.md: skills pessoais, disponíveis em todos os projetos que você abrir.
• .claude/skills/<skill-name>/SKILL.md: skills de projeto, commitadas no repo para que cada colaborador e cada sessão de agente as receba.
• Plugins: um plugin pode agrupar skills junto com comandos e agentes, que é como as equipes distribuem um conjunto em uma única instalação.

A localização no repo importa mais do que parece. Uma skill pessoal ajusta as suas sessões; uma commitada ajusta as sessões dos seus colegas e também as sessões do seu agente de CI. Qualquer coisa que codifique um contrato de projeto — como revisamos a UI, como escrevemos migrações, como aplicamos o design system — pertence ao .claude/skills/, ao lado do código que ela governa.

O Claude Code oferece três lugares para colocar conhecimento, e eles respondem a perguntas diferentes. O CLAUDE.md é sempre carregado: serve para restrições que se aplicam a cada solicitação, e cada linha nele é paga em cada prompt, por isso deve ser curto. Uma skill é carregada sob demanda: serve para procedimentos que são relevantes apenas às vezes, e pode ser longa porque não custa nada até ser ativada. Um subagente é um contexto inteiramente separado: serve para trabalhos cujo output intermediário poluiria a sua sessão.

A linha divisória para a taxonomia completa de arquivos, incluindo AGENTS.md e DESIGN.md, está em CLAUDE.md vs AGENTS.md vs SKILL.md vs DESIGN.md.

1. 1

   Comece por uma correção repetitiva

   Os melhores candidatos a skill são as coisas que você não para de digitar: o checklist de revisão que você cola, a sequência de deploy que você reexplica. Se você nunca precisou corrigir o agente sobre isso duas vezes, ainda não é necessária uma skill.

2. 2

   Escreva a descrição primeiro, como condições de gatilho

   Antes das instruções, escreva a frase que decide quando isso será carregado: os verbos e situações que uma requisição correspondente conteria. Se você não consegue nomear as situações, a skill não será ativada, e você descobrirá isso logo cedo.

3. 3

   Transforme o corpo em um procedimento executável

   Passos numerados, comandos exatos, caminhos de arquivos exatos. Referencie arquivos na pasta da skill para qualquer conteúdo longo. Um agente segue um procedimento com muito mais confiabilidade do que se baseia em uma 'vibe'.

4. 4

   Aponte para artefatos, não para adjetivos

   Uma skill que diz "mantenha a UI consistente" não faz nada. Uma skill que diz "leia o DESIGN.md e use apenas seus tokens" funciona, porque o julgamento é externalizado em um arquivo que o agente pode abrir. Coloque o conhecimento em um artefato e deixe a skill ser o ponteiro.

5. 5

   Teste perguntando, não invocando

   Não teste com uma invocação explícita; isso não prova nada sobre o gatilho. Formule uma requisição da maneira que você faria naturalmente e verifique se a skill é carregada. Se não for, a descrição, e não o corpo, é o que precisa de edição.

Design é o caso de uso perfeito para skills e a ilustração ideal da regra de artefatos mencionada acima. A Anthropic fornece uma skill de design de frontend para o Claude Code, e ela realmente melhora telas individuais; nós a testamos e escrevemos exatamente o que ela faz e o que falta. O que falta é a memória entre telas: a skill carrega bom gosto, não os seus valores, então a tela vinte se distancia da tela um. O bom gosto se generaliza; a identidade não.

A solução é o padrão do passo quatro: a skill permanece como um procedimento simples, e a identidade vive em um artefato, um DESIGN.md na raiz do repositório com tokens reais, escolhas de tipografia, regras de espaçamento e regras de 'não fazer'. A skill de auditoria de marca no topo desta página tem apenas doze linhas porque tudo o que ela impõe está definido naquele único arquivo. É isso que é um design system para um agente: não um plugin, mas um contrato legível.

npx --yes identityforge@latest install --client claude-code

O formato de skill deixou de ser específico do Claude de uma forma que impacta onde você investe seu tempo. O Codex da OpenAI detecta pastas SKILL.md em .agents/skills/ e ~/.agents/skills/ e as invoca com $; o Cursor adicionou Agent Skills com o mesmo carregamento sob demanda ao lado de suas Rules permanentes, e tem direcionado regras procedurais longas para skills. A convenção está convergindo para a mesma forma em todos os lugares: frontmatter que anuncia, um corpo que instrui e um carregamento que aguarda a relevância. Skills que você escreve baseadas em artefatos no seu repositório, em vez de peculiaridades de uma ferramenta, sobrevivem à rotatividade de ferramentas.