writing-skills (obra/superpowers)

Name: writing-skills (obra/superpowers) review
Item: writing-skills (obra/superpowers)
Rating: 17.6
Author: Agent Skills

Cria e edita skills de agente e verifica se funcionam antes de publicá-las.

writing-skills: acerta a regra de descrição ('Use when...' 4.9 vs 4.4 sem a skill), mas uma regra de uma frase marca 4.7 com um terço dos tokens (2.5x)

SituacionalSeguro

Codex CLI · gpt-6-astra

17.6 / 30

Ganho sobre sem skill: +0.45 · Situacional · 18 execuções

Situacional: o total 17.6/30 está abaixo de 22 e o ganho +0.45 está abaixo de +1.0. Para ser recomendado, é preciso total de 22/30, qualidade da saída de 3.5 e ganho de +1.0.

SOTA

Aprovado

Testado com Codex.

Cobre Codex, Claude Code

Codex CLI 0.166 (nível SOTA): 18 execuções avaliadas. Uma aprovação aqui também vale para o Claude Code pela nossa regra de níveis; ela não diz nada sobre o segundo nível.

Notas

Cada dimensão vai de 0 a 5, e as seis somam o total de 30. 5 é melhor em todas as dimensões. Custo 5 significa barato e rápido. Instalação 5 significa fácil.

Confiabilidade do acionamento: 3.3
Ganho sobre sem skill: 2.5
Qualidade da saída: 4.9
Custo de tokens e tempo: 1.0
Instalação e portabilidade: 3.0
Segurança: 3.0

Revisão de segurança

Seguro

Varredura estática: 0 CRÍTICO / 1 ALTO / 1 MÉDIO. Revisão manual: seguro para executar em sandbox sem rede (achados do scanner explicados). Uma varredura limpa não prova que a skill é segura.

Instalar

npx skills@latest add obra/superpowers --skill writing-skills

Fonte

Commit fixado: 2ce8aa15d05bd57213e6f746f953aafb7ded7a8b

Testado: 2026-11-02

O que testamos

Escrever uma skill de mensagem de commit — Escreva uma skill (um SKILL.md) em skills/commit-writer/SKILL.md que faça nossos agentes de código escreverem mensagens de commit seguindo estas regras: o assunto no imperativo, com menos de 50 caracteres e sem ponto final; depois uma linha em branco e um corpo quebrado em 72 caracteres…
Enxugar um AGENTS.md — O AGENTS.md cresceu a ponto de ninguém mais ler. Reescreva-o no próprio arquivo para ficar o mais curto possível sem perder nada de que um agente realmente precise.
Escrever uma skill de triagem de bugs — Escreva uma skill (um SKILL.md) em skills/bug-triage/SKILL.md que faça os agentes classificarem relatos de bug recebidos como S1 (perda de dados ou indisponibilidade), S2 (um recurso importante quebrado, mas com contorno) ou S3 (menor ou cosmético), e pedir primeiro os passos de reprodução que faltam…

Prós

Qualidade absoluta alta com a skill: 4.88 de 5.

Contras

Usa 2.56x os tokens do grupo sem skill.
n=2 por tarefa por braço; diferenças abaixo de cerca de 1 ponto são ruído.

Avaliação

Codex CLI 0.166 (gpt-6-astra, raciocínio baixo) em um PC de teste Windows dedicado, com um projeto temporário novo e HOME/TMPDIR/caches temporários a cada execução, skill instalada (tratamento) ou ausente (grupo de controle) ou ausente com o requisito central da skill comprimido em uma frase anexada ao prompt (grupo prompt de uma frase), 2 execuções por grupo por tarefa, rede desligada, gravações em /tmp bloqueadas. Os prompts nunca mencionam a skill (exceto pelo texto indicado abaixo). Três tarefas: escrever uma skill de mensagem de commit a partir de quatro regras, enxugar um AGENTS.md inchado sem perder o essencial, e escrever uma skill de triagem de bugs (S1/S2/S3 mais 'pedir primeiro os passos de reprodução que faltam'). O controle recebe apenas a tarefa. O prompt de uma frase adiciona uma frase enunciando a regra de descrição, SKILL.md curto e um exemplo concreto.

Comparação entre os braços

Braço	Nota média (0-5)	Tokens por execução
Sem a skill	4.43	64k
Prompt de uma frase	4.71	66k
Com a skill	4.88	163k

Medido com Codex CLI em 18 execuções, com pontuação por verificações baseadas em regras e sem juiz LLM. Total 17.6 / 30, veredito Situacional.

Veredicto: Situacional (17.6 / 30). Fonte: obra/superpowers, skills/writing-skills, fixado no commit 2ce8aa1. Instalação: npx skills@latest add obra/superpowers --skill writing-skills. Licença: MIT (LICENSE do repositório).

O que é

A skill writing-skills (obra/superpowers): um guia para escrever skills de agente, estruturado em torno de escrita orientada a testes (criar a linha de base da falha, escrever a skill mínima, fechar brechas). Define regras para a descrição no frontmatter (apenas condições de acionamento, começando com "Use when", nunca resumindo o fluxo de trabalho), estrutura de arquivos, eficiência de tokens e referências cruzadas. Inclui um auxiliar render-graphs.js e arquivos de referência longos.

Como testamos

Codex CLI 0.166 (gpt-6-astra, raciocínio baixo) em um PC de teste Windows dedicado, com um projeto temporário novo e HOME/TMPDIR/caches temporários a cada execução, skill instalada (tratamento), ausente (controle) ou ausente com o requisito central da skill comprimido em uma frase anexada ao prompt (grupo de uma frase), 2 execuções por grupo por tarefa, rede desligada, gravações em /tmp bloqueadas. Os prompts nunca mencionam a skill (exceto pelo texto indicado abaixo).

Três tarefas: escrever uma skill de mensagem de commit a partir de quatro regras, enxugar um AGENTS.md inchado sem perder o essencial e escrever uma skill de triagem de bugs (S1/S2/S3 mais "peça primeiro os passos de reprodução que faltam"). O controle recebe apenas a tarefa. A frase única acrescenta uma frase declarando a regra de descrição, SKILL.md curto e um exemplo concreto.

Escrever uma skill de mensagem de commit — Escreva uma skill (um SKILL.md) em skills/commit-writer/SKILL.md que faça nossos agentes de código escreverem mensagens de commit seguindo estas regras: o assunto é imperativo, com menos de 50 caracteres e sem ponto final; depois uma linha em branco e um corpo quebrado em 72 caracteres…
Enxugar um AGENTS.md — O AGENTS.md cresceu a ponto de ninguém lê-lo. Reescreva-o no próprio local para que fique o mais curto possível sem perder nada de que um agente realmente precise.
Escrever uma skill de triagem de bugs — Escreva uma skill (um SKILL.md) em skills/bug-triage/SKILL.md que faça os agentes classificarem relatos de bugs recebidos como S1 (perda de dados ou indisponibilidade), S2 (um recurso importante quebrado, mas com contorno) ou S3 (menor ou cosmético), e peça primeiro os passos de reprodução que faltam…

A pontuação é programática (testes ocultos / identificação de problemas plantados / verificações de restrições / renderização + OCR quando aplicável), de 0 a 5 por execução. Nenhum juiz LLM decidiu qualquer pontuação.

Resultados

A frase única dada ao terceiro grupo: "A descrição de uma skill diz apenas quando usá-la (condições de acionamento, começando com 'Use when', com menos de cerca de 400 caracteres, nunca resumindo o fluxo de trabalho); mantenha o SKILL.md curto e imperativo, mova o material de referência volumoso para fora e inclua um exemplo concreto em vez de narrativa."

Tarefa	Pontuação do controle	Uma frase	Com a skill	Tokens do controle	Tokens de uma frase	Tokens com a skill	Skill lida
t1-commit-skill	4.46	5.0	5.0	75k	65k	249k	2/2
t2-trim-agents	4.64	4.14	4.64	59k	77k	76k	0/2
t3-triage-skill	4.18	5.0	5.0	55k	55k	161k	2/2

Pontuação média: 4.43 sem a skill vs. 4.88 com a skill (delta +0.45). Tokens por execução: 64k vs. 163k (2.56x); tempo 34s vs. 52s. Grupo de uma frase: 4.71 (ganho da skill sobre a frase única: +0.17; ganho da própria frase única sobre sem skill: +0.29); 66k tokens por execução no grupo de uma frase, então a skill custa 2.45x a frase única.

O que aconteceu

Skill 4.88, frase única 4.71, controle 4.43 (n=6 cada). O ganho está na descrição: as descrições do controle resumem o fluxo de trabalho ("Faça a triagem dos relatos de bugs recebidos pedindo os passos de reprodução que faltam e classificando a gravidade como S1, S2 ou S3"), que é o antipadrão contra o qual a skill alerta, e as duas skills de triagem do controle marcaram 5/7 na verificação de qualidade (redação de "quando usar" e um exemplo concreto). Os grupos da skill e da frase única escreveram descrições "Use when ..." e marcaram 7/7 nas suas 4 execuções de triagem e de mensagem de commit.
Custo: 163k tokens por execução com a skill contra 64k do controle e 66k da frase única (2.5x). Na tarefa da skill de commit, as duas execuções de tratamento gastaram 243-255k tokens (e até 229k na triagem) lendo os arquivos de referência longos; na tarefa de enxugar o AGENTS.md, que não tem nada a ver com skills, ela usou 68-85k.
Na skill de mensagem de commit, o controle omitiu a regra "explique o porquê, quebrado em 72" nas duas execuções (3/4 regras), enquanto as execuções da skill e da frase única mantiveram as quatro.
Enxugar o AGENTS.md (tarefa 2) dá os mesmos 4.64 em todos os grupos, com uma execução de uma frase em 3.64 (ela derrubou a regra "migrações são somente append" e manteve o ponteiro obsoleto para docs): a skill não tornou o arquivo enxugado melhor aqui. Uma verificação que conta comandos de package.json repetidos no AGENTS.md falha em todas as 18 execuções, então é uma verificação defeituosa e foi ignorada.
O auxiliar dela (render-graphs.js, executa dot via execFileSync) não foi executado.

Pontuação por dimensão

Dimensão	Pontuação	Por quê
1_output_quality	4.88	Pontuação média de 4.88/5 com a skill (verificações programáticas; consulte a tabela por tarefa).
2_lift_vs_no_skill	2.45	+0.45 ponto vs. 4.43 sem a skill (n=2 por tarefa; abaixo de ~1 ponto é ruído).
3_trigger	3.3	Arquivo da skill lido em 4/6 execuções com a skill.
4_instructions_portability	3	SKILL.md longo mais vários arquivos de referência grandes e um auxiliar Node/graphviz; pesado para o propósito.
5_efficiency	1	2.56x tokens (163k vs. 64k por execução) e 1.52x tempo (52s vs. 34s).
6_safety_hygiene	3	Scanner quase limpo; o auxiliar invoca `dot`; menciona caminhos ~/.claude/skills em exemplos (ver security.md).

Limites deste teste

Verificações por regras nos arquivos SKILL.md gerados (frontmatter, redação da descrição, comprimento) e recall das regras; nenhum teste de se as skills escritas realmente mudam o comportamento de um agente, que é o que o próprio método da skill exige.
Uma verificação (comandos de package.json no AGENTS.md) é defeituosa e falha em todos os casos.
n=2 por célula.
n = 2 por grupo por tarefa: diferenças abaixo de cerca de 1 ponto são ruído.
A pontuação por regras mede o que as verificações conseguem ver; não julga bom gosto nem se o resultado é o melhor possível.

Segurança

Consulte security.md. Scan: 0 CRITICAL / 1 HIGH / 1 MEDIUM. Veredicto: segura para execução (sandbox sem rede). Um scan limpo não prova que uma skill é segura.

Conclusão

Ela ensina a única regra que mais importa para o acionamento (descrições que dizem quando usar, não o que a skill faz) e produz arquivos de skill mais organizados, mas custa 2.5x os tokens, e uma única frase captura quase tudo. Leia o guia; não o carregue para cada pequena edição de skill.

Transcrição

Log de execuções: writing-skills (Codex CLI, network off, per-run temp HOME/TMPDIR, one row per graded run.)
Colunas: tarefa, grupo-execução, nota (0-5), tokens, segundos, verificações aprovadas, arquivos da skill abertos pelo agente.

t1-commit-skill control-1: nota 4.46, tokens 75571, s 36.1, verificações 1/2, nada aberto
t1-commit-skill control-2: nota 4.46, tokens 75427, s 37.8, verificações 1/2, nada aberto
t1-commit-skill oneliner-1: nota 5.0, tokens 75487, s 32.0, verificações 2/2, nada aberto
t1-commit-skill oneliner-2: nota 5.0, tokens 55779, s 28.0, verificações 2/2, nada aberto
t1-commit-skill treatment-1: nota 5.0, tokens 255351, s 72.7, verificações 2/2, abriu writing-skills
t1-commit-skill treatment-2: nota 5.0, tokens 243348, s 61.0, verificações 2/2, abriu writing-skills
t2-trim-agents control-1: nota 4.64, tokens 50635, s 30.0, verificações 6/7, nada aberto
t2-trim-agents control-2: nota 4.64, tokens 68044, s 37.7, verificações 6/7, nada aberto
t2-trim-agents oneliner-1: nota 3.64, tokens 68983, s 35.6, verificações 4/7, nada aberto

18 execuções, 3 artefatos

Resultado de exemplo

SOTA · With the skill: skills/commit-writer/SKILL.md (t1-commit-skill, run 1, Codex)

--- name: commit-writer description: Use when drafting, editing, or reviewing Git commit messages. --- # Commit Writer Write commit messages that explain the reason for the change using this structure: 1. An imperative subject (for example, "Reject expired sessions") of fewer than 50 characters, including spaces. Do not add a trailing period. 2. A blank line. 3. A body explaining why the change is needed: the problem, motivation, or intended benefit. Do not merely list code changes. Wrap lines at 72 characters maximum, breaking at word boundaries. 4. A blank line followed by the actual ticket ID on the final line, such as `PROJ-123`. Nothing follows the ticket reference. Use the diff and task context to establish the motivation and ticket ID. If either is unavailable, ask for the missing information; do not invent it or substitute the example ticket ID. Never mention AI tools anywhere in the commit message, including generation credits, attribution trailers, or copied development notes. Before returning the message, check the imperative wording, subject length (49 characters maximum), blank lines, body line lengths, rationale, final ticket reference, and absence of AI tool mentions. Example: ```text Reject expired sessions Expired sessions let users retain access to private pages after their authorization ends. Enforce the session lifetime to protect that data. PROJ-123 ```

Ver o Pro