writing-for-agents (mattpocock/skills)

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). Mêmes trois tâches que pour writing-skills : écrire un skill de message de commit à partir de quatre règles, resserrer un AGENTS.md boursouflé sans perdre l'essentiel (5 vraies règles enfouies parmi du remplissage, des doublons et un pointeur obsolète), et écrire un skill de triage de bugs. Le contrôle ne reçoit que la tâche. Le groupe « une phrase » donne les règles principales du skill en une phrase. Les fichiers SKILL.md générés sont notés avec la même checklist en 7 points que writing-skills, qui attend une description de style « Use when ... » ; le conseil du skill lui-même est « trigger first », pas cette formulation littérale.

Comparaison à trois bras

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

Verdict : Selon les cas (24.9 / 30). Source : mattpocock/skills, skills/productivity/writing-for-agents, épinglé au commit 4ae2317. Installation : npx skills@latest add mattpocock/skills --skill writing-for-agents. Licence : MIT (LICENSE du dépôt).

Ce que c'est

Le skill writing-for-agents (mattpocock/skills) : des conseils pour écrire des instructions que les agents lisent : placer le déclencheur en premier dans une description, avec un déclencheur par branche distincte, garder chaque signification dans une source de vérité unique, supprimer les instructions sans effet que le modèle suit déjà et les lignes qui répètent l'environnement (scripts, configuration), terminer chaque étape par un critère d'achèvement vérifiable, et garder les fichiers courts.

Comment nous avons testé

Codex CLI 0.166 (gpt-6-astra, raisonnement faible) sur un PC de test Windows dédié, un projet temporaire neuf et des caches HOME/TMPDIR temporaires à chaque exécution, skill installé (groupe avec skill) ou absent (groupe témoin) ou absent avec l'exigence centrale du skill compressée en une phrase ajoutée à la fin du 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).

Les mêmes trois tâches que pour writing-skills : écrire un skill de message de commit à partir de quatre règles, resserrer un AGENTS.md gonflé sans perdre l'essentiel (5 vraies règles enfouies parmi du remplissage, des doublons et un pointeur obsolète), et écrire un skill de tri de bugs. Le groupe témoin ne reçoit que la tâche. Le prompt d'une phrase donne les règles principales du skill en une phrase. Les fichiers SKILL.md générés sont notés avec la même liste de contrôle en 7 points que writing-skills, qui attend une description de style « Use when ... » ; le conseil de ce skill est « déclencheur d'abord », pas cette formulation littérale.

1. Écrire un skill de message de commit — Écrivez un skill (un SKILL.md) dans skills/commit-writer/SKILL.md qui amène nos agents de codage à écrire des messages de commit selon ces règles : le sujet est à l'impératif, fait moins de 50 caractères et ne se termine pas par un point ; puis une ligne vide et un corps coupé à 72 caractères…
2. Resserrer un AGENTS.md — AGENTS.md a tellement grossi 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.
3. Écrire un skill de tri de bugs — Écrivez un skill (un SKILL.md) dans skills/bug-triage/SKILL.md qui amène les agents à 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 à demander d'abord les étapes de reproduction manquantes…

La notation est programmatique (tests cachés / détection de 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 décidé d'un seul score.

Résultats

Le prompt d'une phrase donné au troisième groupe : "Écrivez pour les agents : placez le déclencheur en premier dans la description, avec un déclencheur par branche distincte, gardez chaque signification dans une source de vérité unique, supprimez les instructions sans effet que le modèle suit déjà et les lignes qui ne font que répéter l'environnement (scripts, configuration), terminez chaque étape par un critère d'achèvement vérifiable, et gardez le fichier court."

Score moyen : 4.17 sans le skill contre 4.52 avec (delta +0.35). Tokens par exécution : 70k contre 88k (1.27x) ; temps 39s contre 37s. Groupe prompt d'une phrase : 4.63 (gain du skill par rapport au prompt d'une phrase : -0.11 ; gain du prompt d'une phrase par rapport à l'absence de skill : +0.46) ; 76k tokens par exécution pour le prompt d'une phrase, donc le skill coûte 1.17x le prompt d'une phrase.

Ce qui s'est passé

• Moyennes : skill 4.52, prompt d'une phrase 4.63, témoin 4.17 (n=6 chacun). Le gain net est la tâche AGENTS.md : skill 5.00 dans les deux exécutions (les 5 règles essentielles conservées, le remplissage supprimé, le pointeur obsolète corrigé, les doublons fusionnés) contre 4.29 pour le témoin et 4.71 pour le prompt d'une phrase. Les deux exécutions du prompt d'une phrase ont supprimé la règle « les migrations sont en ajout seul » en resserrant le fichier ; celles du skill l'ont conservée.
• Sur les deux tâches d'écriture de skill, le skill ne fait pas mieux que le témoin (4.18-4.59 contre 4.06-4.18) : dans les 4 exécutions avec skill sur ces tâches, la description était un résumé du flux de travail ou n'indiquait pas quand utiliser le skill (« Trier les rapports de bug entrants en demandant les étapes de reproduction manquantes et en classant la gravité... », identique au témoin), donc la liste de contrôle en 7 points a donné 5/7 ou 6/7 comme au témoin. Les exécutions du prompt d'une phrase ont écrit des descriptions de style déclencheur (« Quand un rapport de bug entrant manque d'étapes de reproduction, les demander d'abord... »).
• Le témoin a omis la règle « corps coupé à 72 caractères, expliquer pourquoi » dans les deux exécutions de skill de commit (3/4 règles) ; le skill et le prompt d'une phrase ont gardé les quatre.
• Coût : 88k tokens par exécution pour le skill contre 70k pour le témoin et 76k pour le prompt d'une phrase (1.26x, 1.16x). Les exécutions avec skill copient 4 fichiers par exécution dans le projet.
• Une vérification qui compte les scripts package.json répétés dans AGENTS.md échoue pour les 2 exécutions du témoin, ici seulement (3 correspondances), ce qui est cohérent avec la règle du skill « ne pas répéter l'environnement ».

Scores par dimension

Limites de ce test

• Vérifications basées sur des règles, en partie empruntées au test writing-skills : la liste de contrôle en 7 points récompense la formulation « Use when » que ce skill n'exige pas, ce qui le sous-estime sur les deux tâches d'écriture de skill.
• Personne n'a testé si les skills écrits ou l'AGENTS.md resserré changent réellement le comportement d'un agent.
• n=2 par cellule.
• n = 2 par groupe et par tâche : les écarts inférieurs à environ 1 point relèvent du bruit.
• La notation basée sur des règles mesure ce que les vérifications peuvent voir ; elle ne juge ni le goût ni si le résultat est le meilleur possible.

Sécurité

Voir security.md. Scan : 0 CRITICAL / 0 HIGH / 0 MEDIUM. Verdict : exécution sûre (bac à sable hors ligne). Un scan propre ne prouve pas qu'un skill est sûr.

En résumé

Utile pour compacter un fichier d'instructions (il a conservé chaque vraie règle qu'un prompt d'une phrase a laissée tomber), sinon pas meilleur que le modèle de base pour écrire de nouveaux skills, à 1.26x tokens.