Criando Skills Personalizadas para o Claude Code: Um Tutorial Completo

Em três sessões consecutivas, colei o mesmo checklist de segurança no Claude Code. O checklist continha os padrões de vulnerabilidade específicos da nossa equipe — as verificações de IDOR exclusivas do design da nossa API, as regras de tratamento de sessão do nosso fluxo de autenticação, as regras de exposição de dados para nossos campos de PII. Toda vez, o Claude os aplicava perfeitamente. Toda vez, eu precisava lembrar de colá-los.

O momento em que você se pega re-explicando o mesmo contexto é o momento em que deveria criar uma skill.

TL;DR

Skills são extensões invocadas pelo modelo — o Claude as descobre e aplica automaticamente com base no contexto, sem que você precise chamá-las explicitamente ¹. A chave para skills confiáveis é o campo description: o Claude usa raciocínio de LLM (não correspondência por palavras-chave) para decidir quando ativar cada skill ¹. Crie skills para conhecimento de domínio que se aplica entre sessões (padrões de segurança, estilo de código, regras de negócio). Não crie skills para tarefas pontuais — use comandos slash em vez disso.

Pré-requisitos: Familiaridade com o sistema de extensões do Claude Code. Para a comparação entre skills, comandos e subagentes, veja a seção de Skills do guia.

Quando Criar uma Skill

Nem todo prompt repetido merece uma skill. O framework de decisão:

Skills são para conhecimento que o Claude sempre tem disponível. Comandos slash são para ações que você aciona explicitamente. Se estiver decidindo entre os dois, pergunte: “O Claude deveria aplicar isso automaticamente, ou eu deveria decidir quando executar?”

Um erro comum: criar uma skill para algo que você faz uma vez por semana. Criei uma skill git-rebase-helper que se ativava em qualquer prompt relacionado a git — rebases, merges, cherry-picks, até git status. A descrição era ampla demais, poluía o contexto em 80% das sessões onde não era necessária e competia com outras skills pelo orçamento de 2% de contexto ¹. A solução foi deletar a skill e usar um comando slash: /rebase quando eu realmente precisava. Skills devem codificar conhecimento de domínio estável, não fluxos de trabalho ocasionais.

Tutorial: Crie uma Skill de Revisão de Código

Passo 1: Crie o diretório

Skills ficam em quatro locais possíveis, do escopo mais amplo ao mais restrito ¹:

Para este tutorial, vamos criar uma skill pessoal:

mkdir -p ~/.claude/skills/code-reviewer

Passo 2: Escreva o SKILL.md com frontmatter

Toda skill precisa de um arquivo SKILL.md com duas partes: frontmatter YAML (entre marcadores ---) que diz ao Claude quando usar a skill, e conteúdo em markdown com instruções que o Claude segue quando a skill é invocada ¹.

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

### Data Exposure
- PII masked in log output and error messages
- API responses don't leak internal IDs or stack traces
- Sensitive fields excluded from serialization defaults

Observe allowed-tools: Read, Grep, Glob — isso restringe a skill a operações somente leitura. O revisor de código pode examinar arquivos, mas não pode modificá-los. Restrições de ferramentas evitam que skills tenham efeitos colaterais indesejados.

Outros campos úteis de frontmatter além de name, description e allowed-tools ¹:

Uma ressalva da documentação oficial: context: fork “só faz sentido para skills com instruções explícitas que se beneficiam de isolamento” ¹. Use-o para skills de análise (revisão de código, auditoria de segurança) onde você quer um contexto limpo, não para skills de conhecimento que devem se integrar à conversa principal.

Passo 3: Adicione recursos de apoio

Skills podem referenciar arquivos adicionais no mesmo diretório ¹:

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Referencie-os a partir do SKILL.md com links relativos:

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for OWASP Top 10 checks.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for query optimization.

O Claude lê esses arquivos sob demanda quando a skill é ativada, usando ferramentas padrão de leitura de arquivos ¹. Mantenha o SKILL.md com menos de 500 linhas e mova material de referência detalhado para arquivos de apoio ³ — arquivos de skill mais curtos reduzem a sobrecarga de injeção de contexto e mantêm o Claude focado na tarefa atual.

Passo 4: Teste a ativação

A skill se ativa na próxima vez que você iniciar uma sessão do Claude Code. Teste-a:

# Ask Claude to review code — should trigger the skill automatically
claude "Review the authentication middleware in app/security/"

Verifique se a skill foi carregada usando um dos dois métodos ¹:

# In an interactive session, ask Claude directly:
> What skills are available?

# Or check the context budget for excluded skills:
> /context

Se a skill não ativar, o problema quase sempre está no campo description. Veja o Passo 5.

Passo 5: O passo crítico — escrevendo a descrição

O campo description é a linha mais importante da sua skill. Veja o que acontece por baixo dos panos: no início da sessão, o Claude Code extrai o name e a description de cada skill e os injeta no contexto do Claude. Quando você envia uma mensagem, o Claude usa raciocínio de modelo de linguagem — não regex, não correspondência por palavras-chave, não similaridade de embeddings — para decidir se alguma skill é relevante. A documentação oficial afirma: “O Claude compara sua tarefa com as descrições das skills para decidir quais são relevantes. Se as descrições forem vagas ou se sobrepuserem, o Claude pode carregar a skill errada — ou deixar passar uma que ajudaria” ¹.

Análises independentes do código-fonte do Claude Code confirmam o mecanismo: as descrições das skills são injetadas em uma seção available_skills do prompt do sistema, e o modelo usa compreensão de linguagem padrão para selecionar skills relevantes no momento da invocação ⁴. A correspondência baseada em LLM tem implicações importantes para como você escreve as descrições.

Descrição ruim:

description: Helps with code

O Claude não tem ideia de quando ativar isso. “Helps with code” corresponde a tudo e a nada — e como a correspondência é por raciocínio de LLM, descrições vagas criam ativação imprevisível.

Descrição melhor:

description: Review code for bugs and issues

Vaga demais. Que tipo de bugs? Que tipo de problemas? Quando o Claude deveria usar isso em vez da sua análise nativa?

Descrição eficaz:

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

A descrição eficaz funciona porque inclui: - O que faz: Revisar código para tipos específicos de problemas - Quando usar: Examinando mudanças, PRs, análise de qualidade - Frases gatilho: review, audit, check — palavras que o usuário naturalmente digita

Uma restrição a conhecer: todas as descrições de skills compartilham um orçamento de contexto que “escala dinamicamente a 2% da janela de contexto, com um fallback de 16.000 caracteres” ¹. Se você tem muitas skills, mantenha cada descrição concisa — uma descrição verbosa compete com outras skills por espaço limitado. Você pode sobrescrever o orçamento via a variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET ², mas a melhor solução são descrições mais curtas e precisas.

Teste diferentes descrições. Inicie uma sessão nova, peça ao Claude para revisar código e verifique se a skill ativa. Se não, adicione mais frases gatilho. Se ela ativa quando não deveria, torne a descrição mais específica.

Passo 6: Itere com base no uso

Após uma semana de uso, você vai descobrir: - Padrões que a skill deveria verificar, mas não verifica — adicione-os ao SKILL.md - Ativações falsas em tarefas não relacionadas — refine a descrição, ou adicione disable-model-invocation: true e exija invocação explícita via /code-reviewer - Contexto faltando — adicione arquivos de recursos de apoio - Restrições de ferramentas muito rígidas ou muito frouxas — ajuste allowed-tools

Skills são documentos vivos. A primeira versão nunca é a versão final.

Avançado: Skills como uma Biblioteca de Prompts

Além de skills com propósito único, a estrutura de diretórios funciona como uma biblioteca organizada de prompts:

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Cada skill codifica uma faceta diferente da expertise da sua equipe. Juntas, formam uma base de conhecimento da qual o Claude extrai automaticamente com base no contexto. Um desenvolvedor júnior recebe orientação de nível sênior sem precisar pedir.

Uma nota sobre a quantidade de skills: Mais skills significam mais descrições competindo pelo orçamento de contexto ¹. Se você notar que skills não estão ativando, execute /context para verificar se alguma está sendo excluída. Priorize menos skills bem descritas em vez de muitas vagas.

Compartilhando Skills com Sua Equipe

Skills pessoais (~/.claude/skills/) são somente suas. Use para preferências pessoais, padrões experimentais ou expertise específica do seu fluxo de trabalho.

Skills de projeto (.claude/skills/ na raiz do repositório) são compartilhadas via git ¹:

# Create project-level skill
mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...

# Commit and push
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

Quando os colegas de equipe fizerem pull, eles recebem a skill automaticamente. Sem instalação, sem configuração. A distribuição via git é a forma mais eficaz de padronizar expertise em uma equipe.

Diretrizes para skills compartilhadas: - Mantenha skills de projeto focadas em conhecimento de domínio (regras de negócio, padrões de arquitetura) - Mantenha skills pessoais para preferências de fluxo de trabalho (formatação, estilo de commit) - Documente por que a skill existe em um comentário no topo do SKILL.md - Revise mudanças em skills em PRs como qualquer outro código

Pontos-Chave

• Crie uma skill quando se pegar re-explicando contexto. Se você cola o mesmo checklist três vezes, deveria ser uma skill.
• O campo description determina tudo. O Claude usa raciocínio de LLM para comparar suas solicitações com as descrições ¹. Invista mais tempo na descrição do que no conteúdo da skill.
• Use allowed-tools para restringir efeitos colaterais. Skills somente leitura devem ser restritas a Read, Grep, Glob.
• Compartilhe skills de projeto via git. Distribuição de conhecimento da equipe com zero configuração ¹.
• Não abstraia demais. Uma skill para cada micropadrão cria carga de manutenção e compete pelo orçamento de contexto. Crie skills para expertise que seja estável, reutilizável e valiosa o suficiente para manter.

Referências