Criar uma `skill` do Claude: escrever, capturar ou instalar

A documentação da Anthropic coloca preço em cada metade de uma skill, e esses números deveriam mudar a forma como você constrói a sua. Os metadados — name mais description — entram no system prompt na inicialização e custam por volta de 100 tokens por skill. O corpo custa zero até a skill disparar, e menos de 5k tokens quando dispara. Instale cinquenta skills e você paga por cinquenta descrições, não por cinquenta procedimentos.

Ou seja: as instruções são a metade barata e fácil. A metade cara é um campo só. E é essa a lente pra escolher entre os três jeitos de construir uma skill: todos terminam no mesmo arquivo, mas nenhum deles é igualmente bom em produzir uma description que combine com o jeito que você realmente pede a tarefa.

Primeiro, o arquivo

Todo caminho converge pra esse formato. Mínimo, válido e portável entre Claude Code, claude.ai e a API:

---
name: writing-status-updates
description: Turns a week of commits, tickets and threads into the async written update a distributed team reads. Use when the user asks for a weekly update, a status write-up, or what to tell their manager.
---

## Steps
1. Gather the raw material: `git log --author=me --since='7 days ago'`, tickets closed, decisions made.
2. Write three sections — Shipped, Blocked, Next. Three bullets each, maximum.
3. Every bullet names an outcome, not an activity: "checkout p95 down to 180ms", never "worked on checkout performance".
4. For each blocker, state the decision that unblocks it and propose a default.

## Rules
- No adjectives, no "great progress".
- A bullet with no number and no name in it is not finished. Rewrite it.
- 150 words total, hard cap.

Salve em ~/.claude/skills/writing-status-updates/SKILL.md (sua, em todos os projetos) ou em .claude/skills/… (só neste repositório, e entra no git). O nome do diretório vira o comando que você digita, então esse arquivo te dá o /writing-status-updates. O Claude Code monitora esses diretórios, então uma skill nova vale na mesma sessão — sem reiniciar nada.

Três limites pra saber antes de batizar a sua: name vai até 64 caracteres, só letras minúsculas, números e hífens, e as palavras "claude" e "anthropic" são reservadas — claude-status-updates é rejeitado. description vai até 1.024 caracteres. E no Claude Code a description somada ao campo opcional when_to_use é truncada em 1.536 caracteres na listagem de skills, então coloque o gatilho no começo.

Caminho 1 — Escrever na mão

Use quando o procedimento já existe escrito em algum lugar: um runbook, uma seção do CONTRIBUTING, um checklist nas suas notas. Você não está criando conhecimento, está mudando ele de lugar pra um arquivo que o Claude carrega sozinho.

É o caminho mais barato, e o único em que você controla a description palavra por palavra. A documentação é rígida num ponto: escreva em terceira pessoa, porque esse texto cai dentro do system prompt. "Generates commit messages by analyzing git diffs" funciona; "I can help you write commit messages" atrapalha a descoberta da skill.

Caminho 2 — Fazer o trabalho uma vez e pedir pro Claude capturar

Use quando o procedimento vive na sua mão e em nenhum outro lugar — você sabe fazer, mas esqueceria metade das decisões de julgamento se sentasse pra escrever tudo.

Esse é o caminho que o próprio guia de autoria da Anthropic recomenda, e ele é um ciclo, não um prompt: faça uma tarefa real com o Claude do jeito normal, repare no contexto que você fica repetindo, e só então peça pra ele transformar aquilo numa skill. A documentação deixa claro que não precisa de preparação nenhuma — o Claude conhece o formato de skill nativamente, então "escreve isso como uma skill" já basta. Depois vêm as duas etapas que todo mundo pula: tirar as explicações que o Claude colocou pra coisas que ele já sabe, e testar numa instância nova, com a skill carregada e nada da sua conversa.

Mesmo caminho, entrada diferente: em vez de uma sessão, você pode entregar um documento que já existe. Isso merece um guia próprio.

Por que esse caminho ganha justamente no campo que importa: os gatilhos que aparecem na description final vêm das frases que você digitou de verdade, não das que você imaginou que ia digitar na hora de escrever o arquivo.

Caminho 3 — Instalar a de outra pessoa

Use quando a tarefa é genérica e já batida — formatação, conversão, uma revisão padrão. Alguém já ajustou aquilo, e uma skill boa pra uma tarefa universal viaja bem.

Duas mecânicas de distribuição importam aqui. Coloque no .claude/skills/ do repositório e todo mundo do time herda no clone. Publique dentro de um plugin e ela ganha o namespace plugin-name:skill-name, então não colide com nada. A precedência vai de enterprise → pessoal → projeto, e uma skill em qualquer nível sobrepõe uma nativa com o mesmo nome — jogue uma code-review no seu projeto e ela substitui o /code-review que vem com o Claude Code.

O custo é contexto. A skill de um estranho não sabe nada da sua stack, dos seus clientes, nem daquela exceção que você abre pra um serviço legado. E audite antes de confiar: a orientação da Anthropic é tratar uma skill como instalação de software, porque o allowed-tools de uma skill de projeto pode entregar ferramentas ao Claude sem te pedir permissão depois que você marca aquele diretório como confiável.

Duas coisas que mordem depois que funciona

Mantenha o corpo com menos de 500 linhas — esse é o número da documentação, e passando dele o certo é quebrar o material de referência em arquivos vizinhos que a skill referencia, num nível só de profundidade. Segunda: depois que uma skill é invocada, o conteúdo dela fica na conversa até o fim da sessão, e o Claude Code não relê o arquivo nos turnos seguintes. Então escreva regras permanentes, que valem pra tarefa inteira, e não passos pontuais que só fazem sentido no instante da invocação.

O ângulo de EM

Pra um dev brasileiro trabalhando com um time distribuído nos EUA ou na Europa, uma pasta .claude/skills/ versionada é alavancagem que aparece na revisão. É assim que o padrão do seu time pra uma atualização de status, uma migração ou uma descrição de PR deixa de ser conhecimento tribal que só se absorve estando no fuso certo.

Hoje: pegue a última tarefa que você fez bem com o Claude e rode o Caminho 2 nela — peça uma skill construída a partir daquela sessão. Depois reescreva só a description, em terceira pessoa, usando a frase exata que você digitaria pra pedir aquilo de novo. Dispare uma vez com essa frase pra confirmar que ela pega.

Fontes

• Claude Code docs — Extend Claude with skills
• Claude Docs — Agent Skills overview
• Claude Docs — Skill authoring best practices