writing-skills

Visão geral

O que a skill writing-skills faz

A writing-skills é uma meta-skill para quem cria, refina e testa outras skills para agentes como o Claude. Ela adapta o clássico Test-Driven Development (TDD) para documentação de processos, para que suas skills fiquem:

• Ancoradas em cenários reais de pressão
• Verificadas contra falhas reais de agentes
• Refinadas para fechar brechas e resistir à racionalização

Você usa writing-skills para desenhar skills que os agentes conseguem descobrir, seguir e continuar seguindo mesmo sob pressão de tempo, viés de custo afundado ou incentivos conflitantes.

Para quem é a writing-skills

Use a skill writing-skills se você é:

• Um desenvolvedor criando skills para Claude ou agentes semelhantes
• Um líder de equipe padronizando fluxos de trabalho em ~/.claude/skills ou ~/.agents/skills/
• Um responsável por documentação que cuida de skills que precisam ser seguidas, não apenas lidas
• Um tester validando se as skills realmente mudam o comportamento do agente antes da liberação

Ela não foca em estilo de escrita genérico. O foco específico é criar skills de agentes eficazes e testáveis.

Problemas que esta skill ajuda a resolver

A writing-skills foi criada para situações em que:

• Os agentes ignoram ou seguem apenas parcialmente suas skills sob pressão
• Você não tem certeza se uma nova skill muda de fato o comportamento
• Você precisa de uma forma repetível de testar skills com subagentes antes da implantação
• Você quer se alinhar às melhores práticas de criação de skills da Anthropic sem precisar adivinhar
• Você precisa visualizar e comunicar fluxos de skills complexos usando Graphviz

Se você tem skills que funcionam mais como histórias únicas ou anotações soltas, writing-skills ajuda a transformá-las em guias de referência reutilizáveis e testáveis.

Quando writing-skills é ou não uma boa escolha

Boa escolha:

• Skills que impõem disciplina (TDD, verificação, checklists de revisão)
• Skills que têm um verdadeiro custo de conformidade (tempo, retrabalho, atraso em entregas)
• Skills que os agentes podem tentar contornar ("só desta vez")
• Skills nas quais você quer melhorar de forma mensurável as taxas de conformidade

Não é uma boa escolha:

• Skills puramente de referência (por exemplo, sintaxe de API, cheatsheets básicos de linguagem)
• Skills que intencionalmente não têm regras a serem violadas
• Notas leves em que você não precisa de testes ao estilo TDD ou cenários de pressão

Se você só precisa de uma nota rápida e informal para uma conversa específica, provavelmente não precisa de writing-skills. Se você quer uma skill que sobreviva à pressão de produção, precisa.

Como usar

Instalação e configuração básica

Para instalar a skill writing-skills em um ambiente que reconhece skills:

npx skills add https://github.com/obra/superpowers --skill writing-skills

Esse comando busca a skill writing-skills no repositório obra/superpowers e a registra junto com suas outras skills.

Skills pessoais normalmente ficam em diretórios específicos do agente, por exemplo:

• ~/.claude/skills/ para Claude Code
• ~/.agents/skills/ para Codex ou agentes semelhantes

Coloque ou confirme o diretório writing-skills na raiz de skills relevante, para que seu agente possa carregar SKILL.md e arquivos relacionados quando necessário.

Arquivos e pastas principais em writing-skills

Depois de instalar, abra primeiro estes arquivos para entender e aplicar o fluxo de trabalho:

• SKILL.md – Definição central da skill e visão geral de writing-skills, incluindo o mapeamento de TDD para skills.
• anthropic-best-practices.md – Orientações no estilo oficial sobre como escrever skills concisas, descobríveis e eficazes para Claude.
• testing-skills-with-subagents.md – Guia prático para construir e executar cenários de pressão e campanhas de teste.
• persuasion-principles.md – Padrões de persuasão baseados em evidências para melhorar a conformidade do agente com suas skills.
• graphviz-conventions.dot – Convenções para representar fluxos de skills e processos como diagramas Graphviz.
• render-graphs.js – Script auxiliar que extrai blocos ```dot de SKILL.md e os renderiza como diagramas SVG.
• examples/CLAUDE_MD_TESTING.md – Exemplo completo de uma campanha de teste para variantes de documentação CLAUDE.md.

Esses arquivos se combinam para oferecer um fluxo completo de criação + teste + visualização de skills.

Fluxo central: TDD para skills

A writing-skills aplica conceitos de TDD diretamente à criação de skills. O ciclo em alto nível é:

1. Escreva casos de teste (cenários de pressão)

   • Desenhe situações realistas em que um agente possa racionalizar pular ou distorcer o processo que você pretende.
   • Use subagentes para rodar esses cenários e capturar o comportamento.

2. Rode testes de base e observe as falhas

   • Execute os cenários sem carregar sua skill nova ou atualizada.
   • Capture onde o agente falha: o que ele pula, racionaliza ou entende errado.

3. Escreva ou refine a skill

   • Rascunhe ou atualize SKILL.md e quaisquer arquivos de apoio para tratar as falhas específicas que você observou.
   • Use linguagem concisa e imperativa que caiba nas limitações da janela de contexto.

4. Rode os testes novamente com a skill carregada

   • Execute de novo os mesmos cenários, agora com sua skill ativa.
   • Verifique se o agente passa a descobrir, anunciar e seguir a skill.

5. Refatore para fechar brechas

   • Identifique racionalizações restantes ou conformidade parcial.
   • Aplique princípios de persuasão (autoridade, comprometimento etc.) para fortalecer a adesão.
   • Corte tokens desnecessários para manter a skill concisa.

Esse ciclo espelha o RED → GREEN → REFACTOR do TDD clássico, mas aplicado à documentação e à aplicação de processos em vez de código.

Usando anthropic-best-practices.md para melhorar suas skills

O arquivo anthropic-best-practices.md traz orientações específicas para o ecossistema Claude, incluindo:

• Por que skills concisas melhoram o uso de contexto e o desempenho do modelo
• Como e quando o Claude carrega SKILL.md e outros arquivos na janela de contexto
• Como escrever seções de skill que justifiquem o custo de seus tokens

Você pode usar esse arquivo como checklist ao revisar suas próprias skills:

• Remova explicações que o Claude já conhece
• Foque em padrões, regras e fluxos de trabalho acionáveis
• Estruture as skills para que as instruções mais importantes apareçam cedo e de forma clara

Integrar essas práticas ao ciclo de TDD da writing-skills ajuda a garantir que suas skills sejam ao mesmo tempo descobríveis e eficientes.

Testando skills com subagentes

O arquivo testing-skills-with-subagents.md amplia a abordagem de TDD com um método concreto de teste:

• Desenhe cenários que imitem a pressão real de produção (tempo, custo afundado, velocidade vs. qualidade).
• Rode-os com subagentes que representem como seu agente principal se comportaria.
• Capture falhas e racionalizações em formatos estruturados.

Isso é especialmente útil para skills que:

• Impõem boas práticas demoradas (por exemplo, escrever testes antes)
• Competem com objetivos de curto prazo (por exemplo, entregar mais rápido vs. verificar a fundo)
• Precisam se manter firmes quando humanos pedem explicitamente atalhos

Seguindo os padrões de teste desse arquivo, você consegue validar suas skills sob pressão antes que cheguem aos usuários finais.

Aplicando princípios de persuasão no design da skill

O arquivo persuasion-principles.md resume princípios psicológicos que também afetam o comportamento de LLMs, como:

• Autoridade – Linguagem clara e não negociável para regras críticas de segurança
• Comprometimento – Exigir que os agentes anunciem quando estão usando uma skill e mantenham o caminho escolhido
• Escassez e outros – Usados com cuidado para priorizar práticas críticas

Na prática, você pode:

• Usar formulções mais imperativas para etapas obrigatórias
• Pedir que o agente declare explicitamente: "I am using [Skill Name] now" quando uma skill estiver em uso
• Projetar checklists que obriguem à conclusão das etapas, não apenas à leitura passiva

O objetivo não é manipular; é garantir que práticas críticas sejam seguidas de forma consistente.

Visualizando fluxos de skills com Graphviz

Skills complexas geralmente se beneficiam de uma representação visual. A writing-skills inclui:

• graphviz-conventions.dot – Estrutura e estilo sugeridos para diagramas
• render-graphs.js – Script Node.js que extrai blocos ```dot de SKILL.md e os transforma em arquivos SVG.

Uso básico do renderer:

./render-graphs.js path/to/your/skill
# ou
./render-graphs.js path/to/your/skill --combine

Isso ajuda você a:

• Comunicar o fluxo de uma skill para colaboradores humanos
• Identificar lacunas ou loops no desenho do processo
• Manter documentação e visuais em sincronia, incorporando diagramas como blocos de código ```dot em SKILL.md.

Adaptando writing-skills ao seu ambiente

O repositório descreve padrões que você deve adaptar, não copiar ao pé da letra. Ao integrar writing-skills ao seu próprio fluxo de trabalho:

• Preserve o ciclo de TDD, mas ajuste os formatos de cenário às suas ferramentas
• Use sua própria estrutura de diretórios, se necessário, mantendo limites claros entre skills
• Integre campanhas de teste aos seus processos atuais de CI, revisão ou release

A meta é um fluxo de criação orientada a testes, repetível, que se encaixe na sua equipe e infraestrutura.

FAQ

Quando devo carregar a skill writing-skills?

Use writing-skills sempre que estiver:

• Criando uma nova skill que vai viver em ~/.claude/skills ou diretórios semelhantes
• Editando uma skill existente que começou a se desviar ou ser ignorada
• Preparando uma skill para implantação para colegas ou uso em produção
• Desenhando ou executando uma campanha de teste de skills com subagentes

Se você estiver apenas explorando em uma sessão efêmera única, talvez não precise do fluxo completo da writing-skills.

Preciso entender TDD antes de usar writing-skills?

Sim. A skill exige familiaridade com superpowers:test-driven-development. A writing-skills parte do princípio de que você já conhece o ciclo RED → GREEN → REFACTOR e então o aplica à documentação:

• RED: Rode cenários sem a skill, capture as falhas
• GREEN: Adicione ou refine a skill para fazer esses cenários passarem
• REFACTOR: Melhore a clareza, feche brechas e reduza o custo de tokens

Se TDD é novo para você, carregue e estude primeiro a skill relacionada a TDD.

Como a writing-skills ajuda com o comportamento específico do Claude?

A writing-skills foi projetada para ambientes como o Claude, e o repositório inclui anthropic-best-practices.md com orientações alinhadas à documentação da Anthropic. Juntos, eles ajudam você a:

• Escrever skills que o Claude consegue descobrir de forma confiável
• Respeitar a janela de contexto e o orçamento de tokens
• Estruturar arquivos SKILL para que o Claude os carregue e use de forma eficaz

Isso torna a writing-skills especialmente útil se você estiver construindo uma biblioteca de skills para Claude.

Posso usar writing-skills para skills não técnicas ou sem código?

Sim, desde que a skill descreva um processo repetível que possa ser testado por meio de cenários. Exemplos incluem:

• Checklists de resposta a incidentes
• Fluxos de trabalho de code review
• Processos de revisão ou aprovação de documentação

O ponto-chave é que o processo tenha:

• Regras claras que os agentes possam seguir ou violar
• Consequências reais quando etapas são puladas
• Cenários em que você consiga testar a conformidade de forma significativa

Conteúdo puramente descritivo ou narrativo não é um bom encaixe.

Para que serve o arquivo examples/CLAUDE_MD_TESTING.md?

O arquivo examples/CLAUDE_MD_TESTING.md é um exemplo completo que mostra como:

• Desenhar cenários realistas (pressão de tempo, custo afundado, autoridade vs. velocidade)
• Rodá-los contra diferentes variantes de documentação CLAUDE.md
• Comparar o quão bem cada variante leva à descoberta e ao uso da skill

Use-o como modelo ao desenhar suas próprias campanhas de teste de skills.

Em que uma skill é diferente de uma história ou estudo de caso?

No modelo da writing-skills:

• Uma skill é um guia de referência reutilizável que codifica padrões, ferramentas ou fluxos de trabalho comprovados.
• Uma história ou estudo de caso descreve como você resolveu um problema específico uma única vez.

A writing-skills ajuda você a sair de histórias pontuais para skills generalizadas e testáveis que futuros agentes podem encontrar e aplicar em novas situações.

E se minha skill for longa — isso importa?

O tamanho importa por causa da janela de contexto. O arquivo anthropic-best-practices.md explica por que skills concisas têm desempenho melhor:

• Apenas os metadados são carregados inicialmente, mas depois que SKILL.md é lido, cada token passa a competir com o histórico da conversa.
• Você deve se perguntar constantemente se cada seção merece estar ali.

A writing-skills incentiva você a:

• Cortar explicações redundantes
• Mover exemplos para arquivos de apoio, se necessário
• Focar SKILL.md no processo central e nas regras que fazem os testes passarem

Como sei que writing-skills está funcionando?

Você verá impacto quando:

• Skills que antes eram ignoradas sob pressão passam a ser seguidas
• Novas skills já chegam com cenários e testes explícitos, não apenas texto
• Você consegue apontar comportamentos antes/depois de agentes em cenários específicos

Se você não consegue mostrar diferença entre o comportamento com e sem uma skill, volte ao ciclo de TDD e aos guias de persuasão e teste fornecidos pela writing-skills.