writing-for-agents (mattpocock/skills)

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). As mesmas três tarefas de writing-skills: escrever uma skill de mensagem de commit a partir de quatro regras, enxugar um AGENTS.md inchado sem perder o essencial (5 regras reais enterradas entre enchimento, duplicatas e um ponteiro obsoleto), e escrever uma skill de triagem de bugs. O controle recebe apenas a tarefa. O prompt de uma frase dá as principais regras da skill em uma frase. Os arquivos SKILL.md gerados são pontuados com a mesma checklist de 7 pontos de writing-skills, que espera uma descrição no estilo 'Use when ...'; o conselho da própria skill é 'trigger first', não essa redação literal.

Comparação entre os braços

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

Veredito: Situacional (24.9 / 30). Fonte: mattpocock/skills, skills/productivity/writing-for-agents, fixado no commit 4ae2317. Instalação: npx skills@latest add mattpocock/skills --skill writing-for-agents. Licença: MIT (LICENSE do repositório).

O que é

A skill writing-for-agents (mattpocock/skills): orientação para escrever instruções que agentes leem: colocar o gatilho primeiro em uma descrição com um gatilho por ramo distinto, manter cada significado em uma única fonte de verdade, apagar instruções sem efeito que o modelo já segue e linhas que repetem o ambiente (scripts, config), terminar cada etapa em um critério de conclusão verificável e manter os arquivos curtos.

Como testamos

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

As mesmas três tarefas de writing-skills: escrever uma skill de mensagem de commit a partir de quatro regras, enxugar um AGENTS.md inchado sem perder o essencial (5 regras reais enterradas entre enchimento, duplicatas e um ponteiro desatualizado) e escrever uma skill de triagem de bugs. O controle recebe apenas a tarefa. O prompt de uma frase traz as principais regras da skill em uma frase. Os SKILL.md gerados são pontuados com a mesma checklist de 7 pontos de writing-skills, que espera uma descrição no estilo 'Use when ...'; o conselho da própria skill é 'gatilho primeiro', não essa redação literal.

1. 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, sem ponto final; depois uma linha em branco e um corpo quebrado em 72 caracteres…
2. Enxugar um AGENTS.md — O AGENTS.md cresceu a ponto de ninguém ler. Reescreva-o no lugar para que fique o mais curto possível sem perder nada de que um agente realmente precise.
3. 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 relatórios 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 os passos de reprodução ausentes de fo…

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

Resultados

A frase única dada ao terceiro grupo: "Escreva para agentes: coloque o gatilho primeiro na descrição, com um gatilho por ramo distinto, mantenha cada significado em uma única fonte de verdade, apague instruções sem efeito que o modelo já segue e linhas que apenas repetem o ambiente (scripts, config), termine cada etapa em um critério de conclusão verificável e mantenha o arquivo curto."

Pontuação média: 4.17 sem a skill vs 4.52 com a skill (delta +0.35). Tokens por execução: 70k vs 88k (1.27x); tempo 39s vs 37s. Grupo prompt de uma frase: 4.63 (ganho da skill sobre o prompt de uma frase: -0.11; ganho do próprio prompt de uma frase sobre nenhuma skill: +0.46); tokens do prompt de uma frase: 76k por execução, então a skill custa 1.17x o prompt de uma frase.

O que aconteceu

• Médias: skill 4.52, prompt de uma frase 4.63, controle 4.17 (n=6 cada). O ganho claro é a tarefa do AGENTS.md: skill 5.00 nas duas execuções (todas as 5 regras essenciais mantidas, enchimento removido, ponteiro desatualizado corrigido, duplicatas consolidadas), contra 4.29 do controle e 4.71 do prompt de uma frase. As duas execuções do prompt de uma frase apagaram a regra "migrações são somente append" ao enxugar; as execuções com a skill a mantiveram.
• Nas duas tarefas de escrita de skill, a skill não sai melhor que o controle (4.18-4.59 vs 4.06-4.18): nas 4 execuções com a skill nessas tarefas, a descrição era um resumo do fluxo ou não dizia quando usar a skill ("Triagem de relatórios de bug recebidos solicitando passos de reprodução ausentes e classificando a severidade...", idêntica ao controle), então a checklist de 7 pontos deu 5/7 ou 6/7, como no controle. As execuções do prompt de uma frase escreveram descrições no estilo gatilho ("Quando um relatório de bug recebido não tiver passos de reprodução, peça-os primeiro...").
• O controle omitiu a regra "corpo quebrado em 72, explique por quê" nas duas execuções da skill de commit (3/4 regras); a skill e o prompt de uma frase mantiveram as quatro.
• Custo: 88k tokens por execução com a skill, contra 70k do controle e 76k do prompt de uma frase (1.26x, 1.16x). As execuções com a skill copiam 4 arquivos por execução para o projeto.
• Uma verificação que conta scripts de package.json repetidos no AGENTS.md falha apenas nas 2 execuções de controle aqui (3 correspondências), consistente com a regra da skill de "não repetir o ambiente".

Pontuações por dimensão

Limites deste teste

• Verificações baseadas em regras, em parte emprestadas do teste writing-skills: a checklist de 7 pontos da skill recompensa a redação "Use when" que esta skill não exige, o que a subestima nas duas tarefas de escrita de skill.
• Ninguém testou se as skills escritas ou o AGENTS.md enxugado realmente mudam o comportamento de um agente.
• n=2 por célula.
• n = 2 por grupo por tarefa: diferenças abaixo de ~1 ponto são ruído.
• A pontuação baseada em regras mede o que as verificações conseguem ver; ela não julga bom gosto nem se o resultado é o melhor possível.

Segurança

Consulte security.md. Varredura: 0 CRITICAL / 0 HIGH / 0 MEDIUM. Veredito: seguro para executar (sandbox sem rede). Uma varredura limpa não prova que uma skill é segura.

Conclusão

Vale a pena para compactar um arquivo de instruções (manteve todas as regras reais que um prompt de uma frase deixou cair); fora isso, não é melhor que o modelo base para escrever novas skills, com 1.26x tokens.