Nova Skill

Escrevendo uma skill para o skills-space

O modelo mental

Uma skill não é documentação. É contexto que entra na cabeça do agente no momento certo e some depois. O agente carrega apenas a description de todas as skills o tempo todo; o corpo só entra em contexto quando a descrição casa com a tarefa.

Isso define as duas responsabilidades, e elas são bem diferentes:

• description — precisa fazer o agente decidir carregar. É um problema de recall.
• corpo — precisa fazer o agente acertar. É um problema de instrução.

Quase toda skill que "não funciona" na verdade nunca foi carregada. Suspeite da description antes de reescrever o corpo.

Passo 1: confirme que precisa existir

Não escreva uma skill quando:

• o agente já acerta sem ela (teste antes: rode a tarefa sem skill nenhuma);
• é uma regra sempre-válida do repositório — isso é CLAUDE.md, não skill;
• é conhecimento de uso único — isso é uma mensagem, não skill.

Escreva quando existe um procedimento repetível, específico do time e que o agente erra sozinho. Se você não consegue nomear o erro que ela evita, ainda não há skill.

Passo 2: escolha o bundle

Skills vivem dentro de um bundle, que é a unidade que o time instala:

plugins/<bundle>/skills/<sua-skill>/SKILL.md

Prefira sempre um bundle existente. Crie um novo só quando um time diferente for dono das skills e o público for outro — bundle demais faz o time instalar cinco coisas em vez de uma. Se criar, escreva também plugins/<bundle>/.claude-plugin/plugin.json com name (igual ao diretório), description, version e author.

Passo 3: escreva a description

Este é o trabalho de verdade. Formato:

Use quando <gatilhos concretos, do jeito que a pessoa fala> — <variações>.

Coloque as palavras que o usuário realmente digita, não os termos internos do time. Se o pessoal fala "subir pra prod", a description precisa conter "subir pra prod", não apenas "deploy em produção".

# ruim — descreve a skill, não o gatilho; nunca vai disparar
description: Padrões de acessibilidade do design system.

# bom — nomeia as situações que devem carregá-la
description: Use quando for criar ou revisar componentes de UI — modal, dropdown,
  formulário, tabela — ou quando alguém perguntar sobre foco, leitor de tela,
  contraste, navegação por teclado ou aria-*.

Erros que o validador não pega, mas que matam a skill:

• descrição genérica demais → dispara em tudo e polui o contexto;
• descrição estreita demais → só dispara na frase exata que você imaginou;
• descrever o conteúdo ("Guia de X") em vez da situação ("Use quando X").

Passo 4: escreva o corpo

Escreva para um colega competente que não conhece as convenções do time. Regras:

• Imperativo, não descritivo. "Rode npm run lint antes de commitar", não "o projeto usa lint".
• Exemplo certo e errado lado a lado. Um par ruim/bom ensina mais que três parágrafos.
• Diga o que não fazer quando existe um atalho tentador e errado.
• Corte o óbvio. Se o agente já faz sem instrução, cada linha extra só compete por atenção com o que importa.
• Determinismo vira script. Se o passo é mecânico e sempre igual, ponha um script em scripts/ ao lado do SKILL.md e mande executá-lo. É mais barato e não varia.

Arquivos de apoio ficam no diretório da skill e são lidos sob demanda:

skills/minha-skill/
  SKILL.md
  references/tabela-completa.md    ← só carrega se o corpo mandar abrir
  scripts/checar.mjs

Mantenha o SKILL.md abaixo de ~500 linhas. Passou disso, mova detalhe para references/ e deixe o corpo apontar para lá.

Passo 5: preencha o metadata

metadata:
  owner: "@thiagopbraga"   # quem responde quando quebra. Obrigatório.
  stability: experimental     # stable | beta | experimental
  targets: [claude]           # onde publicar
  tags: [ci, deploy]

Sobre stability: comece em experimental. Suba para beta quando outra pessoa já usou, e para stable quando o time depende dela e você aceita ser cobrado por regressão.

Sobre targets: deixe em [claude] a menos que tenha um motivo. Claude Code carrega skill sob demanda; Cursor e Copilot carregam de forma bem mais agressiva. Exportar tudo para todo lugar enfia o catálogo inteiro no contexto de cada prompt e degrada todos os agentes. Exporte para cursor, copilot ou agents só quando o time realmente usa aquele agente para aquela tarefa.

Se exportar: o corpo é copiado literalmente, então caminhos relativos para references/ e scripts/ quebram. Skills multi-target precisam ser autocontidas.

Passo 6: valide e gere

npm run validate      # erros e avisos
npm run build         # regenera marketplace.json, CATALOG.md, docs/ e dist/

Commite os artefatos gerados junto. O CI roda npm run check e reprova o PR se dist/, docs/ ou marketplace.json estiverem fora de sincronia com plugins/.

Passo 7: teste de verdade

Validador confere formato, não eficácia. Antes de abrir o PR:

1. Abra uma sessão nova (contexto limpo).
2. Digite a tarefa como um colega digitaria — não cite o nome da skill.
3. Confirme que ela carregou.
4. Se não carregou, o problema é a description. Volte ao passo 3.
5. Se carregou e o resultado ficou errado, o problema é o corpo. Volte ao passo 4.

Rodar direto com um comando explícito prova apenas que o arquivo existe — o gatilho continua sem teste.