writing-skills (obra/superpowers)

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

Crée et modifie des skills d'agent et vérifie leur bon fonctionnement avant déploiement.

writing-skills : fait réussir la règle de description (« Use when... » 4.9 contre 4.4 sans le skill), mais une règle en une phrase obtient 4.7 pour un tiers des tokens (le skill en consomme 2.5 fois plus)

Selon les casSûr

Codex CLI · gpt-6-astra

17.6 / 30

Gain par rapport à sans skill : +0.45 · Selon les cas · 18 exécutions

Selon les cas : le total 17.6/30 est inférieur à 22 et le gain +0.45 est inférieur à +1.0. Pour être recommandé, il faut un total de 22/30, une qualité de sortie de 3.5 et un gain de +1.0.

SOTA

Réussi

Testé avec Codex.

Couvre Codex, Claude Code

Codex CLI 0.166 (palier SOTA) : 18 exécutions notées. Une réussite ici couvre aussi Claude Code selon notre règle de palier ; elle ne dit rien du second palier.

Scores

Chaque dimension va de 0 à 5 et les six forment le total sur 30. 5 est la meilleure note dans chaque dimension. Coût 5 signifie bon marché et rapide. Installation 5 signifie facile.

Fiabilité du déclenchement: 3.3
Gain par rapport à sans skill: 2.5
Qualité de sortie: 4.9
Coût en tokens et en temps: 1.0
Installation et portabilité: 3.0
Sécurité: 3.0

Revue de sécurité

Sûr

Scan statique : 0 CRITIQUE / 1 ÉLEVÉ / 1 MOYEN. Revue manuelle : sûr à exécuter dans un bac à sable sans réseau (alertes du scanner expliquées). Un scan propre ne prouve pas qu'un skill est sûr.

Installer

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

Source

Commit épinglé: 2ce8aa15d05bd57213e6f746f953aafb7ded7a8b

Testé: 2026-11-02

Ce que nous avons testé

Écrire un skill de message de commit — Écrivez un skill (un SKILL.md) dans skills/commit-writer/SKILL.md qui fasse écrire à nos agents de code des messages de commit suivant ces règles : le sujet est à l'impératif, fait moins de 50 caractères, sans point final ; puis une ligne vide et un corps coupé à 72 caractères…
Resserrer un AGENTS.md — AGENTS.md a grossi au point que personne ne le lit. Réécrivez-le sur place pour qu'il soit aussi court que possible sans rien perdre de ce dont un agent a réellement besoin.
Écrire un skill de triage de bugs — Écrivez un skill (un SKILL.md) dans skills/bug-triage/SKILL.md qui fasse classer par les agents les rapports de bug entrants en S1 (perte de données ou panne), S2 (une fonctionnalité majeure est cassée mais un contournement existe) ou S3 (mineur ou cosmétique), et demande d'abord les étapes de reproduction manquantes…

Points forts

Qualité absolue élevée avec le skill : 4.88 sur 5.

Points faibles

Consomme 2.56 fois plus de tokens que sans skill.
n=2 par tâche et par bras ; les écarts inférieurs à environ 1 point sont du bruit.

Avis

Codex CLI 0.166 (gpt-6-astra, low reasoning) sur un PC Windows de test dédié, un projet temporaire neuf et des HOME/TMPDIR/caches temporaires à chaque exécution, skill installé (traitement) ou absent (contrôle) ou absent avec l'exigence centrale du skill compressée en une phrase ajoutée au prompt (groupe « prompt d'une phrase »), 2 exécutions par groupe et par tâche, réseau coupé, écritures dans /tmp bloquées. Les prompts ne mentionnent jamais le skill (sauf la formulation indiquée ci-dessous). Trois tâches : écrire un skill de message de commit à partir de quatre règles, resserrer un AGENTS.md boursouflé sans perdre l'essentiel, et écrire un skill de triage de bugs (S1/S2/S3 plus « demander d'abord les étapes de reproduction manquantes »). Le contrôle ne reçoit que la tâche. Le groupe « une phrase » ajoute une phrase énonçant la règle de description, un SKILL.md court et un exemple concret.

Comparaison à trois bras

Bras	Score moyen (0-5)	Tokens par exécution
Sans le skill	4.43	64k
Prompt d'une phrase	4.71	66k
Avec le skill	4.88	163k

Mesuré avec Codex CLI sur 18 exécutions, noté par des contrôles basés sur des règles, sans juge LLM. Total 17.6 / 30, verdict Selon les cas.

Verdict : Selon le cas (17.6 / 30). Source : obra/superpowers, skills/writing-skills, épinglé au commit 2ce8aa1. Installation : npx skills@latest add obra/superpowers --skill writing-skills. Licence : MIT (LICENSE du dépôt).

Présentation

Le skill writing-skills (obra/superpowers) : un guide pour rédiger des skills d’agents, construit autour de l’écriture pilotée par les tests (établir la base d’échec, écrire le skill minimal, fermer les failles). Il fixe des règles pour la description du frontmatter (conditions de déclenchement uniquement, commençant par « Use when », sans jamais résumer le workflow), la structure des fichiers, l’efficacité en tokens et les renvois croisés. Fournit un helper render-graphs.js et de longs fichiers de référence.

Méthode de test

Codex CLI 0.166 (gpt-6-astra, raisonnement faible) sur une machine de test Windows dédiée, un projet temporaire neuf et des HOME/TMPDIR/caches temporaires à chaque exécution, skill installé (groupe avec skill), absent (groupe témoin), ou absent avec l’exigence centrale du skill compressée en une phrase ajoutée au prompt (groupe « prompt en une phrase »), 2 exécutions par groupe et par tâche, réseau désactivé, écritures dans /tmp bloquées. Les prompts ne mentionnent jamais le skill (sauf la formulation indiquée plus bas).

Trois tâches : écrire un skill de messages de commit à partir de quatre règles, resserrer un AGENTS.md gonflé sans perdre l’essentiel, et écrire un skill de tri de bugs (S1/S2/S3 plus « demander d’abord les étapes de reproduction manquantes »). Le témoin ne reçoit que la tâche. Le prompt ajoute une phrase énonçant la règle de description, un SKILL.md court et un exemple concret.

Écrire un skill de messages de commit — Écris un skill (un SKILL.md) dans skills/commit-writer/SKILL.md qui amène nos agents de code à rédiger des messages de commit selon ces règles : le sujet est à l’impératif, fait moins de 50 caractères, sans point final ; puis une ligne vide et un corps coupé à 72 caractères…
Resserrer un AGENTS.md — AGENTS.md a tellement grossi que personne ne le lit. Réécris-le sur place pour qu’il soit aussi court que possible sans rien perdre de ce dont un agent a réellement besoin.
Écrire un skill de tri de bugs — Écris un skill (un SKILL.md) dans skills/bug-triage/SKILL.md qui demande aux agents de classer les rapports de bug entrants en S1 (perte de données ou panne), S2 (une fonctionnalité majeure est cassée mais un contournement existe) ou S3 (mineur ou cosmétique), et de demander d’abord les étapes de reproduction manquantes fi…

Le scoring est programmatique (tests cachés / détection des problèmes implantés / vérifications de contraintes / rendu + OCR le cas échéant), de 0 à 5 par exécution. Aucun juge LLM n’a attribué de score.

Résultats

Le prompt en une phrase donné au troisième groupe : « La description d’un skill dit seulement quand l’utiliser (conditions de déclenchement, commençant par « Use when », moins d’environ 400 caractères, sans jamais résumer le workflow) ; garde SKILL.md court et à l’impératif, déplace les références volumineuses ailleurs, et inclure un exemple concret plutôt qu’un récit. »

Tâche	Score témoin	Prompt en une phrase	Avec skill	Tokens témoin	Tokens du prompt en une phrase	Tokens avec skill	Skill lu
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

Score moyen : 4.43 sans le skill contre 4.88 avec (écart +0.45). Tokens par exécution : 64k contre 163k (2.56x) ; temps 34s contre 52s. Groupe « prompt en une phrase » : 4.71 (gain du skill sur ce prompt : +0.17 ; gain du prompt par rapport à l’absence de skill : +0.29) ; tokens du prompt : 66k par exécution, donc le skill coûte 2.45x le prompt en une phrase.

Ce qui s’est passé

Skill 4.88, prompt 4.71, témoin 4.43 (n=6 chacun). Le gain vient de la description : les descriptions du témoin résument le workflow (« Tri les rapports de bug entrants en demandant les étapes de reproduction manquantes et en classant la sévérité en S1, S2 ou S3 »), ce qui est l’anti-pattern que le skill dénonce, et les deux skills de tri de bugs du témoin ont obtenu 5/7 à la vérification de qualité (formulation « quand l’utiliser » et exemple concret). Les groupes skill et prompt ont écrit des descriptions « Use when ... » et obtenu 7/7 dans leurs 4 exécutions de tri et de messages de commit.
Coût : 163k tokens par exécution pour le skill contre 64k pour le témoin et 66k pour le prompt (2.5x). Sur la tâche du skill de commit, les deux exécutions avec skill ont dépensé 243-255k tokens (et jusqu’à 229k sur le tri) à lire les longs fichiers de référence ; sur la tâche de resserrement d’AGENTS.md, qui n’a rien à voir avec les skills, il a utilisé 68-85k.
Sur le skill de messages de commit, le témoin a omis la règle « expliquer pourquoi, coupé à 72 » dans les deux exécutions (3/4 règles) alors que les exécutions du skill et du prompt ont gardé les quatre.
Le resserrement d’AGENTS.md (tâche 2) donne le même 4.64 dans tous les groupes, avec une exécution du prompt à 3.64 (elle a supprimé la règle « les migrations sont en ajout seul » et gardé le pointeur obsolète vers la doc) : le skill n’a pas rendu le fichier resserré meilleur ici. Une vérification qui compte les commandes package.json répétées dans AGENTS.md échoue dans les 18 exécutions, c’est donc une vérification défectueuse qui a été ignorée.
Son helper (render-graphs.js, exécute dot via execFileSync) n’a pas été lancé.

Scores par dimension

Dimension	Score	Pourquoi
1_output_quality	4.88	Score moyen de 4.88/5 avec le skill (vérifications programmatiques, voir le tableau par tâche).
2_lift_vs_no_skill	2.45	+0.45 point par rapport à 4.43 sans le skill (n=2 par tâche ; un écart inférieur à ~1 point relève du bruit).
3_trigger	3.3	Fichier du skill lu dans 4/6 exécutions avec skill.
4_instructions_portability	3	Long SKILL.md plus plusieurs gros fichiers de référence et un helper Node/graphviz ; lourd pour son objectif.
5_efficiency	1	2.56x tokens (163k contre 64k par exécution) et 1.52x temps (52s contre 34s).
6_safety_hygiene	3	Scanner quasi propre ; le helper invoque `dot` ; mentionne des chemins ~/.claude/skills dans les exemples (voir security.md).

Limites de ce test

Vérifications par règles sur les fichiers SKILL.md générés (frontmatter, formulation de la description, longueur) et détection des règles ; aucun test de si les skills écrits changent réellement le comportement d’un agent, ce que la méthode du skill exige.
Une vérification (commandes package.json dans AGENTS.md) est défectueuse et échoue partout.
n=2 par cellule.
n = 2 par groupe et par tâche : un écart inférieur à ~1 point relève du bruit.
Le scoring par règles mesure ce que les vérifications peuvent voir ; il ne peut juger du goût ni du caractère optimal d’un résultat.

Sécurité

Voir security.md. Scan : 0 CRITICAL / 1 HIGH / 1 MEDIUM. Verdict : exécution sans danger (sandbox sans réseau). Un scan propre ne prouve pas qu’un skill est sûr.

En résumé

Il enseigne bien la règle la plus importante pour le déclenchement (des descriptions qui disent quand utiliser, pas ce que fait le skill) et produit des fichiers de skill plus propres, mais à 2.5x les tokens, et une seule phrase en transmet presque tout. Lisez le guide ; ne le chargez pas pour chaque petite modification de skill.

Transcription

Journal d'exécution : writing-skills (Codex CLI, network off, per-run temp HOME/TMPDIR, one row per graded run.)
Colonnes : tâche, groupe-exécution, score (0-5), tokens, secondes, vérifications réussies, fichiers de la skill ouverts par l'agent.

t1-commit-skill control-1: score 4.46, tokens 75571, s 36.1, vérifications 1/2, rien ouvert
t1-commit-skill control-2: score 4.46, tokens 75427, s 37.8, vérifications 1/2, rien ouvert
t1-commit-skill oneliner-1: score 5.0, tokens 75487, s 32.0, vérifications 2/2, rien ouvert
t1-commit-skill oneliner-2: score 5.0, tokens 55779, s 28.0, vérifications 2/2, rien ouvert
t1-commit-skill treatment-1: score 5.0, tokens 255351, s 72.7, vérifications 2/2, ouvert writing-skills
t1-commit-skill treatment-2: score 5.0, tokens 243348, s 61.0, vérifications 2/2, ouvert writing-skills
t2-trim-agents control-1: score 4.64, tokens 50635, s 30.0, vérifications 6/7, rien ouvert
t2-trim-agents control-2: score 4.64, tokens 68044, s 37.7, vérifications 6/7, rien ouvert
t2-trim-agents oneliner-1: score 3.64, tokens 68983, s 35.6, vérifications 4/7, rien ouvert

18 exécutions, 3 artefacts

Exemple de sortie

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 ```

Voir Pro