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

O problema de repetir tudo

Já teve que explicar a mesma coisa para alguém vinte vezes? Agora 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á te disse que usa o formato tipo: descrição.” “Que não adicione emojis, cara!”

Esse era meu dia a dia até descobrir os Skills. Em outras palavras: 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 se lembrar de invocar o comando. Se tem um skill que diz “usar quando o usuário terminar uma tarefa e houver mudanças sem commit”, o Claude vai fazer sozinho.

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

Onde vivem

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

Se quiser que só você use o skill, coloque no seu home. Se quiser que toda a equipe tenha, faça commit no repo. Simples assim.

Anatomia de um Skill

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

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

# Instruções

O que o Claude deve fazer quando invocar este skill.

Isso é 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. Só minúsculas, números e hífens (máx. 64 caracteres). Deve coincidir com o nome do arquivo ou diretório.

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

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.

# 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.

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 só de leitura ou seguros.

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

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

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

---
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 se contamina.

context: fork

Útil para operações complexas de vários passos onde você não quer encher o chat de ruído.

agent

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

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.

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.

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.

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

---
name: security-audit
description: >
  Auditoria de segurança OWASP. Usar quando o usuário pedir para revisar
  segurança, buscar 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)

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

Analisa o código e sugere melhorias.

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

Skill determinístico (script disfarçado)

---
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** fixes 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

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

## Passo 1: Verificar branch

```bash
git branch --show-current

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

Passo 2: Estado limpo

git status --porcelain

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

Passo 3: Bump + push

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

Aqui há lógica de branches, mas continua sendo 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 que o skill só execute:

.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 vive no Bash/Python onde pertence, e o skill é só 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.

---
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 diz "commit", "commita", "salva as mudanças"
- O usuário termina uma tarefa e há 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

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

Se alguma falhar, 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 é o que permite a auto-invocação. O Claude lê isso e pensa: "ah, o usuário acabou de dizer 'já está', há mudanças pendentes, deveria usar este skill".

## Outro exemplo: arquivamento de tarefas

Se usar um arquivo `TASKS.md` para rastrear 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 superar os 20K tokens.
---

# Archive Tasks

## Quando Usar (Automático)

- TASKS.md tem mais de 50 tarefas completadas `[x]`
- TASKS.md supera os 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 se lembrar. O Claude vê que o TASKS.md está enorme e age.

Dicas para escrever bons skills

1. Descrições específicas

# 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

## Quando Usar Este Skill (Automático)

Aplicar automaticamente quando:
- O usuário diz "commit" ou "salva as mudanças"
- Há mudanças staged prontas
- O usuário termina 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, diga claramente:

## 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:

---
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:

---
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 com os commands legacy

Os commands continuam funcionando, mas os skills são estritamente melhores. Se tem 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 se versionam com seu código. Se trabalha em equipe, todos têm os mesmos skills. Se muda algo, fica no histórico do git.

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

Agora se me dão 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 precisar: desde “analisa isso” até scripts disfarçados de prosa. Se precisar de lógica complexa, invoque scripts externos. Vivem em .claude/skills/ e se versionam com seu código.

Este artigo foi escrito originalmente em espanhol e traduzido com a ajuda de IA.