Skills no Claude Code: Ensinando trucos novos ao cão velho

O problema de repetir tudo

Já teve que explicar a mesma coisa para alguém vinte vezes? Pois imagine isso, mas com um robô que ainda por cima perde a memória a cada poucas horas.

“Não, Claude, o commit tem que passar nos testes primeiro.” “Claude, já disse que usa o formato tipo: descrição.” “Para de adicionar emojis, cara!”

Esse era o meu dia a dia até descobrir os Skills. Falando sem rodeios: são instruções que você escreve uma vez e o Claude segue para sempre. Como treinar um cachorro, mas sem as rações.

O que são os Skills

Desde a versão 2.1.3, o Claude Code fundiu os antigos slash commands com algo mais poderoso: os Skills. São arquivos Markdown com instruções que o Claude pode executar de duas formas:

1. Manualmente: quando você escreve /meu-skill
2. Automaticamente: quando o Claude detecta que deveria usá-lo

Esse segundo ponto é a mágica. Você não precisa mais lembrar de invocar o comando. Se tiver um skill que diz “usar quando o usuário terminar uma tarefa e houver mudanças sem commit”, o Claude fará sozinho.

É como ter um mordomo que sabe quando recolher a mesa sem você pedir.

Onde vivem

~/.claude/skills/          # Pessoais (todos seus projetos)
.claude/skills/            # Do projeto (compartilhados com a equipe)
~/.claude/commands/        # Legacy, ainda funciona
.claude/commands/          # Legacy, ainda funciona

Se quiser que só você use o skill, coloca na sua home. Se quiser que toda a equipe tenha, commita no repo. Simples assim.

Anatomia de um Skill

Um skill é um arquivo Markdown com um frontmatter YAML e depois o conteúdo:

1
2
3
4
5
6
7
8

---
name: meu-skill
description: Breve descrição do que faz
---

# Instruções

O que o Claude deve fazer quando este skill for invocado.

Esse é o mínimo. Mas o frontmatter tem várias outras opções que vale a pena conhecer.

Campos obrigatórios

name

O identificador do skill. Apenas minúsculas, números e hífens (máx. 64 caracteres). Deve coincidir com o nome do arquivo ou diretório.

1
2

name: check-types      # ✓ válido
name: Check_Types      # ✗ inválido (maiúsculas e underline)

description

Este é o campo mais importante. O Claude usa para duas coisas:

1. Decidir quando auto-invocar o skill
2. Entender o que deve fazer

Máximo 1024 caracteres. Inclua palavras-chave que o usuário diria naturalmente.

1
2
3
4
5
6
7
8

# Ruim - muito vago
description: Faz coisas com commits

# Bom - específico e com triggers
description: >
  Cria commits git verificando type-check, lint e testes.
  Usar quando o usuário disser "commit", "commita", ou terminar uma tarefa
  com mudanças pendentes.

Campos opcionais

model

Força um modelo específico para este skill. Útil para tarefas que requerem mais capacidade.

1
2
3

model: opus    # Para auditorias de segurança, refactoring complexo
model: sonnet  # Equilíbrio entre capacidade e custo
model: haiku   # Para tarefas simples e rápidas

Se não especificar, usa o modelo da conversa atual.

allowed-tools

Restringe quais ferramentas o Claude pode usar. Crítico para skills apenas de leitura ou seguros.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Só pode ler, não modificar
allowed-tools:
  - Read
  - Grep
  - Glob

# Só pode executar comandos específicos
allowed-tools:
  - Bash(git:*)      # Apenas comandos git
  - Bash(uv:*)       # Apenas comandos uv
  - Read

Exemplo prático: um skill de análise que NÃO deve mexer em nada:

1
2
3
4
5
6
7
8

---
name: analyze-deps
description: Analisa dependências do projeto sem modificar nada
allowed-tools:
  - Read
  - Grep
  - Bash(uv pip list:*)
---

context: fork

Executa o skill em um sub-agente isolado com seu próprio contexto. O histórico da conversa principal não fica poluído.

1

context: fork

Útil para operações complexas de vários passos onde você não quer encher o chat de informações desnecessárias.

agent

Só funciona com context: fork. Define que tipo de agente executa o skill.

1
2
3

context: fork
agent: Explore    # Agente de exploração rápida
agent: Plan       # Agente de planejamento

user-invocable

Controla se aparece no menu de / (slash commands). Por padrão é true.

1

user-invocable: false  # Oculto do menu, mas Claude pode usar

Útil para skills internos que só deveriam ativar automaticamente.

disable-model-invocation

Bloqueia que o Claude invoque o skill por conta própria. Só você pode ativar com /nome.

1

disable-model-invocation: true

Útil para operações destrutivas ou custosas que requerem decisão humana explícita.

hooks

Define hooks que são executados durante o ciclo de vida do skill. Suporta PreToolUse, PostToolUse e Stop.

1
2
3
4
5
6
7

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-input.sh $TOOL_INPUT"
          once: true

Variáveis de substituição

Dentro do conteúdo do skill você pode usar:

Tabela resumo

Exemplo completo

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

---
name: security-audit
description: >
  Auditoria de segurança OWASP. Usar quando o usuário pedir para revisar
  segurança, procurar vulnerabilidades, ou antes de fazer deploy para produção.
model: opus
allowed-tools:
  - Read
  - Grep
  - Glob
user-invocable: true
disable-model-invocation: true  # Só manual, é custoso
---

# Auditoria de Segurança

[instruções...]

Para a referência completa, consulte a documentação oficial de Agent Skills.

Texto livre ou código determinístico?

Esta é a pergunta de um milhão: se os skills são Markdown, significa que o Claude sempre “interpreta” o que você escreve? Posso fazer algo realmente previsível?

A resposta curta: os skills são tão determinísticos quanto você os escrever.

Pense em um espectro:

Vago/Flexível ──────────────────────────► Determinístico
"revisa o código"        "executa estes 3 comandos em ordem"

Skill flexível (Claude decide)

1
2
3
4
5
6

---
name: review
description: Revisa o código em busca de problemas
---

Analise o código e sugira melhorias.

Aqui o Claude tem liberdade total. Pode olhar o que quiser, sugerir o que achar melhor. Útil para exploração, perigoso para processos críticos.

Skill determinístico (script disfarçado)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

---
name: check
description: Verificações de qualidade obrigatórias
allowed-tools:
  - Bash
---

Executar **exatamente** estes comandos em ordem:

1. `uv run basedpyright src/`
2. `uv run ruff check src/`
3. `uv run pytest -x`

## Regras

- **NÃO interpretar** os erros criativamente
- **NÃO continuar** se algum falhar
- **NÃO sugerir** correções automaticamente
- Reportar apenas: ✓ passou / ✗ falhou com output

Isso é basicamente um script de 3 linhas. O Claude não tem margem para ser criativo. Executa, reporta, ponto.

Skill com lógica condicional

1
2
3
4
5
6
7
8
9

---
name: release
description: Prepara release do projeto
---

## Passo 1: Verificar branch

```bash
git branch --show-current

• Se NÃO for main → ABORTAR com “Apenas a partir da main”

Passo 2: Estado limpo

1

git status --porcelain

• Se houver output → ABORTAR com “Mudanças sem commit”

Passo 3: Bump + push

1
2

uv run bump2version patch
git push && git push --tags

Aqui há lógica de branches, mas ainda é determinístico: as condições estão explícitas.

### Skill que invoca um script real

Se precisar de lógica complexa de verdade (loops, parsing, APIs), coloque o código em um script e faça o skill apenas executá-lo:

.claude/skills/deploy/ ├── SKILL.md └── deploy.sh

**SKILL.md:**
```markdown
---
name: deploy
description: Faz deploy para produção
---

Executar:

```bash
bash .claude/skills/deploy/deploy.sh

Reportar o resultado. NÃO modificar o script.

**deploy.sh:**
```bash
#!/bin/bash
set -e
uv run pytest || exit 1
hugo --minify
rsync -avz public/ user@server:/var/www/

O melhor dos dois mundos: a lógica complexa fica em Bash/Python onde pertence, e o skill é apenas o gatilho.

Quando usar cada abordagem

Exemplo real: o skill de commit

Este é o que mais uso. Antes tinha que lembrar: “ok, executa os testes, depois o linter, depois o type-check, e só então commita”. Agora simplesmente digo “commita” e o Claude faz tudo sozinho.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

---
name: commit
description: Cria commits git com verificação obrigatória de qualidade.
  Executa type-check, lint e testes antes de commitar.
---

# Commit

## Quando Usar (Automático)

Aplicar quando:
- O usuário disser "commit", "commita", "salva as mudanças"
- O usuário terminar uma tarefa e houver mudanças sem commit

## Proibido

- Commitar sem executar verificações
- Pedir confirmação (simplesmente faça)
- Adicionar Co-Authored-By
- Usar emojis em mensagens de commit

## Processo

### Fase 1: Detectar mudanças

```bash
git diff --name-only HEAD

Fase 2: Verificações OBRIGATÓRIAS

1
2
3

uv run basedpyright src/
uv run ruff check src/
uv run pytest

Se falhar alguma, NÃO continuar.

Fase 3: Criar commit

1. git add -A
2. Analisar mudanças
3. Gerar mensagem: tipo: descrição
4. git commit

Vê a seção "Quando Usar"? É isso que permite a auto-invocação. O Claude lê isso e pensa: "ah, o usuário acabou de dizer 'pronto', há mudanças pendentes, deveria usar este skill".

## Outro exemplo: arquivamento de tarefas

Se usar um arquivo `TASKS.md` para acompanhar o que faz (eu fazia antes do Beads), este skill limpa as tarefas completadas automaticamente:

```markdown
---
name: archive-tasks
description: Arquiva tarefas completadas de TASKS.md para TASKS-DONE.md.
  Usar automaticamente quando TASKS.md tiver muitas tarefas completadas
  ou ultrapassar 20K tokens.
---

# Archive Tasks

## Quando Usar (Automático)

- TASKS.md tem mais de 50 tarefas completadas `[x]`
- TASKS.md ultrapassa 20.000 tokens
- O usuário menciona que TASKS.md está muito grande

## Processo

1. Ler `docs/llm/TASKS.md`
2. Identificar tarefas completadas (`[x]`)
3. Mover para `docs/llm/TASKS-DONE.md` com data
4. Eliminar de TASKS.md
5. Reportar quantas foram arquivadas

## Regras

- **NÃO eliminar** tarefas pendentes `[ ]`
- **PRESERVAR** o contexto (seção pai)
- **ADICIONAR** data de arquivamento

O legal é que você não precisa lembrar. O Claude vê que TASKS.md está enorme e age.

Dicas para escrever bons skills

1. Descrições específicas

1
2
3
4
5
6

# Ruim
description: Faz coisas com commits

# Bom
description: Cria commits git verificando type-check, lint e testes.
  Bloqueia se houver erros.

2. Define quando aplicar

1
2
3
4
5
6

## Quando Usar Este Skill (Automático)

Aplicar automaticamente quando:
- O usuário disser "commit" ou "salva as mudanças"
- Houver mudanças staged prontas
- O usuário terminar uma tarefa

3. Seja explícito com as proibições

O Claude tende a querer ser educado e pedir confirmação. Se não quiser isso, fale claramente:

1
2
3
4
5

## Proibido

- Pedir confirmação (JAMAIS)
- Adicionar Co-Authored-By
- Usar emojis

4. Use model: opus para o importante

Se o skill faz algo crítico (auditoria de segurança, refactoring complexo), force o modelo mais capaz:

1
2
3
4
5

---
name: owasp
description: Auditoria de segurança OWASP
model: opus
---

5. Restrinja ferramentas se necessário

Às vezes você quer um skill que só leia, sem modificar nada:

1
2
3
4
5
6
7
8

---
name: readonly-analysis
description: Analisa código sem modificá-lo
allowed-tools:
  - Glob
  - Grep
  - Read
---

Skills simples vs complexos

Um skill simples é um só arquivo:

.claude/skills/review.md

Um skill complexo é um diretório com recursos:

.claude/skills/deploy/
├── SKILL.md                 # Instruções
├── templates/
│   └── k8s-deployment.yaml
└── scripts/
    └── healthcheck.sh

O Claude pode ler os arquivos do diretório como contexto adicional.

O que eu uso

A diferença para os commands legacy

Os commands ainda funcionam, mas os skills são estritamente melhores. Se tiver commands antigos, não precisa migrar, mas para coisas novas use skills.

Conclusão

Os skills são basicamente programação, mas em linguagem natural. Você define o que quer que aconteça, quando, e com quais restrições. O Claude faz o resto.

O melhor é que eles são versionados com seu código. Se trabalha em equipe, todos têm os mesmos skills. Se mudar algo, fica no histórico do git.

Vale o esforço de escrevê-los? Se repetir a mesma coisa mais de três vezes, com certeza. Cada skill que escreve é uma conversa que não precisará ter nunca mais.

Agora me deem licença, preciso ensinar ao Claude que “refatorar” não significa “reescrever tudo do zero”.

TL;DR: Os skills são instruções em Markdown que o Claude Code executa manual ou automaticamente. Podem ser tão flexíveis ou determinísticos quanto você precisar: desde “analise isso” até scripts disfarçados de prosa. Se precisar de lógica complexa, invoque scripts externos. Ficam em .claude/skills/ e são versionados com seu código.