writing-skills

Vue d’ensemble

Ce que fait la skill writing-skills

La skill writing-skills est une méta-skill destinée aux personnes qui conçoivent, affinent et testent d’autres skills pour des agents comme Claude. Elle adapte les principes classiques du Test-Driven Development (TDD) à la documentation de processus, pour que vos skills soient :

• Ancrées dans de vrais scénarios de pression
• Vérifiées à partir de défaillances réelles d’agents
• Affinées pour fermer les failles et résister à la rationalisation

Vous utilisez writing-skills pour concevoir des skills que les agents peuvent découvrir, suivre, et continuer à suivre même sous pression temporelle, biais des coûts irrécupérables ou incitations conflictuelles.

À qui s’adresse writing-skills

Utilisez la skill writing-skills si vous êtes :

• Un développeur qui crée des skills pour Claude ou des agents similaires
• Un responsable d’équipe qui standardise des workflows dans ~/.claude/skills ou ~/.agents/skills/
• Un responsable de documentation en charge de skills qui doivent être suivies, pas seulement lues
• Un testeur qui valide que les skills modifient réellement le comportement de l’agent avant déploiement

Elle ne se concentre pas sur le style d’écriture générique. Elle vise spécifiquement la rédaction de skills d’agent efficaces et testables.

Problèmes que cette skill vous aide à résoudre

writing-skills est conçue pour les situations où :

• Les agents ignorent vos skills ou ne les suivent que partiellement sous pression
• Vous ne savez pas si une nouvelle skill change réellement le comportement
• Vous avez besoin d’une méthode reproductible pour tester vos skills avec des subagents avant déploiement
• Vous voulez vous aligner sur les bonnes pratiques Anthropic de rédaction de skills sans devoir deviner
• Vous devez visualiser et communiquer des workflows de skills complexes avec Graphviz

Si vos skills ressemblent davantage à des histoires ponctuelles ou à des notes, writing-skills vous aide à les transformer en guides de référence réutilisables et testables.

Quand writing-skills est (ou n’est pas) adaptée

Bon cas d’usage :

• Skills qui imposent de la discipline (TDD, vérification, checklists de revue)
• Skills qui ont un véritable coût de conformité (temps, retours arrière, livraisons retardées)
• Skills que les agents pourraient essayer de contourner ("juste cette fois")
• Skills pour lesquelles vous voulez une amélioration mesurable des taux de conformité

Mauvais cas d’usage :

• Skills purement référentielles (p. ex. syntaxe d’API, fiches mémo de base)
• Skills qui n’ont volontairement aucune règle à violer
• Notes légères pour lesquelles vous n’avez pas besoin de tests façon TDD ni de scénarios de pression

Si vous avez seulement besoin d’une note rapide et informelle pour une conversation, vous n’avez probablement pas besoin de writing-skills. Si vous voulez une skill qui résiste à la pression de production, oui.

Utilisation

Installation et configuration de base

Pour installer la skill writing-skills dans un environnement compatible skills :

npx skills add https://github.com/obra/superpowers --skill writing-skills

Cette commande récupère la skill writing-skills depuis le dépôt obra/superpowers et l’enregistre aux côtés de vos autres skills.

Les skills personnelles se trouvent en général dans des répertoires spécifiques à l’agent, par exemple :

• ~/.claude/skills/ pour Claude Code
• ~/.agents/skills/ pour Codex ou des agents similaires

Placez (ou vérifiez la présence de) le répertoire writing-skills sous la racine de skills appropriée pour que votre agent puisse charger SKILL.md et les fichiers associés au besoin.

Fichiers et dossiers clés dans writing-skills

Une fois installée, commencez par ouvrir ces fichiers pour comprendre et appliquer le workflow :

• SKILL.md – Définition centrale de la skill et vue d’ensemble de writing-skills, incluant le mapping TDD pour les skills.
• anthropic-best-practices.md – Guide de style "officiel" pour écrire des skills concises, découvrables et efficaces pour Claude.
• testing-skills-with-subagents.md – Guide pratique pour construire et exécuter des scénarios de pression et des campagnes de test.
• persuasion-principles.md – Principes de persuasion fondés sur des preuves pour améliorer la conformité de l’agent à vos skills.
• graphviz-conventions.dot – Conventions pour représenter des workflows et processus de skills en diagrammes Graphviz.
• render-graphs.js – Script utilitaire qui extrait les blocs ```dot de SKILL.md et les rend en diagrammes SVG.
• examples/CLAUDE_MD_TESTING.md – Exemple complet d’une campagne de test pour différentes variantes de documentation CLAUDE.md.

Ces fichiers se complètent pour vous offrir un workflow complet rédaction + test + visualisation des skills.

Workflow central : TDD appliqué aux skills

writing-skills applique les concepts TDD directement à la rédaction de skills. Le cycle haut niveau est :

1. Écrire les cas de test (scénarios de pression)

   • Concevez des situations réalistes où un agent pourrait rationaliser le fait de sauter ou de plier votre processus cible.
   • Utilisez des subagents pour exécuter ces scénarios et capturer leur comportement.

2. Lancer les tests de base et les regarder échouer

   • Exécutez les scénarios sans votre nouvelle skill (ou skill mise à jour) chargée.
   • Capturez les défaillances de l’agent : ce qu’il saute, rationalise ou comprend mal.

3. Rédiger ou affiner la skill

   • Rédigez ou mettez à jour SKILL.md et tout fichier de support pour traiter les échecs précis observés.
   • Utilisez un langage concise et impératif adapté aux contraintes de la fenêtre de contexte.

4. Relancer les tests avec la skill chargée

   • Réexécutez les mêmes scénarios, cette fois avec votre skill activée.
   • Vérifiez que l’agent découvre, annonce et suit désormais la skill.

5. Refactorer pour fermer les failles

   • Identifiez les rationalisations restantes ou la conformité partielle.
   • Appliquez des principes de persuasion (autorité, engagement, etc.) pour renforcer l’adhérence.
   • Éliminez les tokens superflus pour garder la skill concise.

Ce cycle reflète le schéma ROUGE → VERT → REFACTOR du TDD classique, mais appliqué à la documentation et à l’application de processus plutôt qu’au code.

Utiliser anthropic-best-practices.md pour de meilleures skills

Le fichier anthropic-best-practices.md fournit des recommandations spécifiques à l’écosystème Claude, notamment :

• Pourquoi des skills concises améliorent l’usage du contexte et les performances du modèle
• Comment et quand Claude charge SKILL.md et d’autres fichiers dans la fenêtre de contexte
• Comment rédiger des sections de skill qui justifient leur coût en tokens

Vous pouvez utiliser ce fichier comme checklist lors de la relecture de vos propres skills :

• Supprimer les explications que Claude connaît déjà
• Vous concentrer sur les schémas d’action, règles et workflows
• Structurer les skills pour que les instructions les plus importantes apparaissent tôt et clairement

En intégrant ces pratiques au cycle TDD de writing-skills, vous augmentez les chances que vos skills soient à la fois faciles à découvrir et efficaces.

Tester les skills avec des subagents

Le fichier testing-skills-with-subagents.md étend l’approche TDD avec une méthode de test concrète :

• Concevez des scénarios qui reproduisent la vraie pression de production (temps, coûts irrécupérables, vitesse vs qualité).
• Exécutez-les avec des subagents qui représentent le comportement de votre agent principal.
• Capturez les échecs et rationalisations dans des formats structurés.

C’est particulièrement utile pour les skills qui :

• Imposent des bonnes pratiques chronophages (p. ex. écrire les tests en premier)
• Entrent en compétition avec des objectifs de court terme (p. ex. livrer plus vite vs vérifier en profondeur)
• Doivent tenir bon quand des humains demandent explicitement des raccourcis

En suivant les modèles de test de ce fichier, vous pouvez vérifier les skills sous pression avant qu’elles n’atteignent les utilisateurs finaux.

Appliquer des principes de persuasion dans la conception de skills

persuasion-principles.md résume des principes psychologiques qui influencent aussi le comportement des LLM, tels que :

• Autorité – Langage clair et non négociable pour les règles critiques de sécurité
• Engagement – Exiger des agents qu’ils annoncent quand ils utilisent une skill et qu’ils respectent la voie choisie
• Rareté et autres – Utilisés avec prudence pour prioriser les pratiques critiques

En pratique, vous pouvez :

• Employer un ton plus impératif pour les étapes non optionnelles
• Demander à l’agent de déclarer explicitement : "I am using [Skill Name] now" quand une skill est activée
• Concevoir des checklists qui imposent la complétion plutôt qu’une lecture passive

L’objectif n’est pas de manipuler, mais de garantir que les pratiques critiques soient suivies de manière cohérente.

Visualiser les flux de skills avec Graphviz

Les skills complexes bénéficient souvent d’une représentation visuelle. writing-skills inclut :

• graphviz-conventions.dot – Structure et style suggérés pour les diagrammes
• render-graphs.js – Script Node.js qui extrait les blocs ```dot depuis SKILL.md et les transforme en fichiers SVG.

Utilisation de base du renderer :

./render-graphs.js path/to/your/skill
# ou
./render-graphs.js path/to/your/skill --combine

Cela vous aide à :

• Communiquer le flux d’une skill à vos collaborateurs humains
• Repérer les manques ou boucles dans la conception de votre processus
• Garder documentation et visuels synchronisés en intégrant les diagrammes sous forme de blocs de code ```dot dans SKILL.md.

Adapter writing-skills à votre environnement

Le dépôt décrit des modèles que vous devez adapter, pas copier à l’identique. Pour intégrer writing-skills dans votre propre workflow :

• Conservez le cycle TDD, mais ajustez le format des scénarios à vos outils
• Utilisez votre propre structure de répertoires si nécessaire, en gardant des frontières de skills claires
• Intégrez les campagnes de test à vos processus existants de CI, revue ou release

L’objectif est un workflow de rédaction pilotée par les tests, reproductible, adapté à votre équipe et à votre infrastructure.

FAQ

Quand dois-je charger la skill writing-skills ?

Utilisez writing-skills lorsque vous :

• Créez une nouvelle skill destinée à vivre sous ~/.claude/skills ou des répertoires similaires
• Modifiez une skill existante qui commence à dériver ou à être ignorée
• Préparez une skill pour un déploiement auprès de coéquipiers ou pour un usage en production
• Concevez ou exécutez une campagne de test de skills avec des subagents

Si vous faites juste des essais dans une session éphémère unique, vous n’avez peut-être pas besoin de tout le workflow writing-skills.

Dois-je comprendre le TDD avant d’utiliser writing-skills ?

Oui. Cette skill suppose que vous connaissez superpowers:test-driven-development. writing-skills part du principe que vous maîtrisez déjà le cycle ROUGE → VERT → REFACTOR, puis l’applique à la documentation :

• ROUGE : lancer des scénarios sans la skill, capturer les échecs
• VERT : ajouter ou affiner la skill pour faire passer ces scénarios
• REFACTOR : améliorer la clarté, fermer les failles et réduire le coût en tokens

Si le TDD est nouveau pour vous, chargez et étudiez d’abord la skill liée au TDD.

En quoi writing-skills aide-t-elle pour le comportement spécifique de Claude ?

writing-skills est conçue pour des environnements comme Claude, et le dépôt inclut anthropic-best-practices.md avec des recommandations alignées sur la documentation Anthropic. Ensemble, ils vous aident à :

• Rédiger des skills que Claude peut découvrir de manière fiable
• Respecter la fenêtre de contexte et le budget de tokens
• Structurer les fichiers SKILL pour que Claude les charge et les utilise efficacement

Cela rend writing-skills particulièrement utile si vous construisez une bibliothèque de skills pour Claude.

Puis-je utiliser writing-skills pour des skills non techniques ou sans code ?

Oui, tant que la skill décrit un processus reproductible pouvant être testé via des scénarios. Exemples :

• Checklists de gestion d’incident
• Workflows de revue de code
• Processus de relecture ou de validation de documentation

L’essentiel est que le processus comporte :

• Des règles claires que les agents peuvent suivre ou violer
• De vraies conséquences si des étapes sont ignorées
• Des scénarios permettant de tester réellement la conformité

Des contenus purement descriptifs ou narratifs ne constituent pas une bonne cible.

À quoi sert le fichier examples/CLAUDE_MD_TESTING.md ?

examples/CLAUDE_MD_TESTING.md est un exemple complet qui montre comment :

• Concevoir des scénarios réalistes (pression temporelle, coût irrécupérable, autorité vs vitesse)
• Les exécuter sur différentes variantes de documentation CLAUDE.md
• Comparer dans quelle mesure chaque variante favorise la découverte et l’usage de la skill

Servez-vous-en comme modèle pour créer vos propres campagnes de test de skills.

En quoi une skill diffère-t-elle d’une histoire ou d’une étude de cas ?

Dans le modèle writing-skills :

• Une skill est un guide de référence réutilisable qui encode des schémas, outils ou workflows éprouvés.
• Une histoire ou étude de cas décrit comment vous avez résolu un problème spécifique, une fois.

writing-skills vous aide à passer d’histoires ponctuelles à des skills généralisées et testables que les agents futurs pourront trouver et appliquer à de nouvelles situations.

Et si ma skill est longue – est-ce important ?

La longueur compte à cause de la fenêtre de contexte. anthropic-best-practices.md explique pourquoi les skills concises fonctionnent mieux :

• Seules les métadonnées sont chargées au départ, mais une fois SKILL.md lu, chaque token entre en concurrence avec l’historique de la conversation.
• Vous devriez constamment vous demander si chaque section mérite sa place.

writing-skills vous incite à :

• Supprimer les explications redondantes
• Déplacer les exemples dans des fichiers de support si nécessaire
• Concentrer SKILL.md sur le processus central et les règles qui permettent aux tests de réussir

Comment savoir si writing-skills fonctionne ?

Vous verrez l’impact lorsque :

• Des skills auparavant ignorées sous pression sont désormais suivies
• Les nouvelles skills arrivent avec des scénarios et tests explicites, pas seulement du texte
• Vous pouvez pointer des comportements "avant/après" chez les agents sur des scénarios précis

Si vous ne pouvez pas montrer de différence entre le comportement avec et sans une skill, revenez au cycle TDD ainsi qu’aux guides de persuasion et de test fournis par writing-skills.