writing-skills — comment les skills Carbon sont écrits

La source de vérité est .ai/skills/{name}/SKILL.md. L'installateur (.ai/scripts/install-skills.sh, exécuté automatiquement par pnpm prepare ou manuellement via pnpm install-skills) crée des liens symboliques de chaque répertoire de skill dans .claude/skills/ et .codex/skills/. Ne jamais éditer sous .claude/ ou .codex/ — éditer uniquement .ai/skills/.

La prime directive : écrire pour l'exécuteur le plus faible

Supposez que le modèle exécutant un skill est bien moins capable que vous et n'a aucun contexte. Il n'inférera pas l'intention, ne comblera pas les lacunes, n'exercera pas son jugement. Donc :

1. Un seul chemin canonique par tâche. N'offrez jamais d'options sans déclarer un défaut. « Choisir ce qui convient » est une lacune ; un modèle faible remplit mal les lacunes.
2. Commandes exactes avec sortie attendue. Chaque vérification est une commande plus ce que sa sortie doit contenir. « Vérifier que ça marche » n'est pas une instruction.
3. Chemins exacts. Jamais « le répertoire approprié ». Jamais un chemin que vous n'avez pas confirmé exister.
4. Règles STOP inline. Déclarez explicitement quand arrêter et signaler au lieu d'improviser (« 2 tentatives échouées → STOP », « question ouverte non résolue → STOP »).
5. Tableaux de décision plutôt que prose. Situation → action. Un modèle faible peut faire correspondre une ligne ; il ne peut pas peser un essai.
6. Références vérifiées uniquement. Tout fichier, commande, et skill qu'un skill mentionne doit exister — exécutez la commande, faites ls du chemin, avant de l'écrire. Cela inclut les affirmations héritées d'une version antérieure du skill : re-vérifiez-les ; l'auteur précédent peut s'être trompé. Une référence à quelque chose qui n'existe pas envoie l'exécuteur en boucle.
7. Fermez explicitement les failles. Pour les règles de discipline, listez les contournements spécifiques qui sont interdits et les phrases d'alerte qui signifient « arrêtez » (« juste cette fois », « je testerai après », « le garder comme référence »).
8. Annoncez au démarrage. Les skills de workflow s'ouvrent avec une ligne nommant le skill et sa cible. Cela verrouille l'exécuteur dans la procédure et indique au supervisant humain quel playbook s'exécute.
9. Non-interactif uniquement. Ne jamais instruire git rebase -i, git add -i, git restore -p, ou quoi que ce soit qui ouvre un éditeur/prompt — les commandes interactives se suspendent dans les harnais d'agent. Donnez l'équivalent non-interactif.
10. Groupez les assets pour la sortie générative. Quand un skill produit un artefact stylisé (page HTML, scaffold de document), livrez un modèle rempli sous assets/ et faites en sorte que l'exécuteur copie + remplisse les marqueurs <!-- FILL --> — les modèles faibles remplissent les modèles bien mieux qu'ils n'inventent la structure.

Contrat frontmatter (exigences fermes)

• Le fichier commence par --- à la ligne 1. Rien avant — un commentaire HTML au-dessus du frontmatter casse l'analyse de description et le commentaire fuit dans la liste des skills. Les commentaires d'attribution vont sous le --- de fermeture.
• name: doit égaler exactement le nom du répertoire (lettres, chiffres, tirets). L'installateur crée des liens symboliques par nom de répertoire ; une non-correspondance déconnecte le skill.
• description: ≤1024 caractères, troisième personne. Formule : ce qu'il fait et produit + « Utiliser quand … » déclencheurs concrets + quand NE PAS utiliser, pointant vers le skill frère applicable. La description est la seule chose que le modèle voit avant de décider de charger le skill — les déclencheurs comptent plus que l'élégance.

Modèle maison

---
name: {dir-name}
description: {ce qu'il fait/produit}. Utiliser quand {déclencheurs}. Ne pas utiliser pour {cas adjacent} — utiliser /{autre-skill}.
---

# {name} — {objectif d'une ligne}

{2–3 phrases : contrat entrée → sortie.}

**Annoncer au démarrage :** « Utilisation du skill {name} — {objectif}. »

## Étape 1 : {impératif}
{commandes exactes, sortie attendue}
...

## Sortie
{modèle exact que le skill doit produire, dans un bloc clôturé}

## Terminé quand
- [ ] {élément vérifiable — un résultat de commande ou un artefact à un chemin exact}

## Défaillance → action        {quand le skill peut échouer en cours d'exécution}
| Symptôme | Action |

Dimensionnement : la plupart des skills 60–180 lignes. Déplacez le matériel de référence lourd (100+ lignes) vers references/*.md dans le répertoire du skill et dites exactement quand lire chaque fichier. Un excellent exemple vaut mieux que trois médiocres.

Piège de formatage : quand un bloc modèle dans votre skill doit lui-même contenir des commandes clôturées, utilisez une clôture externe à quatre backticks (````markdown ````` ) — une clôture à trois backticks à l'intérieur d'une clôture à trois backticks ferme le bloc externe tôt et enlaidit tout après.

Chemins d'artefacts canoniques (utilisez ceux-ci ; n'en inventez jamais de nouveaux)

Conventions de commande que chaque skill doit respecter : typecheck scoped uniquement (pnpm exec turbo run typecheck --filter=<pkg> — le repo entier OOM), pnpm jamais npm, pnpm run generate:types après les migrations avant le typechecking, les commits passent par /check-and-commit.

Workflow pour un skill nouveau ou édité

1. Vérifiez le chevauchement en premier. Lisez .ai/skills/README.md. Si un skill existant couvre 70 % du travail, étendez-le — deux skills qui se chevauchent avec des instructions différentes c'est pire qu'un skill imparfait.
2. Écrivez le skill selon le modèle. Vérifiez chaque référence (règle 6).
3. Test lecture à froid. Distribuez un sous-agent avec uniquement le texte du skill et une tâche réaliste ; observez où il stagne, improvise, ou mal lit. Chaque stagnation est une lacune dans le skill, pas un défaut de l'exécuteur. Corrigez et répétez.
4. Re-exécutez l'installateur et confirmez que le skill s'enregistre :

   pnpm install-skills && bash .ai/scripts/install-skills.sh --list

5. Mettez à jour .ai/skills/README.md (l'index) et, si le skill appartient à un pipeline, le tableau Workflows dans AGENTS.md racine.

Règles d'édition

• Un skill qui nomme un fichier, une commande, ou un drapeau qui n'existe plus est périmé — corrigez-le dès que vous le remarquez (.ai/rules/keep-sources-in-sync.md).
• N'affaiblissez jamais une règle STOP ou une porte pour qu'une exécution réussisse.
• Quand vous changez le contrat d'un skill (entrées, sorties, chemins d'artefacts), grep les fichiers .ai/ et AGENTS.md pour les références entrantes et mettez-les à jour dans la même modification.