Transforme os pedidos que você repete em comandos seus no Claude Code

Se você vive digitando as mesmas instruções ("resuma minhas mudanças e aponte o que for arriscado", "faça o commit disso com uma mensagem decente", "confira o disco e a memória"), dá para transformar cada uma em um comando seu. Você digita /summarize-changes e o Claude recebe as instruções completas, já com os dados de que precisa.

No Claude Code, isso se chama skill. Este guia mostra como escrever uma, como passar argumentos e o resultado de comandos, como decidir quem pode rodar a skill, e o que conferir antes de usar skills do repositório de outra pessoa.

Skills e comandos personalizados agora são a mesma coisa

Guias mais antigos falam de comandos personalizados em .claude/commands/. Eles passaram a fazer parte das skills. Um arquivo em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam o mesmo /deploy e funcionam do mesmo jeito. Os seus arquivos de comandos antigos continuam funcionando.

As skills trazem algumas coisas a mais: uma pasta para arquivos extras, configurações que controlam quem pode rodar a skill, e a possibilidade de o Claude usá-la por conta própria quando ela serve para o que você pediu.

Onde ficam as skills

Cada skill é uma pasta com um arquivo SKILL.md dentro. O lugar onde você coloca a pasta define onde a skill funciona:

• ~/.claude/skills/<nome>/SKILL.md: uma skill pessoal, em todos os projetos da sua máquina.
• .claude/skills/<nome>/SKILL.md em um projeto: só naquele projeto. Faça commit dela e todo mundo que trabalha no projeto passa a ter a skill.

O nome da pasta vira o comando. .claude/skills/summarize-changes/SKILL.md gera o /summarize-changes. Se uma skill pessoal e uma de projeto tiverem o mesmo nome, roda a pessoal.

Sua primeira skill

Esta skill resume as mudanças que ainda não foram para um commit e aponta o que for arriscado. Ela foi adaptada do exemplo da documentação oficial.

1. 1

   Crie a pasta

   Terminal · seu usuário

   $ mkdir -p .claude/skills/summarize-changes

2. 2

   Escreva o SKILL.md

   .claude/skills/summarize-changes/SKILL.md

   ---
   description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
   ---
   
   ## Current changes
   
   !`git diff HEAD`
   
   ## Instructions
   
   Summarize the changes above in two or three bullet points, then list any risks you notice, such as hardcoded passwords, changed limits or missing error handling. If the diff is empty, say there are no uncommitted changes.

3. 3

   Rode a skill

   Claude Code

   > /summarize-changes

O arquivo tem duas partes:

• O cabeçalho (frontmatter), entre as linhas ---. Aqui ele tem só a description, que diz ao Claude para que serve a skill e quando usá-la.
• O corpo, as instruções que o Claude segue quando a skill roda.

Uma skill pode ser escrita em português. Usamos inglês porque é assim que você vai encontrar a maioria dos exemplos.

A linha !`git diff HEAD` não é uma instrução para o Claude. O Claude Code roda o comando antes e coloca o resultado naquele lugar, então o Claude recebe o seu diff de verdade, e não um pedido para ir buscá-lo.

No nosso teste, o resumo de uma mudança que subia um limite de 10 para 1000 e adicionava uma senha a um arquivo PHP veio em dois itens, seguidos de riscos que incluíam "Hardcoded password" e "Limit raised 100×".

Deixe o Claude achar a skill sozinho

Você não precisa digitar o comando. O Claude vê a descrição de cada skill e, quando o seu pedido combina com uma, ele mesmo carrega a skill. No nosso teste, bastou a pergunta simples abaixo: o Claude chamou a skill summarize-changes sem ninguém mandar.

> What did I change?

Por isso a descrição é a linha mais importante do arquivo. Diga primeiro o que a skill faz e depois os pedidos que ela deve atender, com as palavras que as pessoas usam de verdade.

Decida quem pode rodar a skill

Tem skill que nunca deve rodar sem você pedir. Você não quer que o Claude decida sozinho que agora é uma boa hora para fazer deploy. Duas configurações no cabeçalho controlam isso:

• disable-model-invocation: true: só você pode rodar, digitando o comando. O Claude nem vê a skill na lista dele. Use para tudo que tem efeitos colaterais: commits, deploys, envio de mensagens.
• user-invocable: false: só o Claude pode usar. Ela some do menu /. Use para conhecimento de contexto, como o funcionamento de um sistema antigo, que não é um comando que alguém digitaria.

Testamos a primeira com uma skill de relatório do servidor configurada como só manual. Quando pedimos o relatório em texto livre, "a short health report for this server using the server-report skill", o Claude não usou a skill e rodou os próprios comandos. Digitar /server-report rodou a skill.

Passe argumentos

O que você digitar depois do comando chega à skill como $ARGUMENTS. Esta skill /commit usa isso para a mensagem do commit:

---
description: Stage all changes and commit them with the given message
disable-model-invocation: true
argument-hint: [commit message]
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Stage all changes with `git add -A` and commit them with this message: $ARGUMENTS

If no message was given, write a one-line message from the diff. Then show the result of `git status --short`.

> /commit Raise limit to 1000

• argument-hint é a dica que aparece enquanto você digita o comando.
• Para pegar os argumentos um por um, use $0, $1 e assim por diante: /deploy staging v2 faz $0 valer staging e $1 valer v2. Coloque um valor entre aspas para manter várias palavras juntas.
• allowed-tools deixa a skill rodar esses comandos sem perguntar para você. O nosso commit de teste passou sem nenhum pedido de permissão. A aprovação vale só até você enviar a próxima mensagem.

O Claude continua usando o próprio critério dentro de uma skill. Na nossa primeira tentativa, a mudança tinha uma senha escrita no código e, em vez de fazer o commit, o Claude parou e perguntou se devia tirar a senha antes.

Alimente a skill com o resultado de comandos

As linhas !`comando` são o que torna as skills úteis para trabalho em servidor. Esta skill reúne os números para um relatório rápido da saúde do servidor:

---
description: Short health report for this server (disk, memory, load)
disable-model-invocation: true
allowed-tools: Bash(systemctl --failed *)
---

## Disk
!`df -h /`

## Memory
!`free -h`

## Load
!`uptime`

## Failed services
!`systemctl --failed --no-legend`

## Instructions

Write a five-line health report from the numbers above. Say plainly if disk use is over 80 percent or if memory is nearly full.

Esses comandos nunca param para pedir permissão. O Claude Code confere cada um com as suas regras de permissão antes de rodar:

• Os comandos só de leitura que o Claude Code reconhece rodam direto. No nosso teste, df, free e uptime não precisaram de nada.
• Qualquer outro comando que as suas regras não liberem interrompe a skill inteira antes de ela chegar ao Claude.

Sem a linha allowed-tools, o systemctl --failed interrompeu a skill com:

Shell command permission check failed for pattern "!`systemctl --failed --no-legend`": This command requires approval

A linha allowed-tools do arquivo acima resolve isso, aprovando os comandos systemctl --failed só para esta skill.

Um comando que termina com erro também interrompe a skill. Se você espera que um comando saia com código diferente de zero, por exemplo um script de checagem que sinaliza problemas pelo código de saída, termine a linha com || true.

Skills do repositório de outra pessoa

Vale a pena conhecer três pontos da documentação antes de trabalhar em um repositório que não foi você que escreveu:

• O allowed-tools de uma skill do projeto vale mesmo se você nunca confiou na pasta, inclusive em execuções com claude -p. Isso é diferente das regras de liberar do .claude/settings.json, que só valem depois da caixa de confiança. Vimos isso no nosso teste: a pasta nunca tinha sido marcada como confiável, e o /commit rodou o git add e o git commit sem pedir nada. Uma skill pode aprovar para si mesma um acesso amplo. Leia as linhas allowed-tools do .claude/skills/ do repositório antes de rodar o Claude Code ali.
• As linhas !`comando` rodam na sua máquina quando a skill roda. Elas passam pela mesma verificação de permissões que os outros comandos, mas o allowed-tools da própria skill pode aprová-las.
• Você pode desligar essas linhas de comando de vez com "disableSkillShellExecution": true nas suas configurações. Cada comando passa a ser trocado por um aviso, em vez de rodar.

Mantenha as skills curtas

• O texto completo de uma skill só é carregado quando ela roda. Até lá, só a descrição ocupa espaço, então uma skill longa quase não custa nada enquanto não é usada.
• Depois que roda, o texto fica na conversa. Cada linha custa tokens em todas as mensagens seguintes, então escreva o que fazer, e não o porquê.
• A documentação sugere manter o SKILL.md abaixo de 500 linhas. Coloque o material de referência longo em outros arquivos da mesma pasta e diga no SKILL.md o que tem em cada um, para o Claude só ler quando precisar.

Quando uma skill não aparece

• Confira o caminho. Tem que ser .claude/skills/<nome>/SKILL.md, com SKILL.md em maiúsculas.
• Confira a primeira linha. O cabeçalho só é lido se o --- de abertura for exatamente a primeira linha do arquivo.
• Confira os nomes dos campos. Eles precisam bater exatamente, hífens incluídos. O Claude Code ignora um campo que não reconhece, sem mostrar erro.
• Se o Claude nunca usa a skill sozinho, reescreva a descrição com as palavras que você usa de verdade quando pede, ou simplesmente digite o comando.
• Se ela roda vezes demais, deixe a descrição mais específica, ou adicione disable-model-invocation: true.

Fontes

• Extend Claude with skills, documentação do Claude Code (em inglês)
• Configure permissions, documentação do Claude Code (em inglês)
• Agent Skills, o padrão aberto que as skills do Claude Code seguem (em inglês)