writing-skills

name: writing-skills description: À utiliser lors de la création de nouvelles compétences, de l'édition de compétences existantes, ou de la vérification du fonctionnement des compétences avant le déploiement

Créer une liste de signaux d'alerte

Facilitez l'auto-vérification des agents lors de leur rationalisation :

## Signaux d'alerte - ARRÊTEZ et recommencez

- Code avant test
- "Je l'ai déjà testé manuellement"
- "Les tests après atteignent le même objectif"
- "C'est l'esprit qui compte, pas le rituel"
- "C'est différent parce que..."

**Tous ces signaux signifient : Supprimez le code. Recommencez avec TDD.**

Mettre à jour la CSO pour les symptômes de violation

Ajouter à la description : symptômes du moment où vous êtes SUR LE POINT de violer la règle :

description: à utiliser lors de l'implémentation de n'importe quelle fonctionnalité ou correction de bug, avant d'écrire le code d'implémentation

RED-GREEN-REFACTOR pour les compétences

Suivez le cycle TDD :

RED : Écrire un test défaillant (baseline)

Exécutez un scénario de pression avec un sous-agent SANS la compétence. Documentez le comportement exact :

• Quels choix ont-ils faits ?
• Quelles rationalisations ont-ils utilisées (verbatim) ?
• Quelles pressions ont déclenché des violations ?

C'est « regarder le test échouer » - vous devez voir ce que les agents font naturellement avant d'écrire la compétence.

GREEN : Écrire une compétence minimale

Écrivez une compétence qui répond à ces rationalisations spécifiques. N'ajoutez pas de contenu supplémentaire pour des cas hypothétiques.

Exécutez les mêmes scénarios AVEC la compétence. L'agent devrait maintenant être conforme.

REFACTOR : Boucher les failles

L'agent a trouvé une nouvelle rationalisation ? Ajoutez un contre-argument explicite. Testez à nouveau jusqu'à ce que ce soit blindé.

Méthodologie de test : Voir @testing-skills-with-subagents.md pour la méthodologie de test complète :

• Comment écrire des scénarios de pression
• Types de pressions (temps, coûts irrécupérables, autorité, épuisement)
• Boucher les failles systématiquement
• Techniques de méta-test

Anti-modèles

❌ Exemple narratif

"En session 2025-10-03, nous avons découvert que projectDir vide causait..." Pourquoi c'est mauvais : Trop spécifique, non réutilisable

❌ Dilution multi-langage

example-js.js, example-py.py, example-go.go Pourquoi c'est mauvais : Qualité médiocre, charge de maintenance

❌ Code dans les diagrammes de flux

step1 [label="import fs"];
step2 [label="read file"];

Pourquoi c'est mauvais : Impossible à copier-coller, difficile à lire

❌ Étiquettes génériques

helper1, helper2, step3, pattern4 Pourquoi c'est mauvais : Les étiquettes doivent avoir une signification sémantique

ARRÊT : Avant de passer à la compétence suivante

Après avoir écrit N'IMPORTE QUELLE compétence, vous DEVEZ ARRÊTER et terminer le processus de déploiement.

NE PAS :

• Créer plusieurs compétences en batch sans tester chacune
• Passer à la compétence suivante avant de vérifier la compétence actuelle
• Sauter les tests parce que « le regroupement est plus efficace »

La liste de vérification de déploiement ci-dessous est OBLIGATOIRE pour CHAQUE compétence.

Déployer des compétences non testées = déployer du code non testé. C'est une violation des normes de qualité.

Liste de vérification de création de compétence (TDD adapté)

IMPORTANT : Utilisez TodoWrite pour créer des todos pour CHAQUE élément de liste de vérification ci-dessous.

Phase RED - Écrire un test défaillant :

• [ ] Créer des scénarios de pression (3+ pressions combinées pour les compétences de discipline)
• [ ] Exécuter les scénarios SANS compétence - documenter le comportement baseline verbatim
• [ ] Identifier les modèles dans les rationalisations/échecs

Phase GREEN - Écrire une compétence minimale :

• [ ] Le nom n'utilise que des lettres, chiffres, tirets (pas de parenthèses/caractères spéciaux)
• [ ] Frontmatter YAML avec champs obligatoires name et description (max 1024 caractères ; voir spec)
• [ ] La description commence par « À utiliser quand... » et inclut les déclencheurs/symptômes spécifiques
• [ ] Description écrite à la troisième personne
• [ ] Mots-clés à travers le texte pour la recherche (erreurs, symptômes, outils)
• [ ] Vue d'ensemble claire avec principe fondamental
• [ ] Aborder les échecs baseline spécifiques identifiés dans RED
• [ ] Code inline OU lien vers un fichier séparé
• [ ] Un excellent exemple (pas multi-langage)
• [ ] Exécuter les scénarios AVEC compétence - vérifier que les agents sont maintenant conformes

Phase REFACTOR - Boucher les failles :

• [ ] Identifier les NOUVELLES rationalisations à partir des tests
• [ ] Ajouter des contre-arguments explicites (si compétence de discipline)
• [ ] Construire un tableau de rationalisation à partir de toutes les itérations de test
• [ ] Créer une liste de signaux d'alerte
• [ ] Tester à nouveau jusqu'à ce que ce soit blindé

Vérifications de qualité :

• [ ] Petit diagramme de flux uniquement si la décision n'est pas évidente
• [ ] Tableau de référence rapide
• [ ] Section des erreurs courantes
• [ ] Pas de narration storytelling
• [ ] Fichiers de support uniquement pour les outils ou les références lourdes

Déploiement :

• [ ] Valider la compétence dans git et pousser vers votre fork (si configuré)
• [ ] Envisager de contribuer via PR (si largement utile)

Flux de découverte

Comment Claude futur trouvera votre compétence :

1. Rencontre un problème (« les tests sont instables »)
2. Trouve la COMPÉTENCE (la description correspond)
3. Scanne la vue d'ensemble (c'est pertinent ?)
4. Lit les modèles (tableau de référence rapide)
5. Charge l'exemple (seulement lors de l'implémentation)

Optimisez pour ce flux - mettez les termes recherchables en avant et souvent.

Le fond du problème

Créer des compétences EST TDD pour la documentation de processus.

Même loi de fer : Pas de compétence sans test défaillant d'abord. Même cycle : RED (baseline) → GREEN (écrire la compétence) → REFACTOR (boucher les failles). Mêmes bénéfices : Meilleure qualité, moins de surprises, résultats blindés.

Si vous suivez TDD pour le code, suivez-le pour les compétences. C'est la même discipline appliquée à la documentation.