Skills do Claude Code: como criar, com exemplos e boas práticas

O que são as skills do Claude Code

Crie uma skill quando você vive colando no chat as mesmas instruções, o mesmo checklist ou o mesmo procedimento de vários passos, ou quando uma parte do seu CLAUDE.md deixou de ser um fato e virou um procedimento. As skills seguem o padrão aberto Agent Skills (agentskills.io), que outras ferramentas de IA também leem; o Claude Code acrescenta extras como controle de invocação, execução em subagentes e saída de shell ao vivo no prompt.

• Duas formas de rodar uma: o Claude a carrega quando o seu pedido combina com a description dela, ou você digita /skill-name.
• Barata até ser usada: só o nome e a descrição ficam no contexto; o corpo carrega quando a skill roda. Uma skill configurada para rodar só manualmente nem lista a descrição.
• Os comandos de barra próprios agora são skills: .claude/commands/<name>.md continua funcionando, mas uma pasta de skill também pode guardar arquivos de apoio. Veja comandos de barra do Claude Code.
• O Claude Code também vem com skills incluídas, como /simplify, /loop, /batch e /debug.

Skills vs. CLAUDE.md vs. subagentes vs. plugins vs. MCP

Como criar uma skill do Claude Code

1. Escolha onde ela fica

   ~/.claude/skills/<name>/ para você em todos os projetos; .claude/skills/<name>/ em um repositório, com commit, para todo mundo que trabalha nele. O nome da pasta vira o comando, então summarize-changes gera /summarize-changes.

2. Escreva o SKILL.md: uma descrição e depois as instruções

   O frontmatter vai entre linhas --- bem no topo. Só description é recomendado: coloque primeiro o caso de uso e as palavras que as pessoas realmente diriam. Abaixo dele, escreva as instruções em Markdown. Uma linha que começa com ` !command ` roda esse comando antes e cola a saída, então a skill trabalha a partir do seu estado real.

   ---
   description: Resume as alterações sem commit e aponta o que for arriscado. Use quando o usuário perguntar o que mudou, quiser uma mensagem de commit ou pedir para revisar o diff.
   ---
   
   ## Alterações atuais
   
   !`git diff HEAD`
   
   ## Instruções
   
   Resuma as alterações acima em dois ou três tópicos e depois liste os riscos,
   como tratamento de erros ausente, valores fixos no código ou testes para atualizar.

3. Teste dos dois jeitos

   Abra o claude em um projeto git com uma alteração sem commit. Pergunte "O que eu mudei?" para ver se o Claude escolhe a skill sozinho, e depois digite /summarize-changes para rodá-la diretamente. As skills que você adiciona durante uma sessão carregam sozinhas; rode /reload-skills se alguma não aparecer.

4. Decida quem pode rodá-la

   Adicione disable-model-invocation: true a qualquer coisa com efeitos colaterais, como deploys ou envio de mensagens, para que só você possa acioná-la. Adicione user-invocable: false a conhecimento de fundo que só o Claude deve carregar. Passe dados com $ARGUMENTS, como mostra o guia de comandos de barra.

5. Compartilhe

   Faça commit de .claude/skills/ no repositório, ou empacote as skills como um plugin para vários repositórios ou times.

Fonte: documentação do Claude Code, Extend Claude with skills

Exemplos de skills do Claude Code

1. Uma skill de referência que só carrega para os arquivos certos

   Skills de referência guardam convenções que o Claude aplica enquanto trabalha. paths limita o carregamento automático aos arquivos que combinam com os globs.

   ---
   description: Convenções de design de API deste código. Use ao escrever ou revisar endpoints HTTP.
   paths: ["src/api/**"]
   ---
   
   Ao escrever endpoints de API:
   - Use nomes RESTful e recursos no plural
   - Retorne erros como { error: { code, message } }
   - Valide o corpo da requisição com os schemas de src/api/schemas/

2. Uma skill de tarefa com arquivos de apoio

   Mantenha o SKILL.md curto e aponte para o resto. O Claude lê checklist.md só quando o SKILL.md manda, e roda bump.sh sem lê-lo, então os detalhes não custam nada até serem necessários.

   release/
   ├── SKILL.md          # os passos, e quando ler os outros arquivos
   ├── checklist.md      # carregado só quando o SKILL.md indica
   └── scripts/
       └── bump.sh       # executado, não lido para o contexto

3. Uma skill que roda no próprio subagente

   context: fork inicia um subagente (aqui o tipo Explore, somente leitura) com a skill como prompt. Ele não vê a sua conversa, então as instruções precisam se sustentar sozinhas; ele roda em segundo plano, a menos que você defina background: false.

   ---
   description: Audita as dependências em busca de vulnerabilidades conhecidas e versões major desatualizadas
   context: fork
   agent: Explore
   disable-model-invocation: true
   ---
   
   Rode a auditoria do gerenciador de pacotes, liste cada achado alto ou crítico com
   a versão que corrige e informe quais versões major estão atrasadas. Não altere nenhum arquivo.

Instalar skills de plugins e marketplaces

Skills escritas por outras pessoas costumam chegar dentro de plugins. O Claude Code registra o marketplace oficial da Anthropic (claude-plugins-official) na primeira vez que você inicia uma sessão interativa; navegue por ele com /plugin ou instale direto, por exemplo /plugin install skill-creator@claude-plugins-official. Para um marketplace de um time ou da comunidade, adicione-o antes com /plugin marketplace add owner/repo.

• As skills de plugin se chamam /plugin-name:skill-name.
• O marketplace oficial mostra o custo de contexto de cada plugin por turno e quando invocado.
• O plugin skill-creator ajuda a escrever uma skill e roda evals que comparam os resultados com e sem ela.
• Leia as skills de um repositório ou plugin antes de confiar nelas: allowed-tools pode pré-aprovar ferramentas no turno em que uma skill roda.

Boas práticas, e quando o Claude ignora uma skill

• Escreva a descrição pensando na correspondência: comece pela tarefa e pelas frases que os usuários dizem. A descrição mais when_to_use é cortada em 1.536 caracteres na listagem.
• Coloque as instruções mais importantes perto do topo: depois que a conversa é compactada, o Claude Code pode manter só o começo de uma skill invocada. Invoque-a de novo para restaurá-la.
• Escreva as orientações para a tarefa inteira ("rode os testes depois de cada edição"), porque o arquivo da skill não é relido nos turnos seguintes. Uma regra que nunca pode ser pulada pertence a um hook.
• Para reduzir o uso de tokens, tire os procedimentos do CLAUDE.md e passe-os para skills, defina disable-model-invocation: true nas skills que você roda manualmente e confira o /skill-doctor para achar skills que custam contexto mas quase não são usadas.
• Não está sendo acionada? Confira se a descrição tem as palavras-chave certas, pergunte "Quais skills estão disponíveis?" e rode claude plugin validate .claude/skills para achar frontmatter que não é lido corretamente.
• Acionada vezes demais? Deixe a descrição mais específica, ou passe a skill para manual com disable-model-invocation: true.

As skills ensinam o Claude Code a fazer. O Crewmark dá a ele algo para fazer a cada hora.

Uma biblioteca de skills deixa cada sessão capaz, mas ela ainda espera você pedir. O Crewmark transforma uma sessão do Claude Code, Codex, DeepSeek Harness ou OpenCode em um funcionário de IA com um papel, uma meta e um horário de trabalho, e a acorda com um heartbeat para pegar a próxima issue de um quadro, com as skills do seu projeto carregadas.

1. Mantenha as skills no repositório

   A sessão do funcionário lê .claude/skills/ e o CLAUDE.md como a sua, então uma skill de release ou um checklist de revisão vão junto.

2. Deixe o heartbeat iniciar o trabalho

   Durante o horário de trabalho, o funcionário acorda a cada 15, 30 ou 60 minutos na mesma conversa e pega a próxima issue; veja como tornar o Claude Code proativo.

3. Atribua issues e responda às mensagens dele

   Coloque o trabalho no quadro; o funcionário comenta conforme avança e avisa você quando precisa de uma decisão. Leia o que é um funcionário de IA.

Perguntas frequentes sobre skills do Claude Code