Writing Skills

Escrevendo Skills

Visão Geral

Escrever skills É Test-Driven Development aplicado à documentação de processos.

Skills pessoais vivem em diretórios específicos do agente (~/.claude/skills para Claude Code, ~/.codex/skills para Codex)

Você escreve casos de teste (cenários de pressão com subagentes), os vê falhar (comportamento inicial), escreve a skill (documentação), os vê passar (agentes obedecem), e refatora (fecha lacunas).

Princípio central: Se você não assistiu um agente falhar sem a skill, você não sabe se a skill ensina a coisa certa.

BACKGROUND OBRIGATÓRIO: Você DEVE compreender superpowers:test-driven-development antes de usar essa skill. Aquela skill define o ciclo fundamental RED-GREEN-REFACTOR. Esta skill adapta TDD para documentação.

Orientação oficial: Para as melhores práticas oficiais de criação de skills da Anthropic, veja anthropic-best-practices.md. Este documento fornece padrões e diretrizes adicionais que complementam a abordagem focada em TDD nessa skill.

O que é uma Skill?

Uma skill é um guia de referência para técnicas comprovadas, padrões ou ferramentas. Skills ajudam futuras instâncias do Claude a encontrar e aplicar abordagens eficazes.

Skills são: Técnicas reutilizáveis, padrões, ferramentas, guias de referência

Skills NÃO são: Narrativas sobre como você resolveu um problema uma vez

Mapeamento TDD para Criação de Skills

Todo o processo de criação de skill segue RED-GREEN-REFACTOR.

Quando Criar uma Skill

Criar quando:

• Técnica não era intuitivamente óbvia para você
• Você consultaria isso novamente em projetos diferentes
• Padrão se aplica amplamente (não específico do projeto)
• Outros se beneficiariam

Não criar para:

• Soluções únicas
• Práticas padrão bem documentadas em outro lugar
• Convenções específicas do projeto (coloque em CLAUDE.md)
• Restrições mecânicas (se é executável com regex/validação, automatize—reserve documentação para julgamentos)

Tipos de Skill

Técnica

Método concreto com passos a seguir (condition-based-waiting, root-cause-tracing)

Padrão

Forma de pensar sobre problemas (flatten-with-flags, test-invariants)

Referência

Docs de API, guias de sintaxe, documentação de ferramentas (office docs)

Estrutura de Diretórios

skills/
  skill-name/
    SKILL.md              # Referência principal (obrigatório)
    supporting-file.*     # Apenas se necessário

Namespace plano - todas as skills em um namespace pesquisável

Arquivos separados para:

1. Referência pesada (100+ linhas) - Docs de API, sintaxe abrangente
2. Ferramentas reutilizáveis - Scripts, utilitários, templates

Mantenha inline:

• Princípios e conceitos
• Padrões de código (< 50 linhas)
• Tudo mais

Defina Graus Apropriados de Liberdade

Alinhe o nível de especificidade à fragilidade e variabilidade da tarefa:

• Alta liberdade (instruções baseadas em texto): Use quando múltiplas abordagens são válidas ou decisões dependem de contexto.
• Liberdade média (pseudocódigo ou scripts com parâmetros): Use quando um padrão preferido existe mas algumas variações são aceitáveis.
• Baixa liberdade (scripts específicos, instruções sem contexto): Use quando operações são frágeis, propensas a erro, ou consistência é crítica.

Revelação Progressiva

Gerencie contexto eficientemente ao dividir informações detalhadas em arquivos separados:

1. Metadados (nome + descrição): Sempre carregado para discovery.
2. Corpo SKILL.md: Workflow central e orientação de alto nível. Mantenha sob 500 linhas.
3. Recursos agregados:
   • scripts/: Código/lógica determinística.
   • references/: Schemas detalhados, docs de API, ou conhecimento de domínio.
   • assets/: Templates, imagens, ou arquivos estáticos.

Padrão: Vincule conteúdo avançado ou detalhes específicos de variantes (ex: aws.md vs gcp.md) do SKILL.md principal.

Estrutura SKILL.md

Frontmatter (YAML):

• Apenas dois campos suportados: name e description
• Máximo 1024 caracteres total
• name: Use apenas letras, números e hífens (sem parênteses, caracteres especiais)
• description: Terceira pessoa, descreve APENAS quando usar (NÃO o que faz)
  • Comece com "Use when..." para focar em condições de ativação
  • Inclua sintomas, situações e contextos específicos
  • NUNCA resuma o processo ou workflow da skill (veja seção CSO para o porquê)
  • Mantenha sob 500 caracteres se possível

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

# Nome da Skill

## Visão Geral

O que é isso? Princípio central em 1-2 frases.

## Quando Usar

[Pequeno fluxograma inline SE decisão não for óbvia]

Lista com SINTOMAS e casos de uso
Quando NÃO usar

## Padrão Central (para técnicas/padrões)

Comparação antes/depois de código

## Referência Rápida

Tabela ou bullets para scanning de operações comuns

## Implementação

Código inline para padrões simples
Link para arquivo para referência pesada ou ferramentas reutilizáveis

## Erros Comuns

O que dá errado + correções

## Impacto no Mundo Real (opcional)

Resultados concretos

Otimização de Busca Claude (CSO)

Crítico para discovery: Claude futuro precisa ENCONTRAR sua skill

1. Campo de Descrição Rico

Propósito: Claude lê descrição para decidir quais skills carregar para uma tarefa. Faça-a responder: "Devo ler essa skill agora?"

Formato: Comece com "Use when..." para focar em condições de ativação

CRÍTICO: Descrição = Quando Usar, NÃO O que a Skill Faz

A descrição deve APENAS descrever condições de ativação. NÃO resuma o processo ou workflow da skill na descrição.

Por que isso importa: Testes revelaram que quando uma descrição resume o workflow da skill, Claude pode seguir a descrição em vez de ler o conteúdo completo. Uma descrição dizendo "revisão de código entre tarefas" causou Claude fazer UMA revisão, mesmo que o fluxograma da skill claramente mostrasse DUAS revisões (conformidade de spec depois qualidade de código).

Quando a descrição foi mudada para apenas "Use when executing implementation plans with independent tasks" (sem resumo de workflow), Claude corretamente leu o fluxograma e seguiu o processo de revisão de dois estágios.

A armadilha: Descrições que resumem workflow criam um atalho que Claude vai levar. O corpo da skill se torna documentação que Claude pula.

# ❌ RUIM: Resume workflow - Claude pode seguir isso em vez de ler skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ❌ RUIM: Muitos detalhes de processo
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# ✅ BOM: Apenas condições de ativação, sem resumo de workflow
description: Use when executing implementation plans with independent tasks in the current session

# ✅ BOM: Apenas condições de ativação
description: Use when implementing any feature or bugfix, before writing implementation code

Conteúdo:

• Use triggers concretos, sintomas e situações que sinalizam que essa skill se aplica
• Descreva o problema (race conditions, comportamento inconsistente) não sintomas específicos de linguagem (setTimeout, sleep)
• Mantenha triggers agnósticos de tecnologia a menos que a skill em si seja específica de tecnologia
• Se skill é específica de tecnologia, deixe isso explícito no trigger
• Escreva em terceira pessoa (injetado em system prompt)
• NUNCA resuma o processo ou workflow da skill

# ❌ RUIM: Muito abstrato, vago, não inclui quando usar
description: For async testing

# ❌ RUIM: Primeira pessoa
description: I can help you with async tests when they're flaky

# ❌ RUIM: Menciona tecnologia mas skill não é específica para ela
description: Use when tests use setTimeout/sleep and are flaky

# ✅ BOM: Começa com "Use when", descreve problema, sem workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# ✅ BOM: Skill específica de tecnologia com trigger explícito
description: Use when using React Router and handling authentication redirects

2. Cobertura de Palavras-chave

Use palavras que Claude buscaria:

• Mensagens de erro: "Hook timed out", "ENOTEMPTY", "race condition"
• Sintomas: "flaky", "hanging", "zombie", "pollution"
• Sinônimos: "timeout/hang/freeze", "cleanup/teardown/afterEach"
• Ferramentas: Comandos reais, nomes de biblioteca, tipos de arquivo

3. Nomenclatura Descritiva

Use voz ativa, verbo primeiro:

• ✅ creating-skills não skill-creation
• ✅ condition-based-waiting não async-test-helpers

4. Eficiência de Tokens (Crítico)

Problema: skills getting-started e frequentemente-referenciadas carregam em TODA conversa. Cada token conta.

Contagem de palavras alvo:

• Workflows getting-started: <150 palavras cada
• Skills frequentemente-carregadas: <200 palavras total
• Outras skills: <500 palavras (ainda seja conciso)

Técnicas:

Mova detalhes para ajuda de ferramenta:

# ❌ RUIM: Documente todas as flags em SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ BOM: Referencie --help
search-conversations supports multiple modes and filters. Run --help for details.

Use referências cruzadas:

# ❌ RUIM: Repita detalhes de workflow

When searching, dispatch subagent with template...
[20 linhas de instruções repetidas]

# ✅ BOM: Referencie outra skill

Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

Comprima exemplos:

# ❌ RUIM: Exemplo verboso (42 palavras)

your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# ✅ BOM: Exemplo mínimo (20 palavras)

Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]

Elimine redundância:

• Não repita o que está em skills referenciadas
• Não explique o que é óbvio a partir do comando
• Não inclua múltiplos exemplos do mesmo padrão

Verificação:

wc -w skills/path/SKILL.md
# workflows getting-started: aim for <150 each
# Other frequently-loaded: aim for <200 total

Nomeie pelo que você FAZ ou insight central:

• ✅ condition-based-waiting > async-test-helpers
• ✅ using-skills não skill-usage
• ✅ flatten-with-flags > data-structure-refactoring
• ✅ root-cause-tracing > debugging-techniques

Gerúndios (-ing) funcionam bem para processos:

• creating-skills, testing-skills, debugging-with-logs
• Ativo, descreve a ação que você está tomando

4. Referenciação Cruzada de Outras Skills

Ao escrever documentação que referencia outras skills:

Use apenas nome da skill, com marcadores de requisito explícitos:

• ✅ Bom: **REQUIRED SUB-SKILL:** Use superpowers:test-driven-development
• ✅ Bom: **REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging
• ❌ Ruim: See skills/testing/test-driven-development (não fica claro se obrigatório)
• ❌ Ruim: @skills/testing/test-driven-development/SKILL.md (força-carrega, queima contexto)

Por que não links @: Sintaxe @ força-carrega arquivos imediatamente, consumindo 200k+ contexto antes de você precisar.

Uso de Fluxogramas

digraph when_flowchart {
    "Need to show information?" [shape=diamond];
    "Decision where I might go wrong?" [shape=diamond];
    "Use markdown" [shape=box];
    "Small inline flowchart" [shape=box];

    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
}

Use fluxogramas APENAS para:

• Pontos de decisão não-óbvios
• Loops de processo onde você pode parar cedo
• Decisões "Quando usar A vs B"

Nunca use fluxogramas para:

• Material de referência → Tabelas, listas
• Exemplos de código → Blocos markdown
• Instruções lineares → Listas numeradas
• Labels sem significado semântico (step1, helper2)

Veja @graphviz-conventions.dot para regras de estilo graphviz.

Visualizando para seu parceiro humano: Use render-graphs.js neste diretório para renderizar fluxogramas da skill para SVG:

./render-graphs.js ../some-skill           # Cada diagrama separadamente
./render-graphs.js ../some-skill --combine # Todos os diagramas em um SVG

Exemplos de Código

Um excelente exemplo bate muitos mediocres

Escolha linguagem mais relevante:

• Técnicas de teste → TypeScript/JavaScript
• Debugging de sistema → Shell/Python
• Processamento de dados → Python

Bom exemplo:

• Completo e executável
• Bem-comentado explicando POR QUE
• De cenário real
• Mostra padrão claramente
• Pronto para adaptar (não template genérico)

Não:

• Implemente em 5+ linguagens
• Crie templates preencha-os-espaços
• Escreva exemplos contritos

Você é bom em portar - um ótimo exemplo é suficiente.

Organização de Arquivos

Skill Autossuficiente

defense-in-depth/
  SKILL.md    # Tudo inline

Quando: Todo conteúdo cabe, nenhuma referência pesada necessária

Skill com Ferramenta Reutilizável

condition-based-waiting/
  SKILL.md    # Visão geral + padrões
  example.ts  # Helpers de trabalho para adaptar

Quando: Ferramenta é código reutilizável, não apenas narrativa

Skill com Referência Pesada

pptx/
  SKILL.md       # Visão geral + workflows
  pptxgenjs.md   # 600 linhas de referência de API
  ooxml.md       # 500 linhas de estrutura XML
  scripts/       # Ferramentas executáveis

Quando: Material de referência muito grande para inline

A Lei de Ferro (Mesma que TDD)

NENHUMA SKILL SEM UM TESTE FALHANDO PRIMEIRO

Isso se aplica a skills NOVAS E EDIÇÕES de skills existentes.

Escrever skill antes de testar? Delete-a. Comece de novo. Editar skill sem testar? Mesma violação.

Sem exceções:

• Não para "adições simples"
• Não para "apenas adicionar uma seção"
• Não para "atualizações de documentação"
• Não mantenha mudanças não-testadas como "referência"
• Não "adapte" enquanto roda testes
• Deletar significa deletar

BACKGROUND OBRIGATÓRIO: A skill superpowers:test-driven-development explica por que isso importa. Os mesmos princípios se aplicam à documentação.

Testando Todos os Tipos de Skill

Diferentes tipos de skill precisam de diferentes abordagens de teste:

Skills que Reforçam Disciplina (regras/requisitos)

Exemplos: TDD, verification-before-completion, designing-before-coding

Teste com:

• Questões acadêmicas: Eles compreendem as regras?
• Cenários de pressão: Eles obedecem sob estresse?
• Múltiplas pressões combinadas: tempo + custo afundado + exaustão
• Identifique racionalizações e adicione contadores explícitos

Critério de sucesso: Agente segue regra sob pressão máxima

Skills de Técnica (guias como fazer)

Exemplos: condition-based-waiting, root-cause-tracing, defensive-programming

Teste com:

• Cenários de aplicação: Conseguem aplicar técnica corretamente?
• Cenários de variação: Conseguem lidar com edge cases?
• Testes de informação faltante: Instruções têm lacunas?

Critério de sucesso: Agente aplica com sucesso técnica a novo cenário

Skills de Padrão (modelos mentais)

Exemplos: reducing-complexity, conceitos information-hiding

Teste com:

• Cenários de reconhecimento: Reconhecem quando padrão se aplica?
• Cenários de aplicação: Conseguem usar modelo mental?
• Contra-exemplos: Sabem quando NÃO aplicar?

Critério de sucesso: Agente corretamente identifica quando/como aplicar padrão

Skills de Referência (documentação/APIs)

Exemplos: Documentação de API, referências de comando, guias de biblioteca

Teste com:

• Cenários de recuperação: Conseguem encontrar informação certa?
• Cenários de aplicação: Conseguem usar o que encontraram corretamente?
• Testes de lacuna: Casos de uso comuns estão cobertos?

Critério de sucesso: Agente encontra e aplica corretamente informação de referência

Racionalizações Comuns para Pular Testes

Todos estes significam: Teste antes de fazer deploy. Sem exceções.

À Prova de Rationalização de Skills

Skills que reforçam disciplina (como TDD) precisam resistir a rationalização. Agentes são inteligentes e encontrarão lacunas quando sob pressão.

Nota de psicologia: Compreender POR QUE técnicas de persuasão funcionam ajuda você aplicá-las sistematicamente. Veja persuasion-principles.md para fundação de pesquisa (Cialdini, 2021; Meincke et al., 2025) em autoridade, commitment, escassez, prova social, e princípios de unidade.

Feche Toda Lacuna Explicitamente

Não apenas declare a regra - proíba truques específicos:

No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

</Bom>

### Endereçar Argumentos "Espírito vs Letra"

Adicione princípio fundacional cedo:

```markdown
**Violating the letter of the rules is violating the spirit of the rules.**

Isso corta classe inteira de racionalizações "Estou seguindo o espírito".

Construa Tabela de Rationalização

Capture racionalizações de teste baseline (veja seção Testing abaixo). Toda desculpa que agentes fazem vai na tabela:

| Desculpa                         | Realidade                                                               |
| -------------------------------- | ----------------------------------------------------------------------- |
| "Muito simples para testar"      | Código simples quebra. Teste leva 30 segundos.                          |
| "Testarei depois"                | Testes passando imediatamente não provam nada.                          |
| "Testes depois atingem os mesmos objetivos" | Testes-depois = "o que isso faz?" Testes-primeiro = "o que deve fazer?" |

Crie Lista de Red Flags

Facilite que agentes se auto-verifiquem quando racionalizando:

## Red Flags - STOP e Comece de Novo

- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

Atualize CSO para Sintomas de Violação

Adicione à descrição: sintomas de quando você está PRESTES a violar a regra:

description: use when implementing any feature or bugfix, before writing implementation code

RED-GREEN-REFACTOR para Skills

Siga o ciclo TDD:

RED: Escrever Teste Falhando (Baseline)

Rodar cenário de pressão com subagente SEM a skill. Documentar comportamento exato:

• Que escolhas fizeram?
• Que racionalizações usaram (verbatim)?
• Quais pressões dispararam violações?

Isso é "observar o teste falhar" - você deve ver o que agentes naturalmente fazem antes de escrever a skill.

GREEN: Escrever Skill Mínima

Escrever skill que endereça essas racionalizações específicas. Não adicione conteúdo extra para casos hipotéticos.

Rodar mesmos cenários COM skill. Agente deve agora obedecer.

REFACTOR: Fechar Lacunas

Agente encontrou nova rationalização? Adicione contador explícito. Re-teste até à prova de bala.

Metodologia de teste: Veja @testing-skills-with-subagents.md para metodologia completa de teste:

• Como escrever cenários de pressão
• Tipos de pressão (tempo, custo afundado, autoridade, exaustão)
• Fechando buracos sistematicamente
• Técnicas de meta-teste

Anti-Padrões

❌ Exemplo Narrativo

"Em sessão 2025-10-03, descobrimos que projectDir vazio causava..." Por que ruim: Muito específico, não reutilizável

❌ Dilução Multi-Linguagem

example-js.js, example-py.py, example-go.go Por que ruim: Qualidade mediocre, carga de manutenção

❌ Código em Fluxogramas

step1 [label="import fs"];
step2 [label="read file"];

Por que ruim: Não consegue copiar-colar, difícil de ler

❌ Labels Genéricos

helper1, helper2, step3, pattern4 Por que ruim: Labels devem ter significado semântico

PARE: Antes de Mover para Próxima Skill

Depois de escrever QUALQUER skill, você DEVE PARAR e completar o processo de deployment.

NÃO:

• Crie múltiplas skills em batch sem testar cada uma
• Mude para próxima skill antes da atual estar verificada
• Pule testes porque "batching é mais eficiente"

O checklist de deployment abaixo é OBRIGATÓRIO para CADA skill.

Fazer deploy de skills não-testadas = fazer deploy de código não-testado. É uma violação de padrões de qualidade.

Checklist de Criação de Skill (TDD Adaptado)

IMPORTANTE: Use TodoWrite para criar todos para CADA item de checklist abaixo.

Fase RED - Escrever Teste Falhando:

• Criar cenários de pressão (3+ pressões combinadas para skills de disciplina)
• Rodar cenários SEM skill - documentar comportamento baseline verbatim
• Identificar padrões em racionalizações/falhas

Fase GREEN - Escrever Skill Mínima:

• Nome usa apenas letras, números, hífens (sem parênteses/caracteres especiais)
• Frontmatter YAML com apenas name e description (máx 1024 chars)
• Description começa com "Use when..." e inclui triggers/sintomas específicos
• Description escrita em terceira pessoa
• Palavras-chave ao longo de tudo para busca (erros, sintomas, ferramentas)
• Visão geral clara com princípio central
• Endereçar falhas baseline específicas identificadas em RED
• Código inline OU link para arquivo separado
• Um excelente exemplo (não multi-linguagem)
• Rodar cenários COM skill - verificar que agentes agora obedecem

Fase REFACTOR - Fechar Lacunas:

• Identificar NOVAS racionalizações do teste
• Adicionar contadores explícitos (se skill de disciplina)
• Construir tabela de rationalização de todas iterações de teste
• Criar lista de red flags
• Re-testar até à prova de bala

Verificações de Qualidade:

• Pequeno fluxograma apenas se decisão não-óbvia
• Tabela de referência rápida
• Seção de erros comuns
• Sem narrativa de storytelling
• Arquivos de suporte apenas para ferramentas ou referência pesada

Deployment:

• Commit skill para git e push para seu fork (se configurado)
• Considere contribuir de volta via PR (se amplamente útil)

Workflow de Discovery

Como Claude futuro encontra sua skill:

1. Encontra problema ("testes são flaky")
2. Encontra SKILL (descrição combina)
3. Escaneia visão geral (isso é relevante?)
4. Lê padrões (tabela de referência rápida)
5. Carrega exemplo (apenas quando implementando)

Otimize para este fluxo - coloque termos pesquisáveis cedo e frequentemente.

A Mensagem Principal

Criar skills É TDD para documentação de processo.

Mesma Lei de Ferro: Nenhuma skill sem teste falhando primeiro. Mesmo ciclo: RED (baseline) → GREEN (escrever skill) → REFACTOR (fechar lacunas). Mesmos benefícios: Melhor qualidade, menos surpresas, resultados à prova de bala.

Se você segue TDD para código, siga para skills. É a mes