Como criar skills personalizadas para o Claude Code
Pela equipe editorial do Kitbay ·
Para criar uma skill personalizada para o Claude Code, crie uma pasta com o nome da skill em ~/.claude/skills/ (ou em .claude/skills/ dentro de um projeto), adicione um arquivo SKILL.md com name, description e as suas instruções e teste pedindo aquela tarefa ou digitando /skill-name. Depois, a skill-creator da Anthropic pode ajudar você a avaliar e ajustar a skill.
Se o formato for novo para você, leia antes o que é uma skill do Claude. Este guia mostra os passos práticos.
Passo 1: escolha uma única tarefa
Uma skill funciona bem quando cobre uma tarefa repetível com um fim claro: "escrever as release notes a partir dos pull requests mesclados", e não "ajudar com o projeto". A documentação do Claude Code sugere transformar em skill as instruções que você vive colando no chat e tirar procedimentos do CLAUDE.md quando eles ficam longos.
Escolha um nome curto, com letras minúsculas, números e hífens, como release-notes. Esse nome vira o nome da pasta e o comando de barra.
Passo 2: crie a pasta
Skills pessoais, disponíveis em todos os projetos da sua máquina:
mkdir -p ~/.claude/skills/release-notes
Skills de projeto, compartilhadas com qualquer pessoa que clonar o repositório:
mkdir -p .claude/skills/release-notes
Plugins também podem trazer skills em uma pasta skills/, que é o caminho mais comum para compartilhar um conjunto de skills entre muitos repositórios.
Passo 3: escreva o SKILL.md
---
name: release-notes
description: Drafts release notes from merged pull requests since the last tag. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---
## Steps
1. Find the latest git tag and list pull requests merged after it.
2. Group changes under Added, Changed and Fixed.
3. Write one plain sentence per change and link the pull request.
## Rules
- Leave out internal refactors unless they change behaviour.
- Ask before publishing anything.
Três pontos fazem a diferença:
- A descrição decide quando a skill é carregada. O Claude compara os pedidos com ela. Diga o que a skill faz e quando usá-la, e inclua as palavras que as pessoas digitariam naturalmente. O Claude Code corta descrições longas na lista de skills (o texto combinado tem limite de 1.536 caracteres), então coloque o uso principal primeiro.
- Escreva instruções que continuem valendo durante toda a sessão. O Claude Code adiciona o conteúdo da skill à conversa uma vez e não relê o arquivo nas interações seguintes.
- Seja breve. Procure manter o
SKILL.mdcom menos de 500 linhas e mova os detalhes para arquivos separados.
Passo 4: adicione scripts e arquivos de referência, se precisar
Material de referência longo deve ficar em um arquivo próprio, com link no SKILL.md para o Claude saber quando abri-lo:
release-notes/
├── SKILL.md
├── references/style-guide.md
└── scripts/list_merged_prs.py
Scripts servem para etapas que precisam dar sempre o mesmo resultado. O Claude os executa e vê apenas a saída. No Claude Code, use a variável ${CLAUDE_SKILL_DIR} para apontar para os arquivos incluídos, assim o caminho funciona quer a skill esteja instalada como pessoal, de projeto ou em um plugin. A especificação Agent Skills recomenda que os scripts listem as próprias dependências e mostrem mensagens de erro claras.
Passo 5: defina quem pode iniciar a skill
Por padrão, tanto você quanto o Claude podem iniciar uma skill. Dois campos do Claude Code mudam isso:
| Campo | Efeito | Uso típico |
|---|---|---|
disable-model-invocation: true |
Só você pode iniciá-la, com /name |
Deploys, envio de mensagens, qualquer coisa com efeitos colaterais |
user-invocable: false |
Fica fora do menu /; só o Claude a carrega |
Conhecimento de apoio, como um guia de estilo |
O campo allowed-tools pré-aprova as ferramentas indicadas durante a interação em que a skill roda. Libere só o que a tarefa precisa.
Passo 6: teste a skill
- Abra o Claude Code e pergunte "What skills are available?". A sua skill deve aparecer na lista.
- Faça um pedido que corresponda à descrição, sem citar o nome da skill, e confira se o Claude a carrega.
- Execute-a diretamente com
/release-notes.
O Claude Code monitora as pastas de skills, então as edições valem na mesma sessão; uma pasta de skills que não existia quando a sessão começou precisa de /reload-skills. Se o YAML estiver malformado, o comando de barra continua funcionando, mas o Claude não consegue comparar os pedidos com a sua descrição. Rodar claude --debug mostra o erro de parsing, e claude plugin validate ~/.claude/skills confere o front matter (Claude Code v2.1.233 ou mais recente). Para skills que também vão ser usadas por outros agentes, o comando skills-ref validate ./my-skill da especificação confere os campos padrão.
Use a skill-creator
A Anthropic publica uma skill skill-creator no seu repositório anthropics/skills. Segundo a própria descrição, ela cria skills novas, aprimora as existentes e mede o desempenho delas. O fluxo de trabalho que ela segue:
- Pergunta o que a skill deve fazer, quando deve ser acionada e como é uma boa saída.
- Escreve um rascunho do
SKILL.mde dos arquivos incluídos. - Escreve dois ou três prompts de teste realistas e os salva em
evals/evals.json. - Roda cada prompt com e sem a skill (ou contra a versão anterior), avalia os resultados e os mostra para a sua revisão.
- Revisa e repete até você ficar satisfeito.
- Gera prompts que devem e que não devem acionar a skill e ajusta a descrição para aumentar a taxa de acerto.
No Claude Code, instale-a como plugin com /plugin install skill-creator@claude-plugins-official e depois peça, por exemplo, "evaluate my release-notes skill with skill-creator". A documentação do Claude Code diz que cada teste roda em um subagente separado, com contexto limpo, e que os resultados incluem taxa de aprovação, tempo e tokens com e sem a skill.
O Codex traz a sua própria skill-creator embutida, iniciada com $skill-creator. Você também encontra a skill nas nossas listagens de skills.
Compartilhe a sua skill
- Com a sua equipe: inclua a pasta
.claude/skills/no repositório. - Entre repositórios: empacote as skills em um plugin do Claude Code.
- No claude.ai: envie a pasta como arquivo zip. Lá, só os campos padrão do front matter são aceitos.
- Em outros agentes: use só os campos padrão e confira na documentação de cada agente qual é a pasta de skills.
Skills personalizadas não são sincronizadas entre o Claude Code, o claude.ai e a API, então adicione-as em cada lugar.
Uma observação sobre segurança
Uma skill com scripts executa código na sua máquina, e, segundo a documentação do Claude Code, a configuração allowed-tools de uma skill de projeto vale até em uma pasta que você não marcou como confiável. Revise as skills que chegam nos repositórios com o mesmo cuidado que qualquer outro código e veja as nossas perguntas de segurança para fazer antes de instalar um servidor ou uma skill.
Próximos passos
Se a sua skill precisa de dados ao vivo de outro app, combine-a com um servidor MCP: nosso guia sobre MCP vs. skills explica como os dois se encaixam. Para ter ideias, veja skills de revisão de código ou de documentação.
Perguntas
- Onde salvo uma skill personalizada do Claude Code?
- Coloque em ~/.claude/skills/<skill-name>/SKILL.md para usá-la em todos os seus projetos, ou em .claude/skills/<skill-name>/SKILL.md dentro de um repositório para compartilhá-la com a equipe desse projeto.
- O que é o skill creator do Claude?
- A skill-creator é uma skill publicada pela Anthropic que ajuda você a escrever uma skill nova, criar prompts de teste, comparar os resultados com e sem a skill e ajustar a descrição. No Claude Code, ela está disponível como plugin.
- Por que o Claude não usa a minha skill?
- Normalmente, a descrição não corresponde ao jeito como você faz os pedidos. Inclua as palavras que as pessoas realmente usam, confira se a skill aparece quando você pergunta quais skills estão disponíveis ou inicie-a diretamente com /skill-name.
- Posso usar a mesma skill no claude.ai ou no Codex?
- Muitas vezes, sim, se você usar só os campos padrão do front matter. O claude.ai recebe skills por upload de arquivo zip e rejeita chaves desconhecidas, e o Codex lê skills de pastas .agents/skills.
Fontes
- Extend Claude with skills (Claude Code docs)conferido em 14 de nov. de 2026
- Agent Skills specificationconferido em 14 de nov. de 2026
- Agent Skills (Claude Platform docs)conferido em 14 de nov. de 2026
- skill-creator SKILL.md (anthropics/skills)conferido em 14 de nov. de 2026
- anthropics/skills repositoryconferido em 14 de nov. de 2026
- Build skills (Codex docs)conferido em 14 de nov. de 2026
Mais guias
- Como conectar servidores MCP ao Claude, ao ChatGPT e ao Cursor
- Como criar um servidor MCP
- Segurança no MCP: perguntas para fazer antes de instalar um servidor ou uma skill
- MCP vs. API: qual é a diferença?
- MCP vs. skills: a diferença entre servidores MCP e skills de agente
- O que é uma skill do Claude?
- O que é um servidor MCP?