Se você usa o Claude Code há algum tempo, provavelmente já se pegou digitando a mesma instrução várias vezes. “Explica o código usando diagramas ASCII.” “Faz o commit seguindo o padrão Conventional Commits.” “Verifica se o PR bate com nossas convenções de API.” Toda semana, o mesmo prompt.

Skills resolvem exatamente isso — e vão além do que parece à primeira vista.

O Que São Skills (e Por Que Não São Só Atalhos)

Uma skill é um arquivo SKILL.md que você cria com instruções para o Claude. A partir daí, ela vira um comando /nome-da-skill que você pode invocar diretamente — ou que o Claude pode acionar automaticamente quando o contexto da conversa bater com a descrição da skill.

Esse segundo ponto é o que separa skills de simples aliases. O Claude lê as descrições das suas skills em segundo plano e decide qual aplicar. Você não precisa lembrar de invocar /explain-code toda vez que perguntar como algo funciona — se a descrição estiver bem escrita, ele vai usar a skill sozinho.

Skills seguem o padrão aberto Agent Skills, o que significa que funcionam além do Claude Code. Mas é dentro do Claude Code que elas chegam ao potencial máximo, com recursos como injeção dinâmica de contexto, execução em subagente isolado e controle fino de quem pode invocar o quê.

Nota sobre comandos customizados: se você já usava .claude/commands/deploy.md, não precisa migrar nada. Comandos customizados continuam funcionando e usam a mesma sintaxe. Skills adicionam recursos extras em cima disso — arquivos de suporte, controle de invocação, execução em fork. Se está criando algo novo, use skills.

Criando Sua Primeira Skill

Vamos criar do zero uma skill útil: um revisor de Pull Requests que busca o diff real via GitHub CLI e entrega um resumo estruturado.

Passo 1 — Escolha onde a skill vai viver

Skills podem existir em três escopos:

Para skills que você quer em todo lugar (padrões de commit, estilo de explicação, etc.), use o escopo pessoal. Para convenções específicas de um projeto (arquitetura da empresa, padrões de API internos), use o escopo do projeto e comite junto com o código.

# Skill pessoal — disponível em qualquer projeto
mkdir -p ~/.claude/skills/review-pr

# Skill de projeto — fica no repositório
mkdir -p .claude/skills/review-pr

Passo 2 — Escreva o SKILL.md

Todo skill precisa de um SKILL.md. A estrutura é simples: frontmatter YAML entre --- no topo, seguido das instruções em Markdown.

---
name: review-pr
description: Revisa um Pull Request buscando o diff atual. Use quando o usuário pedir para revisar, analisar ou dar feedback sobre um PR.
context: fork
agent: Explore
allowed-tools: Bash(gh *)
disable-model-invocation: true
---

# Revisão de PR

## Contexto atual
- Diff do PR: !`gh pr diff`
- Comentários existentes: !`gh pr view --comments`
- Arquivos alterados: !`gh pr diff --name-only`
- Informações gerais: !`gh pr view`

## Sua tarefa

Revise este Pull Request e entregue um relatório estruturado com:

1. **Resumo** — o que essa mudança faz em 2-3 frases
2. **Pontos positivos** — o que está bem feito
3. **Problemas** — bugs potenciais, violações de padrão, code smells
4. **Sugestões** — melhorias concretas (com exemplos de código quando relevante)
5. **Veredicto** — Aprovado / Aprovado com ressalvas / Precisa de revisão

Seja direto. Não elogie o óbvio.

Passo 3 — Teste

# Invocação direta
/review-pr

# Passando o número do PR como argumento
/review-pr 142

Frontmatter: O Que Cada Campo Faz

O frontmatter é onde você configura o comportamento da skill. Nenhum campo é obrigatório — mas description é fortemente recomendado, porque é o que o Claude usa para decidir quando aplicar a skill automaticamente.

---
name: minha-skill          # Nome do comando /minha-skill (padrão: nome do diretório)
description: O que faz e quando usar. Claude usa isso para decidir se ativa automaticamente.
argument-hint: [arquivo] [formato]   # Mostrado no autocomplete
disable-model-invocation: true       # true = só você invoca, nunca o Claude automaticamente
user-invocable: false                # false = esconde do menu /, Claude ainda pode usar
allowed-tools: Read, Grep, Glob      # Ferramentas liberadas sem pedir permissão
model: claude-opus-4-6               # Modelo específico para essa skill
effort: high                         # low | medium | high | max (só Opus 4.6)
context: fork                        # Executa em subagente isolado
agent: Explore                       # Tipo de subagente (se context: fork)
paths: src/**/*.ts, lib/**/*.ts      # Ativa automaticamente só para esses arquivos
---

Controle de invocação: quem pode usar o quê

Esse é o campo que mais gente ignora e que mais gera problema depois.

A regra prática é simples: se a skill tem efeitos colaterais (deploy, commit, envio de mensagem, chamada de API externa), use disable-model-invocation: true. Você não quer que o Claude decida fazer um deploy porque o código “parece pronto”.

---
name: deploy
description: Faz deploy da aplicação para produção
disable-model-invocation: true
---

Deploy $ARGUMENTS para produção:
1. Rode os testes
2. Build da aplicação
3. Push para o target de deploy
4. Verifique se o health check passou

Argumentos: Passando Parâmetros para a Skill

Skills aceitam argumentos via placeholder $ARGUMENTS. Quando você escreve /fix-issue 123, o 123 substitui $ARGUMENTS no conteúdo da skill antes de chegar ao Claude.

---
name: fix-issue
description: Corrige uma issue do GitHub pelo número
disable-model-invocation: true
argument-hint: <número-da-issue>
---

Corrija a issue #$ARGUMENTS seguindo os padrões de código do projeto.

1. Leia a descrição da issue
2. Entenda o que precisa ser feito
3. Implemente a correção
4. Escreva os testes necessários
5. Crie um commit com mensagem descritiva

Para acessar argumentos individuais por posição, use $ARGUMENTS[0], $ARGUMENTS[1], ou a forma curta $0, $1:

---
name: migrate-component
description: Migra um componente entre frameworks
argument-hint: <componente> <de> <para>
---

Migre o componente $0 de $1 para $2.

Preserve todo o comportamento existente e os testes.
Adapte a sintaxe para os idiomas de $2 sem mudar a lógica de negócio.

Invocar /migrate-component SearchBar React Vue substitui $0 por SearchBar, $1 por React e $2 por Vue.

Injeção Dinâmica de Contexto

Esse é o recurso mais poderoso — e menos conhecido — das skills. A sintaxe !`comando` executa um shell command antes da skill ser enviada ao Claude. O output substitui o placeholder no texto.

---
name: contexto-sprint
description: Carrega o contexto do sprint atual do Jira
user-invocable: false
---

## Contexto atual do projeto

Sprint ativo: !`jira sprint list --current --format json | jq '.name'`
Issues em progresso: !`jira issue list --status "In Progress" --format table`
Última build: !`cat .ci/last-build.json`
Testes com falha: !`cat .ci/failed-tests.txt 2>/dev/null || echo "Nenhum"`

Use esse contexto para responder perguntas sobre o estado atual do projeto.

Quando essa skill ativa, cada !`comando` roda imediatamente no shell, o output substitui o placeholder, e o Claude recebe o texto já renderizado com dados reais. Ele não vê os comandos — só os resultados.

Outros usos práticos:

# Data e hora atual
Hoje: !`date "+%d/%m/%Y %H:%M"`

# Versão do projeto
Versão: !`cat package.json | jq -r '.version'`

# Branch atual
Branch: !`git branch --show-current`

# Ambiente de execução
Ambiente: !`echo $NODE_ENV`

Arquivos de Suporte

Skills são um diretório, não um arquivo único. Isso permite organizar material de referência sem encher o SKILL.md principal.

minha-skill/
├── SKILL.md              # Instruções principais (obrigatório)
├── conventions.md        # Convenções de código — carregado quando precisar
├── examples/
│   └── good-pr.md        # Exemplo de PR bem escrito
└── scripts/
    └── validate.sh       # Script que o Claude pode executar

No SKILL.md, você referencia esses arquivos para que o Claude saiba que existem:

## Recursos adicionais

- Para convenções completas de código: [conventions.md](conventions.md)
- Para ver exemplos de bom PR: [examples/good-pr.md](examples/good-pr.md)
- Script de validação disponível em: scripts/validate.sh

O Claude só carrega esses arquivos quando precisar — não tudo de uma vez. Isso mantém o contexto limpo e a skill rápida. Mantenha o SKILL.md abaixo de 500 linhas. Se passou disso, está na hora de separar em arquivos de suporte.

Execução em Subagente (context: fork)

Com context: fork, a skill roda em um contexto completamente isolado, sem acesso ao histórico da conversa. É ideal para tarefas de pesquisa pesada, análise de codebase ou qualquer coisa que não precisa do contexto conversacional.

---
name: auditoria-seguranca
description: Audita o código em busca de vulnerabilidades de segurança
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
disable-model-invocation: true
---

Realize uma auditoria de segurança completa em $ARGUMENTS (ou no projeto inteiro se não especificado).

Procure por:
- Injeção de SQL e command injection
- Secrets hardcoded (chaves de API, senhas, tokens)
- Dependências com CVEs conhecidos (verifique package.json/requirements.txt)
- Endpoints sem autenticação
- Inputs não sanitizados

Entregue um relatório com severidade (crítica / alta / média / baixa) para cada achado.

O campo agent define qual tipo de subagente executa a skill. As opções built-in são Explore (ótimo para leitura de código, sem edição), Plan (arquitetura e planejamento) e general-purpose. Você também pode referenciar subagentes customizados definidos em .claude/agents/.

Boas Práticas

Depois de criar algumas skills, alguns padrões ficam claros:

Escreva descriptions como se fosse para um colega. O Claude usa o campo description para decidir quando ativar a skill. Se a descrição for vaga (“útil para código”), vai ativar quando não deve ou nunca ativar. Seja específico sobre o gatilho: “Use quando o usuário pedir para explicar como algo funciona, ensinar sobre o codebase, ou perguntar ‘como isso funciona?'”

Separe skills de referência de skills de ação. Skills de referência adicionam conhecimento ao contexto atual (convenções de API, padrões do projeto, documentação). Skills de ação executam algo com efeito colateral (commit, deploy, envio de mensagem). As primeiras podem ter user-invocable: false e serem carregadas automaticamente. As segundas devem ter disable-model-invocation: true sempre.

Use paths para skills específicas de contexto. Se você tem uma skill que só faz sentido para arquivos TypeScript do frontend, configure paths: src/frontend/**/*.tsx. O Claude vai ativá-la automaticamente só quando trabalhar com esses arquivos.

---
name: react-patterns
description: Padrões de componentes React para o projeto
paths: src/frontend/**/*.tsx, src/frontend/**/*.ts
user-invocable: false
---

Ao criar ou modificar componentes React neste projeto:
- Use sempre hooks funcionais, nunca class components
- Prefira composição a herança
- Extraia lógica complexa para custom hooks em src/frontend/hooks/
- Siga o padrão de arquivo: types → hooks → component → exports

Não tente fazer uma skill fazer tudo. Uma skill de 800 linhas que cobre deploy, testes, PR e notificação é difícil de manter e vai ativar no momento errado. Quebre em skills menores com responsabilidades claras.

Versione as skills do projeto junto com o código. Skills em .claude/skills/ que você commita são parte do onboarding do time. Um dev novo clona o repositório e já tem os padrões de commit, o template de PR review e as convenções de código disponíveis como skills.

Casos de Uso que Valem a Pena

Algumas skills que viram padrão rapidamente:

Commit padronizado:

---
name: commit
description: Cria um commit seguindo Conventional Commits
disable-model-invocation: true
---
Crie um commit com as mudanças staged seguindo o padrão Conventional Commits.
Branch atual: !`git branch --show-current`
Mudanças staged: !`git diff --staged --stat`

Use o tipo correto (feat, fix, chore, docs, refactor, test) e escreva a mensagem em inglês.

Geração de changelog:

---
name: changelog
description: Gera changelog baseado nos commits desde a última tag
disable-model-invocation: true
argument-hint: [versão]
---
Gere o changelog para a versão $ARGUMENTS baseado nos commits abaixo.
Última tag: !`git describe --tags --abbrev=0`
Commits desde a última tag: !`git log $(git describe --tags --abbrev=0)..HEAD --oneline`

Agrupe por tipo (Features, Bug Fixes, Breaking Changes). Formato Markdown.

Detector de code smell:

---
name: smell-check
description: Detecta code smells no código alterado recentemente
context: fork
agent: Explore
---
Analise os arquivos alterados recentemente e identifique code smells.
Arquivos modificados: !`git diff --name-only HEAD~5`

Foque em: funções muito longas, alto acoplamento, nomes pouco descritivos, duplicação de lógica.

Depurando Skills que Não Funcionam

Se a skill não ativa quando você espera:

1. Verifique se a description inclui palavras que correspondem ao que você costuma dizer
2. Digite “Quais skills estão disponíveis?” no Claude — ele vai listar as que conhece
3. Invoque diretamente com /nome-da-skill para confirmar que existe
4. Se tem muitas skills, algumas podem estar sendo excluídas por limite de contexto — rode /context para verificar

Se a skill ativa quando não deveria, torne a description mais específica ou adicione disable-model-invocation: true. Se quiser aumentar o orçamento de contexto para skills (padrão é 2% da janela de contexto), defina a variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET.

O que torna skills úteis de verdade não é o recurso em si — é a disciplina de criar uma vez e não precisar repetir. Cada skill que você escreve é uma convenção que vira automática, um padrão que nunca precisa ser lembrado, um atalho que todo o time passa a ter. Vale o investimento.

A documentação completa está em code.claude.com/docs/en/skills.

👉 Leia também: O Documento de Uma Página que Faz Qualquer IA Responder 10x Melhor