Claude Code Skills: crie extensões próprias com ativação automática

Como criar um skill próprio para o Claude Code? Crie um arquivo SKILL.md em ~/.claude/skills/<name>/ (pessoal) ou em .claude/skills/<name>/ (no nível do projeto), com um frontmatter YAML contendo os campos name, description e allowed-tools, seguido do conteúdo em markdown com o seu conhecimento. O Claude usa raciocínio de LLM sobre essa descrição para ativar o skill automaticamente quando a sua tarefa combina com ela. Skills de projeto compartilhados via git não exigem nenhuma configuração dos seus colegas.

Três sessões seguidas, colei o mesmo checklist de segurança no Claude Code. Esse checklist trazia os padrões de vulnerabilidade específicos do nosso time: as verificações de IDOR ligadas ao desenho da nossa API, as regras de tratamento de sessão do nosso fluxo de autenticação, as regras de exposição de dados dos nossos campos com PII. Toda vez, o Claude aplicou tudo com perfeição. Toda vez, eu precisei lembrar de colar.

O momento em que você se pega reexplicando o mesmo contexto é o momento de criar um skill.

TL;DR

Skills são extensões invocadas pelo modelo — o Claude descobre e aplica cada uma automaticamente, conforme o contexto, sem que você precise chamá-la ¹. A chave de um skill confiável é o campo description: é por raciocínio de LLM, e não por correspondência de palavras-chave, que o Claude decide quando ativar cada skill ¹. Crie skills para conhecimento de domínio que vale entre sessões (padrões de segurança, estilo de código, regras de negócio). Não crie skills para tarefas pontuais — para isso existem os slash commands.

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

Quando vale a pena criar um skill

Nem todo prompt repetido merece um skill. O quadro de decisão:

Skills são conhecimento que o Claude tem sempre à mão. Slash commands são ações que você dispara explicitamente. Na dúvida entre os dois, pergunte-se: “o Claude deve aplicar isso automaticamente, ou eu é que decido quando rodar?”.

Um erro comum: criar um skill para algo que você faz uma vez por semana. Eu criei um skill git-rebase-helper que disparava em qualquer prompt ligado ao git — rebases, merges, cherry-picks, até git status. A descrição era ampla demais, poluía o contexto em 80% das sessões em que não fazia falta e competia com os outros skills pelo orçamento de contexto de 2% ¹. A solução foi apagar o skill e usar um slash command no lugar: /rebase, quando eu realmente precisava. Skills devem codificar conhecimento de domínio estável, não fluxos de trabalho ocasionais.

Tutorial: crie um skill de revisão de código

Passo 1: crie o diretório

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

Neste tutorial, vamos criar um skill pessoal:

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

Passo 2: escreva o SKILL.md com frontmatter

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

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

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

Outros campos úteis do 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 do isolamento” ¹. Use em skills de análise (revisão de código, auditoria de segurança), em que você quer um contexto limpo — e não em skills de conhecimento, que devem se misturar à conversa principal.

Passo 3: adicione recursos de apoio

Um skill pode referenciar outros arquivos do 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 esses arquivos 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, assim que o skill é ativado, usando as ferramentas normais de leitura de arquivos ¹. Mantenha o SKILL.md abaixo de 500 linhas e mova o material de referência detalhado para arquivos de apoio ³ — arquivos de skill mais curtos reduzem o custo de injeção de contexto e mantêm o Claude focado na tarefa atual.

Passo 4: teste a ativação

O skill entra em ação na próxima vez que você iniciar uma sessão do Claude Code. Para testar:

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

Há duas formas de verificar se o skill foi carregado ¹:

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

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

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

Passo 5: o passo decisivo — escrever a descrição

O campo description é a linha mais importante do seu skill. 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 injeta os dois no contexto do Claude. Quando você envia uma mensagem, o Claude decide se algum skill é relevante por raciocínio de modelo de linguagem — não por regex, não por correspondência de palavras-chave, não por similaridade de embeddings. A documentação oficial diz: “o Claude compara a sua tarefa com as descrições dos skills para decidir quais são relevantes. Se as descrições forem vagas ou se sobrepuserem, o Claude pode carregar o skill errado — ou deixar passar um que ajudaria” ¹.

Uma análise independente do código-fonte do Claude Code confirma o mecanismo: as descrições dos skills são injetadas em uma seção available_skills do prompt de sistema, e o modelo seleciona os skills relevantes no momento da invocação por compreensão de linguagem comum ⁴. Esse matching por LLM tem implicações importantes na forma de escrever descrições.

Descrição ruim:

description: Helps with code

O Claude não faz ideia de quando ativar isso. “Helps with code” combina com tudo e com nada — e, como o matching é raciocínio de LLM, descrições vagas geram ativação imprevisível.

Descrição um pouco melhor:

description: Review code for bugs and issues

Vaga demais. Que tipo de bug? Que tipo de problema? Quando o Claude deveria usar isso em vez da análise embutida dele?

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.

Essa descrição funciona porque traz: - O que ela faz: revisar código em busca de tipos específicos de problema - Quando usá-la: ao examinar mudanças, PRs e análise de qualidade - Frases-gatilho: review, audit, check — palavras que o usuário digita naturalmente

Uma restrição que vale conhecer: todas as descrições de skills dividem um orçamento de contexto que “escala dinamicamente em 2% da janela de contexto, com um valor de reserva de 16.000 caracteres” ¹. Se você tem muitos skills, mantenha cada descrição concisa — uma descrição prolixa toma o espaço das outras. Dá para alterar o orçamento pela variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET ², mas a solução melhor são descrições mais curtas e precisas.

Teste descrições diferentes. Abra uma sessão nova, peça ao Claude para revisar código e veja se o skill ativa. Se não ativar, acrescente mais frases-gatilho. Se ativar quando não deveria, deixe a descrição mais específica.

Passo 6: itere conforme o uso

Depois de uma semana de uso, você vai descobrir: - Padrões que o skill deveria checar e não checa — acrescente ao SKILL.md - Ativações falsas em tarefas sem relação — aperte a descrição, ou adicione disable-model-invocation: true e exija a invocação explícita /code-reviewer - Contexto faltando — acrescente arquivos de recursos de apoio - Restrições de ferramentas apertadas ou frouxas demais — ajuste o allowed-tools

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

Avançado: skills como biblioteca de prompts

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

~/.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 do conhecimento do seu time. Juntos, formam uma base de conhecimento da qual o Claude bebe automaticamente, conforme o contexto. Um desenvolvedor júnior recebe orientação de nível sênior sem precisar pedir.

Uma observação sobre a quantidade de skills: mais skills significam mais descrições competindo pelo orçamento de contexto ¹. Se você notar skills que não ativam, rode /context para checar se algum está sendo excluído. Priorize poucos skills bem descritos em vez de muitos skills vagos.

Compartilhando skills com o seu time

Skills pessoais (~/.claude/skills/) são só seus. Use para preferências pessoais, padrões experimentais ou conhecimento específico do seu jeito de trabalhar.

Skills de projeto (.claude/skills/ na raiz do repositório) são compartilhados 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 dão pull, eles recebem o skill automaticamente. Sem instalação, sem configuração. A distribuição por git é a forma mais eficaz de padronizar conhecimento em um time.

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

Principais conclusões

• Crie um skill quando você se pegar reexplicando contexto. Se você cola o mesmo checklist três vezes, aquilo deveria ser um skill.
• O campo description determina tudo. O Claude usa raciocínio de LLM para casar os seus pedidos com as descrições ¹. Invista mais tempo na descrição do que no conteúdo do skill.
• Use allowed-tools para conter efeitos colaterais. Skills somente de leitura devem ficar restritos a Read, Grep, Glob.
• Compartilhe skills de projeto via git. Distribuição de conhecimento no time com zero configuração ¹.
• Não abstraia demais. Um skill para cada micropadrão cria carga de manutenção e compete pelo orçamento de contexto. Crie skills para conhecimento estável, reutilizável e valioso o bastante para ser mantido.

Perguntas frequentes

O que são os skills do Claude Code?

Skills são extensões invocadas pelo modelo, guardadas como arquivos markdown, que o Claude descobre e aplica automaticamente conforme o contexto. Diferente dos slash commands, que você dispara explicitamente, um skill ativa quando o raciocínio de LLM do Claude determina que a sua tarefa atual combina com a descrição dele. Skills codificam conhecimento de domínio — padrões de segurança, regras de estilo de código, lógica de negócio — que persiste entre sessões, sem exigir que você reexplique o contexto toda vez.

Como criar um skill próprio para o Claude Code?

Crie um diretório em ~/.claude/skills/<name>/ para skills pessoais ou em .claude/skills/<name>/ para skills de projeto. Dentro dele, crie um arquivo SKILL.md com frontmatter YAML (contendo name, description e, opcionalmente, allowed-tools), seguido do conteúdo em markdown com o conhecimento que o Claude deve aplicar. O campo description é crítico — é sobre ele que o Claude aplica raciocínio de LLM para decidir quando ativar o skill. Veja o tutorial completo acima para o passo a passo.

Qual é a diferença entre skills do Claude Code e slash commands?

Skills se ativam sozinhos conforme o contexto — o Claude decide quando eles são relevantes por raciocínio de LLM sobre a descrição do skill. Slash commands são ações invocadas pelo usuário, que você dispara explicitamente digitando /command-name. Crie um skill quando o Claude precisar ter aquele conhecimento sempre disponível (conhecimento de domínio, padrões de qualidade). Crie um slash command quando você quiser decidir a hora de rodar a ação (scripts de deploy, fluxos pontuais).

Skills do Claude Code podem chamar outras ferramentas?

Podem, mas quem controla quais é você, pelo campo allowed-tools do frontmatter. Um skill somente de leitura, como um revisor de código, deve ficar restrito a Read, Grep, Glob para evitar efeitos colaterais indesejados. Se o allowed-tools for omitido, o skill pode usar qualquer ferramenta a que o Claude tenha acesso. Skills também podem definir os próprios hooks no frontmatter, ativos apenas enquanto o skill roda.

Por que o meu skill do Claude Code não ativa?

A causa mais comum é um campo description vago ou amplo demais. O Claude usa raciocínio de LLM — não correspondência de palavras-chave — para decidir se um skill é relevante para a sua tarefa atual. Se a descrição diz “helps with code”, o Claude não consegue distinguir esse caso de qualquer outra tarefa de programação. Deixe a descrição específica: nomeie os tipos exatos de problema, os cenários de gatilho e os verbos de ação que os usuários digitam naturalmente. Confira também o /context em uma sessão, para ver se o seu skill está sendo excluído pelo limite de 2% do orçamento de contexto. Quando muitos skills disputam espaço, alguns caem.

Onde ficam guardados os skills do Claude Code e como são compartilhados?

Skills ficam em quatro locais, de escopo crescente: pessoal (~/.claude/skills/<name>/SKILL.md), projeto (.claude/skills/<name>/SKILL.md), plugin e empresa (configurações gerenciadas). Skills pessoais valem para todos os seus projetos. Skills de projeto são compartilhados via git — quando os colegas dão pull, recebem o skill automaticamente, com zero configuração. Todas as descrições de skills dividem um orçamento de contexto de 2% da janela de contexto, então mantenha as descrições concisas se você tiver muitos skills.

Referências