writing-skills

Rédiger des Compétences

Aperçu

Rédiger des compétences, c'est le Développement Piloté par les Tests appliqué à la documentation des processus.

Les compétences personnelles se trouvent dans le répertoire des compétences de votre environnement d'exécution (~/.claude/skills/ sur Claude Code) — consultez codex-tools.md ou gemini-tools.md pour le chemin sur ces environnements. Codex, Copilot CLI et Gemini CLI reconnaissent également ~/.agents/skills/ comme un alias multi-environnement.

Vous rédigez des cas de test (scénarios de pression avec sous-agents), vous les regardez échouer (comportement de base), vous rédigez la compétence (documentation), vous regardez les tests réussir (les agents se conforment), et vous refactorez (pour combler les failles).

Principe fondamental : Si vous n'avez pas regardé un agent échouer sans la compétence, vous ne savez pas si la compétence enseigne la bonne chose.

CONNAISSANCES REQUISES : Vous DEVEZ comprendre superpowers:test-driven-development avant d'utiliser cette compétence. Cette compétence définit le cycle fondamental ROUGE-VERT-REFACTOR. Celle-ci adapte le TDD à la documentation.

Guide officiel : Pour les bonnes pratiques officielles de création de compétences d'Anthropic, consultez anthropic-best-practices.md. Ce document fournit des modèles et directives supplémentaires qui complètent l'approche axée sur le TDD de cette compétence.

Qu'est-ce qu'une Compétence ?

Une compétence est un guide de référence pour des techniques, modèles ou outils éprouvés. Les compétences aident les futurs agents à trouver et appliquer des approches efficaces.

Les compétences sont : Des techniques réutilisables, des modèles, des outils, des guides de référence

Les compétences ne sont PAS : Des récits sur la façon dont vous avez résolu un problème une fois.

Correspondance TDD pour les Compétences

Concept TDD	Création de compétence
Cas de test	Scénario de pression avec sous-agent
Code de production	Document de compétence (SKILL.md)
Le test échoue (ROUGE)	L'agent enfreint la règle sans la compétence (base)
Le test réussit (VERT)	L'agent se conforme avec la compétence présente
Refactor	Combler les failles tout en maintenant la conformité
Écrire le test d'abord	Exécuter le scénario de base AVANT d'écrire la compétence
Le regarder échouer	Documenter les justifications exactes de l'agent
Code minimal	Rédiger la compétence en ciblant ces violations spécifiques
Le regarder réussir	Vérifier que l'agent se conforme maintenant
Cycle de refactor	Trouver de nouvelles justifications → corriger → revérifier

L'ensemble du processus de création de compétences suit le cycle ROUGE-VERT-REFACTOR.

Quand Créer une Compétence

Créer quand :

• La technique n'était pas intuitivement évidente pour vous
• Vous y feriez référence à nouveau dans différents projets
• Le modèle s'applique largement (pas spécifique à un projet)
• D'autres en bénéficieraient

Ne pas créer pour :

• Des solutions ponctuelles
• Des pratiques standard bien documentées ailleurs
• Des conventions spécifiques à un projet (mettez-les dans votre fichier d'instructions)
• Des contraintes mécaniques (si c'est applicable avec regex/validation, automatisez-le — réservez la documentation pour les jugements)

Types de Compétences

Technique

Méthode concrète avec des étapes à suivre (attente-conditionnelle, traçage-cause-racine)

Modèle

Façon de penser les problèmes (aplatir-avec-drapeaux, invariants-de-test)

Référence

Documentation d'API, guides de syntaxe, documentation d'outils (documents Office)

Structure des Répertoires

skills/
  skill-name/
    SKILL.md              # Référence principale (obligatoire)
    supporting-file.*      # Uniquement si nécessaire

Espace de noms plat - toutes les compétences dans un seul espace de noms consultable

Fichiers séparés pour :

1. Références lourdes (100+ lignes) - Documentation d'API, syntaxe complète
2. Outils réutilisables - Scripts, utilitaires, modèles

Garder en ligne :

• Principes et concepts
• Modèles de code (< 50 lignes)
• Tout le reste

Structure de SKILL.md

Frontmatter (YAML) :

• Deux champs obligatoires : name et description (voir agentskills.io/specification pour tous les champs pris en charge)
• Maximum 1024 caractères au total
• name : Utilisez uniquement des lettres, des chiffres et des tirets (pas de parenthèses, caractères spéciaux)
• description : Troisième personne, décrit UNIQUEMENT quand utiliser (PAS ce qu'elle fait)
  • Commencez par "Utiliser quand..." pour vous concentrer sur les conditions de déclenchement
  • Incluez des symptômes, situations et contextes spécifiques
  • Ne RÉSUMEZ JAMAIS le processus ou le flux de travail de la compétence (voir la section SDO pour savoir pourquoi)
  • Essayez de rester sous les 500 caractères si possible

---
name: Nom-De-La-Competence-Avec-Tirets
description: Utiliser quand [conditions et symptômes de déclenchement spécifiques]
---

# Nom de la Compétence

## Aperçu
Qu'est-ce que c'est ? Principe fondamental en 1-2 phrases.

## Quand l'Utiliser
[Petit organigramme en ligne SI la décision n'est pas évidente]

Liste à puces avec SYMPTÔMES et cas d'utilisation
Quand NE PAS l'utiliser

## Modèle Principal (pour techniques/modèles)
Comparaison de code avant/après

## Référence Rapide
Tableau ou puces pour parcourir les opérations courantes

## Implémentation
Code en ligne pour les modèles simples
Lien vers un fichier pour les références lourdes ou outils réutilisables

## Erreurs Fréquentes
Ce qui va mal + correctifs

## Impact dans le Monde Réel (optionnel)
Résultats concrets

Optimisation de la Découvrabilité des Compétences (SDO)

Crucial pour la découverte : Les futurs agents ont besoin de TROUVER votre compétence

1. Champ de Description Riche

Objectif : Votre agent lit la description pour décider quelles compétences charger pour une tâche donnée. Faites en sorte qu'il réponde à la question : "Dois-je lire cette compétence maintenant ?"

Format : Commencez par "Utiliser quand..." pour vous concentrer sur les conditions de déclenchement

CRITIQUE : Description = Quand Utiliser, PAS Ce Que Fait la Compétence

La description doit UNIQUEMENT décrire les conditions de déclenchement. Ne résumez PAS le processus ou le flux de travail de la compétence dans la description.

Pourquoi c'est important : Les tests ont révélé que lorsqu'une description résume le flux de travail de la compétence, un agent peut suivre la description au lieu de lire le contenu complet de la compétence. Une description disant "revue de code entre les tâches" a amené un agent à effectuer UNE seule revue, même si l'organigramme de la compétence montrait clairement DEUX revues (conformité aux spécifications puis qualité du code).

Lorsque la description a été changée en simplement "Utiliser quand on exécute des plans d'implémentation avec des tâches indépendantes" (sans résumé du flux de travail), l'agent a correctement lu l'organigramme et suivi le processus de revue en deux étapes.

Le piège : Les descriptions qui résument le flux de travail créent un raccourci que les agents emprunteront. Le corps de la compétence devient une documentation que les agents ignorent.

# ❌ MAUVAIS : Résume le flux de travail - les agents peuvent suivre ceci au lieu de lire la compétence
description: Utiliser quand on exécute des plans - dispatche un sous-agent par tâche avec revue de code entre les tâches

# ❌ MAUVAIS : Trop de détails de processus
description: Utiliser pour le TDD - écrire le test d'abord, le regarder échouer, écrire le code minimal, refactorer

# ✅ BON : Juste les conditions de déclenchement, pas de résumé du flux de travail
description: Utiliser quand on exécute des plans d'implémentation avec des tâches indépendantes dans la session en cours

# ✅ BON : Conditions de déclenchement uniquement
description: Utiliser quand on implémente une fonctionnalité ou un correctif, avant d'écrire le code d'implémentation

Contenu :

• Utilisez des déclencheurs, symptômes et situations concrets qui signalent que cette compétence s'applique
• Décrivez le problème (conditions de course, comportement incohérent) pas les symptômes spécifiques au langage (setTimeout, sleep)
• Gardez les déclencheurs indépendants de la technologie, sauf si la compétence elle-même est spécifique à une technologie
• Si la compétence est spécifique à une technologie, rendez-le explicite dans le déclencheur
• Écrivez à la troisième personne (injecté dans le prompt système)
• Ne résumez JAMAIS le processus ou le flux de travail de la compétence

# ❌ MAUVAIS : Trop abstrait, vague, n'inclut pas quand utiliser
description: Pour les tests asynchrones

# ❌ MAUVAIS : Première personne
description: Je peux vous aider avec les tests asynchrones quand ils sont instables

# ❌ MAUVAIS : Mentionne une technologie mais la compétence n'est pas spécifique à celle-ci
description: Utiliser quand les tests utilisent setTimeout/sleep et sont instables

# ✅ BON : Commence par "Utiliser quand", décrit le problème, pas de flux de travail
description: Utiliser quand les tests ont des conditions de course, des dépendances temporelles, ou réussissent/échouent de manière incohérente

# ✅ BON : Compétence spécifique à une technologie avec déclencheur explicite
description: Utiliser quand on utilise React Router et qu'on gère les redirections d'authentification

2. Couverture de Mots-Clés

Utilisez des mots qu'un agent rechercherait :

• Messages d'erreur : "Hook expiré", "ENOTEMPTY", "condition de course"
• Symptômes : "instable", "bloqué", "zombie", "pollution"
• Synonymes : "expiration/blocage/gel", "nettoyage/teardown/afterEach"
• Outils : Commandes réelles, noms de bibliothèques, types de fichiers

3. Nommage Descriptif

Utilisez la voix active, verbe en premier :

• ✅ creating-skills pas skill-creation
• ✅ condition-based-waiting pas async-test-helpers

4. Efficacité des Jetons (Cruciale)

Problème : Les compétences de prise en main et fréquemment référencées se chargent dans CHAQUE conversation. Chaque jeton compte.

Nombres de mots cibles :

• Flux de travail de prise en main : <150 mots chacun
• Compétences fréquemment chargées : <200 mots au total
• Autres compétences : <500 mots (soyez concis)

Techniques :

Déplacer les détails vers l'aide de l'outil :

# ❌ MAUVAIS : Documenter tous les drapeaux dans SKILL.md
search-conversations prend en charge --text, --both, --after DATE, --before DATE, --limit N

# ✅ BON : Référencer --help
search-conversations prend en charge plusieurs modes et filtres. Exécutez --help pour les détails.

Utiliser des références croisées :

# ❌ MAUVAIS : Répéter les détails du flux de travail
Lors de la recherche, dispatcher un sous-agent avec un modèle...
[20 lignes d'instructions répétées]

# ✅ BON : Référencer une autre compétence
Utilisez toujours des sous-agents (économie de 50 à 100 fois le contexte). OBLIGATOIRE : Utilisez [nom-autre-compétence] pour le flux de travail.

Compresser les exemples :

# ❌ MAUVAIS : Exemple verbeux (42 mots)
votre partenaire humain : "Comment avons-nous géré les erreurs d'authentification dans React Router avant ?"
Vous : Je vais rechercher les conversations passées pour les modèles d'authentification React Router.
[Dispatcher un sous-agent avec la requête de recherche : "gestion erreurs authentification React Router 401"]

# ✅ BON : Exemple minimal (20 mots)
Partenaire : "Comment avons-nous géré les erreurs d'authentification dans React Router ?"
Vous : Recherche...
[Dispatcher un sous-agent → synthèse]

Éliminer la redondance :

• Ne répétez pas ce qui se trouve dans les compétences référencées
• N'expliquez pas ce qui est évident d'après la commande
• N'incluez pas plusieurs exemples du même modèle

Vérification :

wc -w skills/path/SKILL.md
# Flux de travail de prise en main : visez <150 chacun
# Autres compétences fréquemment chargées : visez <200 au total

Nommez par ce que vous FAITES ou l'idée principale :

• ✅ condition-based-waiting > async-test-helpers
• ✅ using-skills pas skill-usage
• ✅ flatten-with-flags > data-structure-refactoring
• ✅ root-cause-tracing > debugging-techniques

Les gérondifs (-ing) fonctionnent bien pour les processus :

• creating-skills, testing-skills, debugging-with-logs
• Actifs, ils décrivent l'action que vous effectuez

5. Références Croisées à d'Autres Compétences

Lors de la rédaction d'une documentation qui référence d'autres compétences :

Utilisez uniquement le nom de la compétence, avec des marqueurs d'exigence explicites :

• ✅ Bon : **SOUS-COMPÉTENCE REQUISE :** Utilisez superpowers:test-driven-development
• ✅ Bon : **CONNAISSANCES REQUISES :** Vous DEVEZ comprendre superpowers:systematic-debugging
• ❌ Mauvais : Voir skills/testing/test-driven-development (pas clair si obligatoire)
• ❌ Mauvais : @skills/testing/test-driven-development/SKILL.md (charge forcée, consomme du contexte)

Pourquoi pas de liens @ : La syntaxe @ force le chargement immédiat des fichiers, consommant 200k+ de contexte avant que vous n'en ayez besoin.

Utilisation des Organigrammes

digraph when_flowchart {
    "Besoin d'afficher des informations ?" [shape=diamond];
    "Décision où je pourrais me tromper ?" [shape=diamond];
    "Utiliser le markdown" [shape=box];
    "Petit organigramme en ligne" [shape=box];

    "Besoin d'afficher des informations ?" -> "Décision où je pourrais me tromper ?" [label="oui"];
    "Décision où je pourrais me tromper ?" -> "Petit organigramme en ligne" [label="oui"];
    "Décision où je pourrais me tromper ?" -> "Utiliser le markdown" [label="non"];
}

Utilisez les organigrammes UNIQUEMENT pour :

• Points de décision non évidents
• Boucles de processus où vous pourriez vous arrêter trop tôt
• Décisions "Quand utiliser A vs B"

N'utilisez jamais les organigrammes pour :

• Du matériel de référence → Tableaux, listes
• Des exemples de code → Blocs Markdown
• Des instructions linéaires → Listes numérotées
• Des étiquettes sans signification sémantique (step1, helper2)

Consultez graphviz-conventions.dot dans ce répertoire pour les règles de style graphviz.

Visualisation pour votre partenaire humain : Utilisez render-graphs.js dans ce répertoire pour rendre les organigrammes d'une compétence en SVG :

node ./render-graphs.js ../une-competence           # Chaque diagramme séparément
node ./render-graphs.js ../une-competence --combine # Tous les diagrammes dans un seul SVG

Exemples de Code

Un excellent exemple vaut mieux que plusieurs médiocres

Choisissez le langage le plus pertinent :

• Techniques de test → TypeScript/JavaScript
• Débogage système → Shell/Python
• Traitement de données → Python

Bon exemple :

• Complet et exécutable
• Bien commenté expliquant POURQUOI
• Issu d'un scénario réel
• Montre clairement le modèle
• Prêt à être adapté (pas un modèle générique)

Ne faites pas :

• Implémenter dans 5+ langages
• Créer des modèles à remplir
• Écrire des exemples artificiels

Vous êtes doué pour le portage - un seul excellent exemple suffit.

Organisation des Fichiers

Compétence Autonome

defense-in-depth/
  SKILL.md    # Tout en ligne

Quand : Tout le contenu tient, aucune référence lourde nécessaire

Compétence avec Outil Réutilisable

condition-based-waiting/
  SKILL.md    # Aperçu + modèles
  example.ts  # Aides fonctionnelles à adapter

Quand : L'outil est un code réutilisable, pas seulement un récit

Compétence avec Référence Lourde

pptx/
  SKILL.md       # Aperçu + flux de travail
  pptxgenjs.md   # 600 lignes de référence API
  ooxml.md       # 500 lignes de structure XML
  scripts/       # Outils exécutables

Quand : Le matériel de référence est trop volumineux pour être en ligne

Invoquez les scripts fournis via leur interpréteur dans le texte (bash scripts/tool.sh, node scripts/tool.js), jamais par un chemin nu : certains packs de plugins de harnais suppriment les bits exécutables, et un scripts/tool.sh nu échoue là avec Permission denied.

La Loi de Fer (Comme en TDD)

PAS DE COMPÉTENCE SANS UN TEST ÉCHOUANT D'ABORD

Ceci s'applique aux NOUVELLES compétences ET aux MODIFICATIONS des compétences existantes.

Rédiger une compétence avant de tester ? Supprimez-la. Recommencez. Modifier une compétence sans tester ? Même violation.

Aucune exception :

• Pas pour "des ajouts simples"
• Pas pour "juste ajouter une section"
• Pas pour "des mises à jour de documentation"
• Ne conservez pas les modifications non testées comme "référence"
• Ne le faites pas.

…

[tronqué pour la traduction]