Skills — habilidades sob demanda

Skill é um conjunto de instruções que o Claude carrega só quando a tarefa pede. Diferente do CLAUDE.md (que entra toda sessão), a skill fica dormente até ser invocada.

Anatomia

Uma skill vive em ~/.claude/skills/<nome>/SKILL.md (global) ou <projeto>/.claude/skills/<nome>/SKILL.md (projeto). Pode ter arquivos auxiliares na mesma pasta.

Exemplo mínimo de SKILL.md:

---
name: gerar-migration
description: Cria migration Drizzle seguindo padrão do projeto. Use quando o usuário pedir pra criar, alterar ou dropar tabela/coluna.
---

# Como criar migration

1. Edita o schema em `src/db/schema.ts`
2. Roda `pnpm db:generate -- --name <nome_descritivo>`
3. Revisa o SQL gerado em `drizzle/`
4. Nunca edita migration já aplicada — cria uma nova

## Convenções de nome
- Tabelas: `snake_case`, plural (`users`, `order_items`)
- Colunas: `snake_case`, FK com sufixo `_id`

O frontmatter é o que importa pro roteamento:

name: identificador único
description: o modelo usa isso pra decidir se carrega a skill. Escreve pensando em “quando usar”

`disable-model-invocation`

Por padrão o Claude decide sozinho quando invocar a skill lendo a description. Se você quer invocar manualmente só:

---
name: deploy-producao
description: Faz deploy pra produção. Passos críticos, só executa quando pedido explicitamente.
disable-model-invocation: true
---

Agora só roda se você disser “usa a skill deploy-producao”. Bom pra coisa perigosa.

Skill vs CLAUDE.md

Regra de bolso:

CLAUDE.md: algo que vale em toda sessão (stack, convenções gerais)
Skill: procedimento específico que só importa em certa tarefa (gerar migration, escrever changelog, revisar PR)

Se você se pega escrevendo “quando for fazer X, segue esses passos” no CLAUDE.md, provavelmente é skill.

Quando NÃO usar skill

Regra de 1 linha (“sempre use pnpm”) — vai no CLAUDE.md
Coisa que muda toda hora — vira overhead de manter
Procedimento que você faz 1x por ano — documenta em README e chama à mão

Exemplo completo

Estrutura:

.claude/skills/changelog/
├── SKILL.md
└── template.md

SKILL.md:

---
name: changelog
description: Atualiza o CHANGELOG.md a partir dos commits desde a última tag. Use quando o usuário pedir pra preparar release ou atualizar changelog.
---

# Processo

1. Lê `template.md` pra formato
2. Roda `git log $(git describe --tags --abbrev=0)..HEAD --oneline`
3. Agrupa por tipo (feat, fix, chore)
4. Adiciona no topo do `CHANGELOG.md` com data de hoje
5. Não commita — deixa pro usuário revisar

O Claude carrega template.md só quando a skill roda. Sem poluir contexto o resto do tempo.

Dica prática

Começa pelas tarefas que você repete toda semana. Cada skill que você cria é uma dor que não volta.