Transformar os pedidos que repetes em comandos teus no Claude Code

Se estás sempre a escrever as mesmas instruções ("resume as minhas alterações e assinala o que for arriscado", "faz o commit disto com uma mensagem como deve ser", "vê o disco e a memória"), podes transformar cada uma num comando teu. Escreves /summarize-changes e o Claude recebe as instruções completas, já com os dados de que precisa.

No Claude Code, a isto chama-se skills. Este guia mostra como escrever uma, como lhe passar argumentos e o resultado de comandos, como decidir quem a pode correr, e o que verificar antes de usares skills do repositório de outra pessoa.

Skills e comandos personalizados são agora a mesma coisa

Guias mais antigos falam de comandos personalizados em .claude/commands/. Esses passaram a fazer parte das skills. Um ficheiro em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam ambos o /deploy e funcionam da mesma maneira. Os teus ficheiros de comandos antigos continuam a funcionar.

As skills acrescentam algumas coisas: uma pasta para ficheiros extra, definições que controlam se o Claude pode correr a skill sozinho, e a possibilidade de o Claude ir buscar uma skill por iniciativa própria quando ela serve para o que pediste.

Onde ficam as skills

Cada skill é uma pasta com um ficheiro SKILL.md lá dentro. O sítio onde pões a pasta decide onde a skill funciona:

• ~/.claude/skills/<nome>/SKILL.md: uma skill pessoal, em todos os projetos da tua máquina.
• .claude/skills/<nome>/SKILL.md num projeto: só nesse projeto. Faz commit dela e toda a gente que trabalha no projeto fica com ela.

O nome da pasta passa a ser o comando. .claude/skills/summarize-changes/SKILL.md dá-te o /summarize-changes. Se uma skill pessoal e uma de projeto tiverem o mesmo nome, corre a pessoal.

A tua primeira skill

Esta skill resume as alterações que ainda não estão em commit e aponta o que for arriscado. É adaptada do exemplo da documentação oficial.

1. 1

   Cria a pasta

   Terminal · o teu utilizador

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

2. 2

   Escreve 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

   Corre-a

   Claude Code

   > /summarize-changes

O ficheiro tem duas partes:

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

A skill pode ser escrita em português. Usámos inglês porque é assim que a vais encontrar na maior parte dos exemplos.

A linha !`git diff HEAD` não é uma instrução para o Claude. O Claude Code corre primeiro o comando e põe o resultado nesse sítio, por isso o Claude recebe o teu diff verdadeiro, e não um pedido para o ir buscar.

No nosso teste, uma alteração que subia um limite de 10 para 1000 e acrescentava uma palavra-passe a um ficheiro PHP voltou como dois pontos de resumo, seguidos de riscos que incluíam "Hardcoded password" e "Limit raised 100×".

Deixa o Claude encontrá-la sozinho

Não precisas de escrever o comando. O Claude vê a descrição de cada skill e, quando o teu pedido encaixa numa, carrega-a ele próprio. No nosso teste, bastou a pergunta simples abaixo: o Claude chamou a skill summarize-changes sem que lho dissessem.

> What did I change?

Por isso, a descrição é a linha mais importante do ficheiro. Diz primeiro o que a skill faz e depois os pedidos a que deve responder, com as palavras que as pessoas usam de facto.

Decide quem a pode correr

Há skills que nunca devem correr sem ser tu a pedir. Não queres que o Claude decida sozinho que agora é boa altura para publicar em produção. Há duas definições no cabeçalho para isto:

• disable-model-invocation: true: só tu a podes correr, escrevendo o comando. O Claude nem sequer a vê na lista dele. Usa-a para tudo o que tenha efeitos: commits, publicações, envio de mensagens.
• user-invocable: false: só o Claude a pode usar. Desaparece do menu /. Usa-a para conhecimento de fundo, como o funcionamento de um sistema antigo, que não é um comando que alguém escreva.

Testámos a primeira com um relatório do servidor só manual. Quando pedimos por palavras "a short health report for this server using the server-report skill", o Claude não usou a skill e correu os seus próprios comandos. Escrever /server-report correu a skill.

Passar argumentos

O que escreveres a seguir ao comando chega à skill como $ARGUMENTS. Esta skill /commit usa-o 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 escreves o comando.
• Para receber os argumentos um a um, usa $0, $1 e por aí fora: /deploy staging v2 faz com que $0 seja staging e $1 seja v2. Põe um valor entre aspas para manter várias palavras juntas.
• allowed-tools deixa a skill correr esses comandos sem te perguntar. O nosso commit de teste passou sem nenhum pedido de permissão. A aprovação dura só esse turno: acaba quando envias a mensagem seguinte.

O Claude continua a usar o seu critério dentro de uma skill. Na nossa primeira tentativa, a alteração tinha uma palavra-passe escrita no código e, em vez de fazer o commit, o Claude parou e perguntou se a devia tirar primeiro.

Dar a uma skill o resultado de comandos

As linhas !`comando` são o que torna as skills úteis para trabalho em servidores. Esta junta os números para um relatório rápido do estado 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.

Estes comandos nunca param para pedir permissão. O Claude Code compara cada um com as tuas regras de permissão primeiro:

• Os comandos só de leitura que o Claude Code reconhece correm tal como estão. No nosso teste, df, free e uptime não precisaram de nada.
• Qualquer outro comando que as tuas regras não autorizem para a skill inteira antes de ela chegar ao Claude.

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

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

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

Um comando que termina com erro também para a skill. Se contas que um comando saia com um código diferente de zero, por exemplo um script de verificação que assinala problemas dessa forma, acaba a linha com || true.

Skills do repositório de outra pessoa

Há três pontos da documentação que convém conhecer antes de trabalhares num repositório que não foste tu a escrever:

• O allowed-tools de uma skill do projeto aplica-se mesmo que nunca tenhas confiado na pasta, incluindo em execuções com claude -p. Isto é diferente das regras de autorizar do .claude/settings.json, que só valem depois da caixa de confiança. Vimo-lo no nosso teste: a pasta nunca tinha sido marcada como de confiança, e o /commit correu o git add e o git commit sem pedir nada. Uma skill pode aprovar para si própria um acesso alargado. Lê as linhas allowed-tools do .claude/skills/ do repositório antes de correres lá o Claude Code.
• As linhas !`comando` correm na tua máquina quando a skill corre. Passam na mesma pela verificação de permissões, mas o allowed-tools pode aprová-las.
• Podes desligar essas linhas de comando por completo com "disableSkillShellExecution": true nas tuas definições. Cada comando passa a ser substituído por uma nota, em vez de correr.

Mantém as skills curtas

• O texto completo de uma skill só é carregado quando ela corre. Até lá, só a descrição ocupa espaço, por isso uma skill longa quase não custa nada enquanto não é usada.
• Depois de correr, o texto fica na conversa. Cada linha custa tokens em todos os turnos seguintes, por isso escreve o que fazer, e não porquê.
• A documentação sugere manter o SKILL.md abaixo das 500 linhas. Põe o material de referência longo noutros ficheiros da mesma pasta e diz no SKILL.md o que está em cada um, para o Claude só os ler quando precisar.

Quando uma skill não aparece

• Confirma o caminho. Tem de ser .claude/skills/<nome>/SKILL.md, com SKILL.md em maiúsculas.
• Confirma a primeira linha. O cabeçalho só é lido se o --- de abertura for mesmo a primeira linha do ficheiro.
• Confirma os nomes dos campos. Têm de coincidir exatamente, hífenes incluídos. O Claude Code ignora um campo que não reconhece, sem dar erro.
• Se o Claude nunca a vai buscar sozinho, reescreve a descrição com as palavras que usas de facto quando pedes, ou escreve simplesmente o comando.
• Se corre vezes demais, torna a descrição mais estreita, ou acrescenta 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, a norma aberta que as skills do Claude Code seguem (em inglês)