Imported from nodefony/nodefony-core (.claude/skills/nodefony-skill/SKILL.md). Install upstream with npx skills add nodefony/nodefony-core --skill nodefony-skill. Copyright stays with the author.

nodefony-skill — écrire un skill qui se déclenche et qui reste vrai

Ce skill dérive de skill-creator (bundlé) : la mécanique générique — structure d'un dossier, divulgation progressive, rédaction d'une description — y vit et n'est pas recopiée ici. Ce fichier porte ce que Nodefony ajoute, et rien d'autre.

Maintenance : vérité courante, jamais un journal. Éditer en place ; l'historique vit dans git log. Une leçon durable devient une règle d'une section, pas une entrée datée.

1. Quand m'utiliser

• Créer un skill du dépôt (.claude/skills/nodefony-<nom>/).
• Réparer un skill qui ne se déclenche jamais (le cas le plus fréquent — voir §5).
• Auditer la conformité avant une publication npm (chantier devkit).
• Décider s'il faut un skill plutôt qu'une règle de CLAUDE.md ou une commande (§2).

Passer la main : mécanique générique d'un skill → skill-creator. Écrire une page de documentation → nodefony-documentation. Scaffolder un module → nodefony-create-module.

2. La question préalable : skill, commande, ou règle ?

⚠️ Ne jamais écrire la même règle aux deux endroits. Un skill dont le CLAUDE.md redonne la commande n'est jamais invoqué : l'agent lit la règle au démarrage, exécute, et n'ouvre pas le skill — qui portait pourtant le diagnostic. Mesuré sur ce dépôt : c'est la cause n°1 des skills à zéro invocation. Le CLAUDE.md pointe, le skill détaille.

3. Conventions Nodefony (en plus du standard)

• Nom : nodefony-<sujet> en minuscules, identique au dossier. Les commandes restent courtes et non préfixées (/start-server).
• metadata.version — jamais version: à la racine : le standard n'autorise que name, description, license, metadata, allowed-tools.
• Ressources : references/ (au pluriel) pour le détail chargé à la demande, scripts/ pour l'exécutable, assets/ pour les gabarits. Le corps reste sous 500 lignes et sert d'index.
• Note de maintenance en tête : édition en place, pas de changelog, pas de date. L'avancement vit dans MIGRATION_STATUS.md, l'historique dans git log.
• Table « quand passer la main » : un skill dit toujours ce qu'il ne fait PAS, avec le nom du skill qui le fait.
• Exemples vérifiés au source — jamais de signature recopiée de mémoire.

4. Écrire la description (c'est elle qui décide de tout)

La description est le seul texte lu à chaque session : elle décide si le skill s'active. Deux règles issues de la mesure d'usage :

1. Nommer le MOMENT, pas l'outil. « RPS », « stress » ne se déclenchent pas — la demande réelle arrive en besoin : « est-ce que ça tient la charge ? », « c'est plus rapide ? », « je vais commiter une modif du pipeline ». Écrire les deux, en commençant par le besoin.
2. Dire quand charger le skill par rapport à l'action. Pour un skill à scripts : « à charger AVANT de lancer un de ces scripts » — sinon on lance le script sans le protocole, et le chiffre obtenu ne vaut rien.

Forme : troisième personne, capacité et moment, ≤ 1024 caractères, aucune roadmap.

5. Réparer un skill qui ne se déclenche jamais

Dans l'ordre, parce que les causes n'ont pas la même fréquence :

1. Sa règle est-elle recopiée dans CLAUDE.md ? → retirer la copie, y mettre un pointeur.
2. Ses déclencheurs nomment-ils l'outil au lieu du moment ? → §4.
3. Ses renvois pointent-ils encore quelque part ? → node .claude/skills/nodefony-skill/scripts/skills-doc.mjs puis vérifier les cibles. Un refactor supprime un fichier ; le renvoi, lui, survit et envoie dans le vide.
4. Est-il seulement lu, jamais invoqué ? C'est un signal de description, pas de contenu : ses references/ servent, sa porte d'entrée ne s'ouvre pas.
5. Le besoin existe-t-il encore ? Si non, le retirer franchement (règle projet : pas de legacy).

6. Fusionner, absorber ou retirer un skill

Trois gestes distincts, une même exigence : aucune capacité ne doit disparaître en silence. Un skill qu'on retire emporte avec lui ses déclencheurs — c'est-à-dire la seule chose qui permettait de l'atteindre.

Dans l'ordre :

1. Inventorier les renvois — avec les dossiers cachés. rg ignore .claude/ sans --hidden : une recherche qui l'oublie conclut « aucun consommateur » sur un skill cité partout.

   rg -n --hidden 'nodefony-<skill-retiré>' -g '!**/node_modules/**' -g '!.git/**'

   Les retex archivés (docs/session-retros/archive/) sont de l'histoire : ne pas les réécrire.

2. Écrire la destination avant de supprimer la source — sinon le contenu est perdu entre les deux.

3. Déplacer les déclencheurs, pas seulement le contenu. Une capacité absorbée dont les formulations ne rejoignent pas la description du skill d'accueil devient inatteignable : le corps existe, la porte n'existe plus.

4. Supprimer avec git rm (l'historique reste), puis réparer chaque renvoi trouvé en 1.

5. Mettre à jour l'outillage : cas du banc de déclenchement, table d'icônes/familles de skills-doc, et toute table « passer la main » qui nommait le disparu.

6. Passer le gate (§7). Le contrôle « aucun renvoi vers un skill inexistant » est là pour ça.

Une table « passer la main » se périme sans bruit. Vérifier que ce qu'elle promet existe : une table citant bash <skill>/<script> pour quatre skills dont aucun n'avait de script a survécu des mois — chaque ligne était fausse. Nommer le skill, pas un chemin supposé.

7. Gate — obligatoire avant de dire « fait »

node .claude/skills/nodefony-skill/scripts/skills-doc.mjs        # conformité des 26+ skills + régénère docs/skills/
node .claude/skills/nodefony-skill/scripts/skills-doc.mjs --check   # contrôle seul (CI)

Il vérifie, avec pour chaque contrôle sa nature (normatif = MUST du standard · recommandé = SHOULD · projet = propre à Nodefony) : name conforme (1-64, minuscules alphanumériques + -, ni au bord ni consécutifs, = nom du dossier) · description de 1 à 1024 caractères · aucun champ hors standard (compatibility désormais admis, ≤500) · compatibility ≤500 si présent · ressources en references/ · aucun renvoi vers un skill inexistant (projet) · corps < 500 lignes (recommandation). Sur un manquement dur il sort en échec, et il régénère la fiche publique dans docs/skills/<nom>.md — version, contenu, déclencheurs, table des references/ avec l'objet de chacune, scripts avec options et variables, et une conformité qui cite la règle exacte du standard (nature + source), pour qu'un lecteur voie d'où sort chaque contrôle.

Les constantes du standard vivent en tête de skills-doc.mjs (ALLOWED_FIELDS, MAX_DESC, MAX_COMPAT, NAME_RE) avec un lien vers la spec. Le standard bouge (le champ compatibility est une addition récente) → revalider contre tmp/specs-agents/ avant de durcir un contrôle.

Le contrôle des renvois ne lit que les noms entre accents graves, dans le SKILL.md et les references/ — les scripts citent des conteneurs et des titres de processus qui portent le même préfixe. Les quelques nodefony-… qui ne désignent pas un skill (le dépôt lui-même, un service, un composant) sont déclarés dans NON_SKILL_TERMS, en tête de skills-doc.mjs : y ajouter un terme demande de justifier pourquoi ce n'en est pas un.

Validateur officiel du standard — il attrape ce qu'un contrôle maison rate, à commencer par un frontmatter YAML invalide (une description en ligne contenant un : casse le mapping sans que rien d'autre ne s'en aperçoive) :

npm pack skills-ref && tar xzf skills-ref-*.tgz     # dans un dossier jetable
node package/dist/cli.js validate ./<skill>          # après y avoir installé commander + js-yaml

⚠️ Auditer avant d'exécuter. Le paquet skills-ref n'a ni repository ni homepage sur npm et n'est pas attribuable à l'AAIF : il lit tous les skills du dépôt. Audité une fois (20 Ko, node:fs/node:path seulement, aucun accès réseau, MIT) — refaire cette lecture à chaque montée de version plutôt que de lui faire confiance sur son nom. C'est pour ça que la commande ci-dessus dépaquette au lieu d'un npx qui exécuterait sans regarder.

Banc de déclenchement — la garde anti-régression des descriptions :

node .claude/skills/nodefony-skill/scripts/trigger-bench.mjs            # phrases réelles → skill élu
node .claude/skills/nodefony-skill/scripts/trigger-bench.mjs --verbose  # + le détail des scores

Il porte quatre mesures, à relancer après toute retouche de description :

1. Phrases réelles (issues des retex et des mémoires) → le bon skill doit sortir en tête. Une phrase qui rate son skill fait échouer le banc.
2. Cas NÉGATIFS → une phrase qui ne DOIT PAS élire un skill donné (ex. « crée un module » ne doit pas élire nodefony-inspect). C'est ce qui attrape la sur-portée : élargir une description sans y penser vole une demande à un autre skill. Une violation fait échouer le banc.
3. Couverture → tout skill a au moins une porte testée (un skill neuf sans cas est signalé).
4. Recouvrements de déclencheurs, séparés en arbitrés (documentés dans ACCEPTED_OVERLAPS avec la raison — « fuite mémoire » est mieux capté par check-memory-health que par debug) et à trancher (le vrai bruit). Un nouveau recouvrement non documenté ressort seul, à arbitrer puis documenter. Les cas verts fragiles (faible marge sur le 2ᵉ) sont comptés (--verbose les détaille).

Audit de placement — où vit chaque script, et qui l'appelle :

node .claude/skills/nodefony-skill/scripts/scripts-audit.mjs           # rapport
node .claude/skills/nodefony-skill/scripts/scripts-audit.mjs --strict  # échoue sur orphelin, renvoi mort ou écart d'acquittement

Il classe les scripts du dépôt selon le critère du §2 : dépend d'un protocole → sa place est dans un skill ; déterministe et câblé au package.json → il reste à la racine. Il signale aussi les scripts que personne ne cite (morts, ou simplement non documentés) et les renvois vers un fichier absent. Trois faux positifs ont été corrigés avant de lui faire confiance : .js capturé dans .json, renvois croisés entre skills déclarés morts faute d'être cherchés ailleurs, et « mentionne docker » confondu avec « lance docker ».

🔴 Être NOMMÉ dans une page n'est pas être EXÉCUTÉ. Le contrôle a longtemps compté une phrase de documentation comme un appel : il annonçait « 0 orphelin » pendant qu'une vingtaine d'auto-contrôles, énumérés un par un dans leur page de skill, n'étaient lancés par rien — dont celui qui savait nommer quinze causes qu'aucun juge ne classait. Un script n'est « lancé » que par un automate : un script npm, un étage de forge, ou un autre source qui le nomme (le nommer dans un .mjs, c'est s'en servir ; le nommer dans un .md, c'est en parler). Les autres sortent en 📄 documenté, jamais lancé — un état, pas une faute : un banc de charge se tape à la main, et c'est très bien.

Ce qui serait une faute, c'est qu'un script NEUF y entre sans qu'on le remarque. La liste versionnée scripts-audit.attendus.json fige l'état connu, et --strict ne mord que sur l'écart : une entrée non acquittée, ou un acquittement devenu faux parce que le script est désormais câblé. Un gate qui rouge en permanence ne garde plus rien — celui-ci ne rouge que sur un changement. Câbler un script, c'est le RETIRER de la liste ; le laisser ferait échouer la passe.

Le critère « invocation adjacente » a été essayé et écarté : il accusait 39 juges parfaitement vivants, dont le chemin est assemblé dans une constante et remis à un lanceur dix lignes plus loin.

Ce banc mesure la surface lexicale, pas le jugement du modèle : un cas vert ne garantit pas l'invocation, mais un cas rouge est un vrai défaut — aucun mot de la demande ne rejoint la description.

8. Le hook de doc — un script se décrit lui-même

Un script documenté ailleurs que dans son source diverge le jour où on l'édite. Six tags facultatifs, lus par skills-doc, suffisent à rendre la fiche exacte au lieu de devinée :

Sans eux, le générateur retombe sur l'heuristique : première ligne de commentaire, drapeaux trouvés dans le source, variables lues hors variables de travail. Avec eux, la fiche gagne un détail par script — invocations, options et variables avec leur explication.

Piège de l'auto-référence : écrire ces tags en exemple dans un commentaire les fait moissonner par leur propre lecteur. Les entourer d'accents graves.

9. Ce que consomme un registre de skills

skills-doc écrit aussi docs/skills/registry.json — la même donnée que les fiches, sérialisée pour une machine : résumé d'une ligne, famille, mots-clés, déclencheurs, coût d'activation en tokens, prérequis, ressources et scripts (options, variables, sortie), graphe de voisinage entre skills, état de conformité contrôle par contrôle, et liens source/fiche. C'est le format qu'un moteur de recherche de skills ou un registre lit sans ouvrir vingt-sept markdown — et c'est aussi ce qui rendra une publication npm possible sans réécrire l'inventaire à la main.

10. Gabarit

---
name: nodefony-<sujet>
metadata:
  version: 1.0.0
description: >
  <Ce qu'il fait, en une phrase à la troisième personne.> <Ce qu'il apporte que l'exécution nue
  n'apporte pas : protocole, décor, pièges.> <Ce qu'il ne couvre pas → skill qui le couvre.>
  Déclencheurs : "<formulation de besoin>", "<moment : avant de …>", "<terme technique>".
---

# nodefony-<sujet> — <promesse en une ligne>

> **Maintenance** : vérité courante, jamais un journal. Éditer en place ; historique = `git log`.

## 1. Quand m'utiliser / quand passer la main

| Besoin | Skill |
| ------ | ----- |

## 2. La procédure

<Les étapes, dans l'ordre, avec les commandes exactes.>

## 3. Pièges

<Ce qui a déjà coûté cher, formulé en règle.>

## 4. Gate

<Comment on prouve que c'est fait.>

11. Pièges vécus

• Une fiche écrite à la main diverge du skill dès la première édition → les fiches docs/skills/ sont générées ; ne jamais les éditer.
• Un renvoi survit à la disparition de sa cible : un refactor a supprimé des references/recipes-*.md en laissant huit renvois morts, plus un renvoi vers une section « §4 » réorganisée entre-temps. Vérifier les cibles fait partie du gate — désormais les renvois vers un skill inexistant le font échouer (§7). Vécu à la fusion des quatre skills d'inspection : frontend-verify était cité par debug, studio-dev et leurs references/.
• Mesurer une description avec une regex $ en mode multiligne ne lit que sa première ligne — le contrôle disait « conforme » sur des descriptions à 1900 caractères. Un gate qu'on n'a jamais vu mordre n'est pas un gate.
• Un déclencheur improbable ne coûte rien mais ne rapporte rien : « 59 fails framework sans serveur » n'a jamais rien déclenché. Préférer trois formulations naturelles à dix exactes.

12. Liens

• docs/outillage-agents.md — inventaire, usage mesuré, étude des fusions et retraits.
• docs/skills/index.md — les fiches générées, une par skill.
• skill-creator — la mécanique générique (structure, divulgation progressive, évaluation).