skill-authoring

Skill Authoring

Guia para criar skills que realmente mudam o comportamento do agente, não documentos que nunca são lidos.

Princípio principal: skill é instrução operacional, não artigo. Se o agente não fizer nada diferente após carregar esta skill, ela falhou.

Como Usar Este Skill

Este skill é usado por meio de conversa, não de uma só vez. O fluxo é:

1. O usuário aciona o skill (exemplo: "use o skill skill-authoring, quero criar uma skill para meu agente").
2. O agente para de escrever e inicia a entrevista da Etapa 1: uma pergunta por vez, aguardando a resposta.
3. Após as cinco perguntas serem respondidas, o agente executa as Etapas 2 a 5 e mostra o rascunho para o usuário.
4. Após a aprovação do usuário, o agente escreve o arquivo (Etapa 6), executa o teste de ativação (Etapa 7) e a lista de verificação (Etapa 8).

Regras para o agente:

• Não escreva SKILL.md antes das cinco perguntas da Etapa 1 serem respondidas. Um rascunho prematuro interrompe a entrevista.
• Não faça as cinco perguntas de uma vez. Uma por vez, com um breve exemplo em cada pergunta.
• Se o usuário quiser apenas um "exemplo rápido", pergunte apenas as questões 1 e 4 e depois prossiga.
• Mencione no início que o resultado final é um único arquivo SKILL.md que pode ser usado diretamente.

Quando Este Skill Está Ativo

• O usuário diz "criar skill", "fazer skill", "como criar skill", "skill para meu agente".
• O usuário tem uma ideia para a capacidade do agente, mas não sabe como expressá-la.
• Uma skill existente nunca é acionada ou não é seguida pelo agente.
• É necessário decidir: isso deve ser uma skill, agent, command ou hook?

Para encontrar skills existentes, use skill-scout primeiro. Para auditar skills acumuladas, use skill-stocktake.

Etapa 0 - Regras Básicas Antes de Escrever

Uma boa skill tem quatro propriedades:

Propriedade	Significado
Específica	Responde a um tipo de trabalho, não a "tudo sobre backend"
Operacional	Contém etapas, comandos, exemplos reais, não teoria
Acionável	description contém palavras que o usuário realmente usa
Limitada	Abaixo de 500 linhas; idealmente 100-250 linhas

Se a ideia da skill não atender a essas quatro, melhore a ideia primeiro, não escreva o arquivo.

Etapa 1 - Capture o Problema Real, Não a Funcionalidade

Não comece com "skill para testes". Comece com uma falha concreta.

Faça estas cinco perguntas ao usuário (uma de cada vez, não todas de uma vez):

1. O que o agente faz errado ou de forma inconsistente agora? Dê um exemplo real.
2. Quando isso acontece? (escrevendo código, revisando PR, fazendo deploy, respondendo ao usuário, analisando dados)
3. Como é o resultado correto? Mostre um exemplo de saída que o usuário considera boa.
4. Qual informação o agente não sabe e deve ser informada por meio desta skill? (convenções da equipe, sequência de etapas, armadilhas)
5. O que o agente não deve fazer ao executar esta skill?

As respostas 4 e 5 são o conteúdo real da skill. As respostas 1 e 2 são o conteúdo da description.

Se o usuário não conseguir responder à pergunta 1, interrompa o processo. Ainda não há uma skill a ser criada – há apenas um desejo. Diga isso.

Etapa 2 - Escolha a Forma Correta

Não transforme tudo em skill. Escolha a forma mais barata que resolve o problema.

Necessidade	Forma	Motivo
Conhecimento/convenções usados repetidamente ao escrever código	Skill	Carregado automaticamente, não precisa ser invocado
Trabalho independente com várias etapas e contexto separado	Agent	Pode ser executado em paralelo, tem contexto próprio
Ação que o usuário aciona conscientemente com argumentos	Command	/{nome} explícito, não automático
Comportamento automático em eventos (antes do commit, após edição)	Hook	Executa sem decisão do modelo
Regra curta que se aplica a todo trabalho	Rule	Sempre ativo, sem acionador
Explicação longa para leitura humana	Documento	Não precisa ser carregado pelo agente

Regras práticas:

• Precisa de acionador? Skill.
• Precisa de contexto separado ou ferramentas limitadas? Agent.
• Precisa ser invocado manualmente com parâmetros? Command.
• Precisa executar sem ser solicitado? Hook.
• Precisa sempre estar correto, nunca violado? Rule.
• Precisa ser lido por humanos, não pelo agente? Documento.

Se estiver em dúvida entre skill e rule: se o conteúdo tiver menos de 10 linhas e se aplicar a tudo, é rule.

Etapa 3 - Procure Duplicatas Primeiro

Antes de escrever, procure primeiro. A pasta de skills difere por harness – adapte-se ao do usuário:

Harness	Pasta de skills
Claude Code	~/.claude/skills/ ou .claude/skills/ no projeto
OpenCode	~/.config/opencode/skills/ ou .opencode/skills/
Cursor	.cursor/skills/
Codex	.agents/skills/

# skill já instalado (substitua <pasta-skill> conforme a tabela acima)
grep -ril "palavras-chave" <pasta-skill> --include=SKILL.md

# se estiver dentro de um repositório com uma pasta skills/
grep -ril "palavras-chave" skills --include=SKILL.md

Se o usuário não souber a pasta de skills, explique a tabela acima e peça que ele escolha o harness que usa. Não adivinhe.

Se já existir uma correspondência próxima, escolha: usar como está, expandir a existente ou criar uma nova. Skills duplicadas confundem o agente na hora de escolher e sobrecarregam o contexto.

Etapa 4 - Escreva a description (Parte Mais Decisiva)

description é a única parte que o agente lê para decidir se carrega a skill ou não. Errar aqui significa skill morta.

Fórmula:

[atividade executada] + [contexto de ativação] + [palavras-chave usadas pelo usuário] + [quando NÃO usar]

Exemplo ruim:

description: Ajuda com testes

Exemplo bom:

description: Padrões de teste React com Vitest e Testing Library - render, eventos de usuário, mock de rede e asserções de acessibilidade. Use ao escrever ou corrigir testes de componentes React. Não para E2E (use e2e-testing).

Regras:

• Mencione palavras que o usuário realmente digita, não termos internos.
• Mencione os limites para que a skill não roube o trabalho de outras skills.
• Uma linha, sem quebras de linha dentro da string.
• Evite palavras genéricas únicas como "código", "ajuda", "vários".

Teste rápido: feche o arquivo, leia apenas a description. Se você como agente não souber exatamente quando carregá-la, reescreva.

Etapa 5 - Estruture o Conteúdo

Ordem das seções que funciona:

---
name: nome-da-skill
description: <fórmula da Etapa 4>
metadata:
  origin: ECC
---

# Título

Um parágrafo: o que esta skill muda no comportamento do agente.

## Quando Ativo
Lista de acionadores concretos.

## Núcleo
Etapas de trabalho, tabela de decisão ou regras. Isso é 70% do conteúdo da skill.

## Exemplo
Um exemplo errado, um exemplo certo. Reais, não placeholders.

## Anti-Padrões
Erros a serem evitados, com breve justificativa.

## Lista de Verificação
Caixas de seleção que podem ser verificadas.

## Skills Relacionados
Dois a quatro nomes de skills.

Regras de redação do conteúdo:

• Frases imperativas ("Faça X"), não descrição passiva ("X pode ser feito").
• Tabelas para decisões, listas numeradas para sequências, blocos de código para comandos.
• Cada regra deve ser verificável – "escreva código limpo" não é, "função com no máximo 50 linhas" é.
• Sem placeholders como [insira aqui], TODO ou ... em partes executadas pelo agente.
• Sem identidade de produto externo copiada diretamente – pegue a ideia, reescreva com seu próprio contexto.
• Sem segredos: chave de API, token, caminho pessoal absoluto, nomes internos da empresa.

Limite de tamanho: 500 linhas (máximo absoluto 800). Se ultrapassar, divida em duas skills ou mova os detalhes para references/ na mesma pasta da skill.

Etapa 6 - Escreva o Arquivo

Antes de escrever, faça duas últimas perguntas:

1. Idioma da skill – o idioma que o usuário usa no dia a dia, ou inglês para portabilidade? Siga a resposta, não escolha por conta própria.
2. Nome da pasta – sugira um nome kebab-case descritivo (exemplo: teste-componentes-react), peça aprovação.

Depois, escreva em <pasta-skill>/<nome>/SKILL.md. Regras que não podem ser quebradas:

• name: no frontmatter exatamente igual ao nome da pasta. Sem isso, alguns harnesses se recusam a carregar a skill.
• Mostre o rascunho completo ao usuário primeiro, depois salve. Não salve silenciosamente.
• Sem placeholders (TODO, [insira aqui], ...) em partes que serão executadas pelo agente.
• Após salvar, informe o caminho completo e uma frase sobre como acionar: "Depois disso, peça ao agente para usar a skill <nome> quando ."

Etapa 7 - Teste Antes de Usar

Três testes mínimos. Não pule nenhum.

Teste 1 - Acionador positivo (ativando) Dê ao agente uma tarefa que deveria acionar esta skill, sem mencionar o nome da skill.

"Escreva um teste para o componente LoginButton."

Passa se a skill for carregada. Falha se a description não tiver palavras-chave suficientes.

Teste 2 - Acionador negativo (não ativando) Dê uma tarefa semelhante, mas fora do domínio.

"Escreva um teste E2E para o fluxo de login."

Passa se a skill NÃO for carregada (ou se o agente escolher outra skill apropriada). Falha se a description for muito ampla.

Teste 3 - Execução Peça ao agente para realizar uma tarefa que realmente acione a skill e compare a saída com e sem a skill.

Sem a skill: o agente escreve teste estilo X
Com a skill: o agente escreve teste estilo Y (de acordo com a convenção da equipe)

Passa se houver uma diferença de comportamento demonstrável. Se a saída for idêntica, a skill é inútil – exclua ou mescle.

Etapa 8 - Lista de Verificação Pronta para Envio

• O arquivo está em <pasta-skill>/{nome}/SKILL.md, e name: é exatamente igual ao nome da pasta
• description tem uma linha, contém palavras-chave do usuário e escopo
• description não usa bloco literal (|), apenas string em linha
• Há uma seção "Quando Ativo" explícita
• Cada regra é verificável, sem "escreva código bom"
• Há pelo menos um exemplo errado e um exemplo certo
• Há anti-padrões
• Abaixo de 500 linhas
• Sem segredos, token ou caminho pessoal absoluto
• Testes 1, 2 e 3 foram executados e resultados registrados
• A Etapa 3 foi executada, sem duplicatas
• Menciona de 2 a 4 skills relacionados no final

Validação automática apenas se disponível no repositório do usuário:

# ECC / repositório que possui validador de skills
node scripts/ci/validate-skills.js

Se não houver validador, verifique manualmente as quatro coisas que mais falham: name: coincide com a pasta, description em uma linha, linhas abaixo de 500 e sem placeholders. Informe ao usuário que esta verificação manual é a utilizada.

Modelo Pronto para Uso

---
name: nome-da-skill
description: <atividade> - <escopo>. Use quando <acionador concreto>. Não para <fora do escopo>.
metadata:
  origin: ECC
---

# Nome da Skill

O que muda no comportamento do agente após carregar esta skill.

## Quando Ativo
- <acionador 1>
- <acionador 2>

## Etapas
1. <primeira etapa que pode ser executada diretamente>
2. <segunda etapa>
3. <verificação>

## Exemplo
Errado: <código ou resposta que costuma aparecer>
Certo: <versão desejada, com breve justificativa>

## Anti-Padrões
- <erro> - <por que é ruim>

## Lista de Verificação
- [ ] <o que pode ser verificado por máquina ou olho>

## Skills Relacionados
- `<skill-a>`, `<skill-b>`

Anti-Padrões de Criação

• Skill sem acionador. description vaga, skill nunca é carregada. Esta é a causa de falha mais comum.
• Skill parede de texto. 900 linhas de teoria sem um comando. O agente carrega e ignora.
• Skill "seja útil". Sem conhecimento específico, o resultado é idêntico ao de não ter a skill.
• Skill duplicada. Duas skills reivindicam o mesmo domínio; o agente escolhe aleatoriamente.
• Copiar skill de outra pessoa por inteiro. Inclui instruções ocultas e dependências que você não percebe.
• Skill com segredo ou caminho pessoal. Acaba sendo compartilhado quando a skill é distribuída.
• Criar skill para um evento único. Se for usado apenas uma vez, não é skill – é documentação ou command.
• Criar skill antes de pesquisar. Sempre execute a Etapa 3.

Quando NÃO Criar uma Skill

Diga claramente ao usuário se alguma destas condições for verdadeira:

• O problema é um bug no código, não falta de conhecimento do agente.
• Precisa ser executado apenas uma vez – basta dar instruções diretas.
• O conteúdo tem menos de 10 linhas de regras gerais – é rule.
• Basta adicionar ao AGENTS.md ou CLAUDE.md do projeto.
• Já existe uma skill que cobre 80% da necessidade – expanda a existente.

Skills Relacionados

• skill-scout - encontra skills existentes antes de criar novas
• skill-stocktake - audita a qualidade de skills acumuladas
• skill-comply - mede se a skill é realmente seguida pelo agente
• agent-harness-construction - projeta ferramentas e limites de ação do agente