Como transformar um prompt que já funciona em skill reutilizável?

Todo mundo tem aquele prompt no bloco de notas que já foi colado umas quinze vezes

Fala aí, beleza? Se liga nisso: o problema não é o prompt, ele funciona bem. O problema é que ele só funciona com você presente, colando o texto, completando o nome do arquivo, respondendo a pergunta de volta que o agente faz no meio do caminho…

A refatoração pra skill tem três movimentos, e é só isso: separar o que é instrução permanente, separar o que é dado da tarefa e reescrever o resto pra rodar sem supervisão

Bora ver na prática?

O que você precisa antes de começar

Primeiro: um prompt que já rodou algumas vezes

Ideia de prompt não vira skill boa, vira skill que você vai reescrever na semana seguinte. Se você colou o texto três, quatro vezes e o formato da resposta se manteve estável, aí sim tem material

Segundo: decidir onde a skill vai morar. No Claude Code existem dois lugares:

• ~/.claude/skills/ para skills pessoais, que valem em todo projeto
• .claude/skills/ para skills de projeto, versionadas no repositório

A diferença é de escopo, não de qualidade. Skill de projeto entra no git e o time inteiro herda a mesma instrução

E tem um detalhe importante pra quem já usa slash commands: a documentação oficial de slash commands do Claude Code trata .claude/commands/ como legado e recomenda preferir .claude/skills/

Se seu prompt hoje está num arquivo em .claude/commands/, é exatamente esse o caminho de migração que estamos falando aqui

Terceiro (opcional): a Anthropic mantém um repositório público de Agent Skills, o anthropics/skills, que pode ser registrado como marketplace de plugins do Claude Code com /plugin marketplace add anthropics/skills. Nele existe uma skill chamada skill-creator, em skills/skill-creator

O README do repositório cita exemplos de instalação de outros pacotes dele, no formato /plugin install document-skills@anthropic-agent-skills e /plugin install example-skills@anthropic-agent-skills. Repare que esses comandos são de outros plugins, não da skill-creator

Dá pra usar esse repositório como atalho, mas eu recomendo fazer a primeira skill na mão. Você entende o corte que precisa fazer no seu prompt e depois automatiza =)

Como transformar o prompt em skill, passo a passo

1. Recorte o prompt em duas colunas

Abra o prompt e marque cada pedaço como uma de duas coisas: instrução permanente ou dado da tarefa

Instrução permanente é regra, formato de saída, critério de qualidade, ordem das etapas, o que nunca muda entre execuções

Dado da tarefa é nome de arquivo, número de ticket, URL, nome de branch, o trecho que você trocava na mão toda vez

O erro comum deste passo: tratar exemplo como instrução. Aquele bloco de código que você colou uma vez pra ilustrar o formato é permanente; o conteúdo específico daquele caso é dado. Misturar os dois gera skill que insiste em resolver o problema da semana passada

2. Crie a pasta e o SKILL.md

Uma skill é uma pasta contendo um arquivo SKILL.md (frontmatter YAML mais instruções em markdown). Recursos de apoio são opcionais e ficam em scripts/, references/ e assets/

.claude/skills/
└── revisao-de-pr/
    ├── SKILL.md          # obrigatório
    ├── references/       # opcional
    └── scripts/          # opcional

No frontmatter, apenas dois campos são obrigatórios: name e description. Todos os outros são opcionais

E os limites são duros:

• name: máximo 64 caracteres, só letras minúsculas, números e hifens, sem tags XML e sem palavras reservadas como anthropic ou claude
• description: máximo 1024 caracteres, não pode ser vazia nem conter tags XML

O erro comum deste passo: batizar a skill de claude-code-review e travar na validação, porque claude é palavra reservada no name

3. Escreva a description dizendo o que faz E quando usar

Esse é o campo que decide se sua skill existe na prática

A description é injetada no system prompt e comparada com o pedido do usuário. Ela precisa indicar o que a skill faz e quando deve ser usada

---
name: revisao-de-pr
description: Revisa um diff aplicando os critérios de qualidade do time (nomes, tratamento de erro, cobertura de teste). Use quando o pedido envolver revisar código, PR ou diff antes do merge.
---

Repare que a segunda frase é sobre gatilho, não sobre funcionalidade

O erro comum deste passo: escrever description de README ("skill de revisão de código") e depois reclamar que o Claude nunca aciona. Ele não aciona porque não sabe quando

4. Troque o dado variável por $ARGUMENTS

Skills do Claude Code aceitam argumentos via placeholder $ARGUMENTS, que é substituído pelo texto digitado depois do nome da skill. Tanto o usuário quanto o Claude podem passar argumentos

## Entrada

Alvo da revisão: $ARGUMENTS

Se nenhum alvo for informado, revisar o diff da branch atual contra a base.

E tem um fallback útil de conhecer: se a skill recebe argumentos mas não tem o placeholder no corpo, o Claude Code anexa ARGUMENTS: <entrada> ao final do conteúdo da skill

O erro comum deste passo: esquecer o "se nada for informado". Sem esse caminho, a skill trava esperando você. E o ponto todo aqui é ela funcionar sem você

5. Reescreva em terceira pessoa e corte as perguntas de volta

As boas práticas oficiais de autoria mandam escrever a skill sempre em terceira pessoa, porque a description é injetada no system prompt e a consistência de ponto de vista importa

Na prática: sai o "me diga qual arquivo você quer revisar" e entra "o agente identifica os arquivos alterados e revisa cada um"

Esse é o passo mais parecido com o trabalho de portar prompt entre modelos: o texto continua o mesmo por fora, mas tudo que dependia de contexto implícito precisa virar explícito

O erro comum deste passo: deixar no corpo frases do tipo "se tiver dúvida, pergunte antes de prosseguir". Isso é ótimo no chat e péssimo numa skill que roda sozinha

6. Se fizer sentido, declare allowed-tools

A especificação de Agent Skills define seis campos de frontmatter permitidos, e o Claude Code aceita todos eles: allowed-tools, compatibility, description, license, metadata, name

O allowed-tools pode listar padrões de ferramentas, e os exemplos da documentação são desse formato:

allowed-tools:
  - Bash(git add *)
  - Bash(git commit *)
  - Bash(git status *)

Eu trato esse campo como declaração de intenção da skill, não como muro de segurança. Não construa seu guardrail em cima disso

7. Invoque com barra e observe

No Claude Code a skill é invocada digitando barra mais o nome da skill, e o comando vem do campo name do frontmatter:

/revisao-de-pr src/services/pedido.ts

Skills distribuídas por plugin recebem o prefixo do plugin, no formato /nome-do-plugin:exemplo

Mas o teste que interessa é o outro: peça a tarefa em linguagem natural, sem a barra, e veja se ela é acionada sozinha. É aí que você descobre se a description está boa

O erro comum deste passo: só testar pela barra. Invocação manual sempre funciona, e você fica com a falsa sensação de que terminou

A skill não dispara ou dispara na hora errada: o que checar

Sintoma: a skill nunca é acionada sozinha

Causa: description genérica, que descreve o que a skill é e não quando ela entra

Solução: reescreva incluindo os gatilhos reais. O checklist oficial de qualidade pede description específica, dizendo o que faz e quando usar. Pense nas palavras que você usa quando pede isso no chat e coloque elas ali

Sintoma: a skill dispara em tarefa que não é dela

Causa: description larga demais, do tipo que cobre metade do que você faz no dia

Solução: estreite o escopo e seja específico sobre o objeto da tarefa. Duas skills com gatilho nítido funcionam melhor que uma skill que tenta adivinhar

Sintoma: o Claude fica pedindo informação que antes você dava no chat

Causa: o dado da tarefa não virou nem $ARGUMENTS nem instrução de busca

Solução: para cada informação que a skill precisa, decida entre duas saídas: vem por argumento ou o agente descobre sozinho (lendo o repo, rodando um comando, olhando o diff). Toda pergunta de volta que sobrar é um ponto onde a skill volta a depender de você

Sintoma: corpo gigante poluindo o contexto

Causa: você colou o prompt inteiro mais três anexos de referência dentro do SKILL.md

Solução: o checklist oficial pede SKILL.md com menos de 500 linhas, terminologia consistente, exemplos concretos e nada de informação sensível ao tempo (ou isolada numa seção de "old patterns"). Material longo de consulta vai pra references/

Como prevenir tudo isso: entenda o progressive disclosure. Na inicialização, o agente carrega apenas name e description de cada skill no system prompt. O corpo completo do SKILL.md entra no contexto só quando a skill é acionada

Ou seja: a description é o que sempre está pago, e o corpo é o que você paga sob demanda. Isso muda completamente onde vale investir tempo de escrita

O que aprendi refatorando prompts em skills

No vídeo eu instalei uma skill chamada ‘self learning skills’ num projeto de teste meu, só pra ver como ela se comporta na prática. Instalei apenas no escopo do projeto, não globalmente, e configurada só pro Claude Code: eu gosto de ter esse controle sobre onde as skills rodam

Perguntei pro agente se ele estava monitorando a skill naquela sessão. A resposta foi que não havia processo ativo monitorando, e que ela funciona de forma reativa, disparando quando detecta padrões ou quando é pedida explicitamente

Depois pedi uma tarefa boba de propósito: subir a API do projeto e validar se a rota de produtos retornava JSON, sem mexer no código fonte

E aí veio a parte interessante. O npm install falhou por incompatibilidade de binário com a versão de node que eu estava usando. O agente contornou trocando a versão, criou o arquivo de ambiente, rodou a migração e subiu o servidor

No fim, ele identificou esse contorno como um "Golden Path" e sugeriu sozinho criar uma skill pra não precisar redescobrir aquilo em sessões futuras. Aceitei, e ele gerou a skill a partir do próprio processo

Fiz a contraprova: usei um script meu pra recriar as condições do erro e repeti o mesmo prompt. Na segunda execução o agente carregou a skill criada antes e resolveu direto, sem redescobrir nada, terminando mais rápido que na primeira. E no final dessa segunda rodada a própria skill foi ajustada por ele, o que mostra que ela se aprimora com o uso

Testei a memória também, pedindo explicitamente pra lembrar o nome do banco de staging do projeto, e vi a informação ser salva. A meta skill também consegue detectar sozinha, em outras sessões, coisas que valem virar memória, sem pedido explícito

O que eu mais gostei: funciona discreto em segundo plano, sem atrapalhar o fluxo, e só aparece sugerindo skill, memória ou regra quando identifica um padrão relevante

O aprendizado prático de tudo isso, pra quem está refatorando prompt na mão: o que precisou ficar mais explícito foi sempre o pressuposto. Aquilo que eu sabia e não escrevia

Mas não vá pro extremo oposto e escreva um roteiro linha por linha. As boas práticas oficiais tratam "graus de liberdade" como decisão de autoria: alto grau de liberdade significa dar direção geral e confiar no Claude pra achar o melhor caminho, como em code review, onde o contexto determina a abordagem

Então critério de qualidade fica firme, caminho fica solto

E o ganho de virar arquivo versionado é o que eu menos esperava valorizar: dá pra ver o diff da instrução. Você sabe o que mudou, quando e por quê. Coisa que o bloco de notas nunca te deu haha

Quais prompts valem virar skill (e quais não)

O corte é simples: frequência e estabilidade de formato

Se você repete o prompt e espera sempre o mesmo tipo de saída, vale. Se foi exploração de uma vez só, pra entender um problema específico, não vale. Vira manutenção sem retorno

O caso que eu acho mais subestimado é a skill de projeto versionada pro time

Quando a instrução de revisão vive em .claude/skills/ dentro do repo, todo mundo herda o mesmo critério. Não é mais "o prompt bom que o fulano tem salvo", é parte do projeto

E isso também resolve o problema de prompt que envelhece escondido. Se você já se pegou checando se seus prompts continuam funcionando depois de uma mudança de modelo, arquivo versionado é bem melhor que arqueologia no bloco de notas

Conclusão

A skill boa é o seu prompt menos a sua presença

É isso. Todo o trabalho de refatoração é identificar onde você era a peça que fazia a engrenagem girar, e transferir aquilo pro arquivo: o dado que você completava virou $ARGUMENTS, a pergunta que você respondia virou instrução de busca, o contexto que você tinha na cabeça virou texto em terceira pessoa

Próximo passo bem concreto pra fechar a semana:

1. Escolha o prompt que você mais recolou nos últimos dias
2. Corte ele em permanente versus variável
3. Publique como skill de projeto em .claude/skills/, com name e description
4. Use alguns dias sem invocar pela barra e refine a description conforme você vê quando ela dispara (e quando não dispara)

Esse quarto passo é o que separa skill que funciona de skill que fica parada na pasta

Até o próximo post!