writing-skills

Vue d’ensemble de la compétence writing-skills

Ce que fait writing-skills

La compétence writing-skills est un guide de Skill Authoring pour créer, éditer et valider des compétences d’agent avec un workflow piloté par les tests. Son idée centrale est simple, mais assumée : traiter la rédaction de compétences comme du TDD appliqué à la documentation de processus. Au lieu de rédiger des conseils d’abord en espérant qu’ils fonctionnent, vous créez des scénarios de pression, observez les échecs sans la compétence, puis n’écrivez que les consignes qui modifient réellement le comportement.

À qui s’adresse writing-skills

writing-skills convient particulièrement aux personnes qui rédigent des compétences pour Claude Code, des environnements d’agent de type Codex, ou des répertoires de compétences locaux comparables. Il est particulièrement utile si vous créez des compétences destinées à imposer de la rigueur, des étapes de vérification ou des workflows que les agents risquent de sauter sous pression.

Le vrai besoin auquel répond writing-skills

La plupart des utilisateurs n’ont pas besoin d’« aide pour écrire du markdown ». Ils ont besoin d’une méthode reproductible pour produire un SKILL.md que les agents vont réellement découvrir, suivre, puis continuer à appliquer même lorsque la vitesse, l’excès de confiance ou le coût déjà engagé les poussent à ignorer le processus. writing-skills a été conçu pour ce problème.

Pourquoi writing-skills diffère d’un prompt générique

Un prompt générique peut aider à rédiger une compétence. writing-skills apporte une méthode pour démontrer que la compétence change réellement le comportement :

• définir des scénarios de pression
• exécuter des tests de base sans la compétence
• rédiger la documentation à partir des modes d’échec observés
• retester et refactorer pour fermer les échappatoires

Cela en fait un outil plus utile pour le Skill Authoring qu’une instruction ponctuelle du type « écris-moi une compétence ».

Prérequis importants et arbitrages

Le principal frein à l’adoption est que writing-skills part du principe que vous maîtrisez déjà le cadrage TDD du dépôt. La compétence exige explicitement une base dans superpowers:test-driven-development. Si vous sautez cette fondation, les conseils de rédaction peuvent sembler plus stricts que nécessaire ou inutilement centrés sur les tests.

L’arbitrage est lui aussi clair : ce workflow est plus lent qu’une rédaction à l’intuition, mais il est bien meilleur lorsque l’échec coûte cher ou lorsque les agents ont tendance à se trouver de bonnes raisons pour contourner la compétence.

Comment utiliser la compétence writing-skills

Contexte d’installation de writing-skills

Ce dépôt indique que les compétences personnelles vivent dans des répertoires propres à chaque agent, par exemple ~/.claude/skills pour Claude Code et ~/.agents/skills/ pour Codex. Si vous installez depuis le dépôt obra/superpowers avec un gestionnaire de compétences, vérifiez que la compétence aboutit bien dans le dossier réellement analysé par votre agent.

Si vous faites une revue manuelle avant installation, commencez ici :

• skills/writing-skills/SKILL.md
• skills/writing-skills/testing-skills-with-subagents.md
• skills/writing-skills/anthropic-best-practices.md
• skills/writing-skills/examples/CLAUDE_MD_TESTING.md

Fichiers à lire en priorité

Pour évaluer rapidement writing-skills, suivez cet ordre de lecture :

1. SKILL.md pour le workflow principal et le positionnement
2. testing-skills-with-subagents.md pour voir comment exécuter RED/GREEN/REFACTOR sur des compétences
3. anthropic-best-practices.md pour des conseils de rédaction concis
4. examples/CLAUDE_MD_TESTING.md pour des scénarios de pression réalistes
5. persuasion-principles.md si votre compétence doit résister à la rationalisation
6. graphviz-conventions.dot et render-graphs.js uniquement si vous voulez des diagrammes

Ce parcours apporte plus d’information qu’une simple lecture en diagonale du haut de SKILL.md.

Ce que writing-skills attend comme entrée

writing-skills fonctionne nettement mieux si vous apportez des éléments concrets, pas seulement un thème. Les bonnes entrées incluent :

• la compétence exacte que vous voulez créer ou réviser
• le comportement d’agent que vous voulez modifier
• des exemples d’échec sans la compétence
• les situations où l’agent est tenté de sauter le processus
• le répertoire cible et la plateforme où la compétence sera installée

Entrée faible : « Aide-moi à écrire une compétence de test. »

Entrée forte : « Crée une compétence qui impose une vérification avant déploiement pour les migrations de base de données. Aujourd’hui, les agents sautent les contrôles de rollback quand le correctif leur paraît évident. »

Transformer un objectif flou en prompt exploitable

Un bon schéma d’writing-skills usage consiste à demander les quatre éléments d’un coup :

1. scénarios de pression
2. attentes d’échec de base
3. structure de la compétence
4. plan de validation

Exemple :

Use writing-skills for Skill Authoring.

Goal: Create a skill for release-checklist enforcement in ~/.claude/skills/release-checks.
Observed failures: agents skip smoke tests when changes look small; they rationalize that CI is enough.
Need:
- 3 pressure scenarios that trigger those shortcuts
- baseline RED expectations without the skill
- a concise SKILL.md outline
- refactor ideas to close loopholes after first test run
Keep it concise and optimized for discoverability.

C’est beaucoup plus solide que de demander « une doc de compétence bien rédigée », car vous fournissez le modèle d’échec que la compétence doit corriger.

Workflow conseillé pour utiliser writing-skills

Dans la pratique, un bon workflow writing-skills ressemble à ceci :

1. Définir le comportement à imposer
2. Écrire 2 à 5 scénarios de pression
3. Tester l’agent sans la compétence
4. Capturer les rationalisations exactes et les raccourcis pris
5. Rédiger SKILL.md uniquement à partir de ces échecs
6. Retester avec la compétence chargée
7. Durcir la formulation là où l’agent dévie encore
8. Supprimer toute explication qui n’a pas amélioré la conformité

La dernière étape compte, car les bonnes pratiques incluses dans le dépôt insistent sur l’efficacité en tokens et sur des consignes concises.

Quand la méthode pilotée par les tests compte le plus

Utilisez writing-skills for Skill Authoring lorsque la compétence a un coût de conformité :

• tests supplémentaires
• vérification plus lente
• contrôles documentaires
• exigences de redémarrage ou de reprise
• règles qui vont à l’encontre des incitations à aller vite

Cette méthode est moins décisive pour des compétences de pure référence, comme des fiches mémo de syntaxe API, où les agents ont peu de raisons de contourner le contenu.

Comment exploiter la référence de test avec subagents

testing-skills-with-subagents.md est le document compagnon le plus pratique. Il aide à vérifier si votre compétence tient sous une vraie pression au lieu de simplement sembler correcte dans des conditions calmes. Lisez-le lorsque vous avez besoin de :

• formats de scénarios
• correspondance RED/GREEN/REFACTOR
• capture des rationalisations
• exemples de non-conformité induite par la pression

Si votre premier draft semble correct mais que l’adoption reste faible, ce fichier est souvent le chemin le plus rapide vers une amélioration.

Utiliser les scénarios d’exemple sans les copier aveuglément

examples/CLAUDE_MD_TESTING.md est utile parce qu’il montre à quoi ressemblent réellement des scénarios de pression : contrainte de temps, coût déjà engagé, effet d’autorité et biais de familiarité. L’erreur consiste à reprendre ces scénarios tels quels pour des compétences sans rapport.

À la place, adaptez le type de pression à votre propre workflow. Par exemple :

• compétence de déploiement → urgence et peur du rollback
• compétence de revue → excès de confiance et biais de vitesse
• compétence de sécurité → rationalisation du type « juste cette fois »
• compétence de style → coût d’adoption faible, donc tests plus légers

Comment les principes de persuasion s’intègrent au workflow

persuasion-principles.md n’est pas là pour faire joli ; ce fichier existe parce que certaines compétences échouent même lorsque le processus est clair. Si votre compétence doit imposer un comportement auquel les agents résistent souvent, une formulation plus forte peut aider. Le fichier propose des schémas concrets comme l’autorité, l’engagement et les annonces explicites.

À utiliser avec discernement. Le but n’est pas de rendre la compétence plus bruyante, mais de rendre les actions requises plus difficiles à écarter par rationalisation.

Règles de concision qui influent sur la qualité du résultat

L’un des apports les plus précieux de ce dépôt est le rappel que les compétences partagent un budget de contexte. writing-skills ne vous dit pas d’écrire davantage ; il vous dit d’écrire uniquement ce qui change le comportement.

Bons signaux :

• déclencheurs concrets
• actions obligatoires formulées clairement
• exemples courts liés à un échec réel
• minimum de contexte

Mauvais signaux :

• longs développements motivationnels
• définitions répétées
• historique du processus
• « bonnes pratiques » génériques que Claude connaît déjà

Outillage graphique facultatif

Le répertoire de compétences inclut render-graphs.js, qui extrait les blocs dot depuis SKILL.md et génère des diagrammes SVG si graphviz est installé. C’est optionnel, et surtout utile lorsque votre workflow comporte des états divergents ou des points de contrôle que des humains doivent inspecter visuellement. Ce n’est pas nécessaire pour utiliser la compétence writing-skills, mais cela peut aider les mainteneurs à diagnostiquer une complexité de processus.

FAQ sur la compétence writing-skills

writing-skills vaut-il le coup si je sais déjà écrire des prompts ?

Oui, si votre problème porte sur la fiabilité plutôt que sur la vitesse de rédaction. Des prompts classiques peuvent générer rapidement une compétence qui a l’air correcte. writing-skills devient utile lorsque vous avez besoin d’être sûr que la compétence finale modifie réellement le comportement de l’agent sous pression.

writing-skills est-il adapté aux débutants ?

En partie. La rédaction elle-même est accessible, mais la méthode suppose une certaine aisance avec un raisonnement de type TDD. Les nouveaux utilisateurs du Skill Authoring devront souvent lire d’abord les ressources du dépôt liées au TDD, faute de quoi ils risquent de prendre ce workflow pour un formalisme inutile.

Dans quels cas writing-skills est-il un mauvais choix ?

Évitez writing-skills pour :

• des compétences simples de référence uniquement
• des notes ponctuelles qui n’ont pas vocation à être réutilisées
• des sujets où il n’existe pas de tentation réaliste de contourner les consignes
• des situations où vous ne pouvez exécuter aucun test avant/après

Dans ces cas-là, un workflow de rédaction plus léger suffit souvent.

En quoi writing-skills diffère-t-il des bonnes pratiques de compétences d’Anthropic ?

Le fichier inclus anthropic-best-practices.md met l’accent sur une rédaction de compétences concise, facile à découvrir et économe en contexte. writing-skills ajoute une logique plus orientée changement de comportement : observer les échecs d’abord, puis n’écrire que ce qui les corrige. Les deux approches sont complémentaires, pas concurrentes.

writing-skills nécessite-t-il des outils supplémentaires du dépôt ?

Non, aucun outillage important n’est nécessaire pour tirer parti de la méthode. Les consignes de test et les exemples sont les ressources clés. Le rendu de graphes est facultatif, et aucun script de support n’est requis pour le workflow principal de rédaction.

Puis-je utiliser writing-skills pour modifier une compétence existante ?

Oui. C’est même l’un des meilleurs cas d’usage. Si une compétence existe déjà mais que les agents l’ignorent encore ou l’utilisent mal, writing-skills vous aide à identifier le mode d’échec réel, à supprimer le contenu inutile et à réécrire les instructions qui comptent vraiment.

Comment améliorer la compétence writing-skills

Partir des échecs observés, pas de la documentation idéale

Le moyen le plus rapide d’améliorer les résultats avec writing-skills est d’apporter des preuves d’échec. Si vous décrivez seulement le processus idéal, le résultat a tendance à devenir générique. Si vous fournissez les raccourcis réellement pris par les agents, la compétence obtenue devient plus précise et plus courte.

Fournir des scénarios de pression plus solides

De bons scénarios créent une vraie tentation de contourner la compétence. Incluez :

• pression temporelle
• confiance liée à une expérience passée
• coût déjà engagé
• pression d’autorité venant d’un humain
• cadrage du type « le correctif est évident »

Ce sont ces conditions qui révèlent où vos instructions sont trop molles ou trop vagues.

Capturer les rationalisations exactes de l’agent

Ne résumez pas l’échec par « a ignoré la compétence ». Notez ce que l’agent a réellement dit ou laissé entendre :

• « This is a small change »
• « CI will catch it »
• « I already know this pattern »
• « Reading the skill would take too long »

Ces rationalisations vous indiquent ce que votre prompt révisé d’writing-skills usage et la formulation finale de la compétence doivent traiter explicitement.

Durcir la formulation là où la conformité compte

Si la compétence est censée imposer un comportement non optionnel, une formulation vague nuit au résultat. Remplacez les suggestions floues par des déclencheurs explicites et des actions obligatoires. Le guide de persuasion aide ici, mais l’amélioration principale vient de la précision :

• quand charger la compétence
• quoi faire en premier
• ce qui ne peut pas être sauté
• ce qui compte comme réussite

Supprimer ce qui ne change pas le comportement

Un mode d’échec fréquent dans le résultat produit par la compétence writing-skills est la sur-explication. Si un paragraphe n’aide ni la découvrabilité, ni la conformité, ni les tests, supprimez-le. Le fichier de bonnes pratiques du dépôt en fait une règle centrale pour une bonne raison.

Itérer après le premier résultat positif

Un premier passage en “GREEN” ne suffit pas si la compétence ne fonctionne que dans des conditions faciles. Retestez avec des prompts plus durs et des formulations alternatives. Demandez-vous si la compétence fonctionne encore quand l’agent est pressé, sûr de lui ou cherche à préserver un travail déjà terminé.

Associer writing-skills à un exemple propre au dépôt

Si votre équipe a un workflow récurrent, ajoutez un exemple concret dans le domaine visé par la compétence. Cela améliore souvent davantage l’adoption que l’ajout de règles abstraites supplémentaires. Gardez l’exemple court et éprouvé sous pression, pas encyclopédique.

Améliorer les prompts en demandant une structure, pas du vernis

Quand vous invoquez writing-skills, demandez :

• une liste de scénarios
• une analyse des échecs
• un plan de compétence concis
• des modifications pour fermer les échappatoires

N’ouvrez pas avec « rends-le plus soigné » ou « rends-le complet ». Cela augmente généralement la longueur sans améliorer la conformité.

Vérifier si la compétence doit exister tout court

L’un des apports utiles du guide writing-skills guide est de montrer que certains sujets n’ont tout simplement pas besoin de compétence. Si le processus est évident, peu risqué ou rarement répété, une compétence peut ajouter un coût de maintenance sans bénéfice comportemental suffisant. C’est une conclusion valable, et elle améliore la qualité du dépôt.

Utiliser writing-skills pour refactorer, pas seulement créer

L’usage le plus précieux de writing-skills consiste souvent à refactorer une compétence existante après l’avoir vue échouer. La méthode cesse alors d’être un simple exercice de rédaction documentaire pour devenir une démarche d’ingénierie du comportement — et c’est là que ce dépôt apporte sa valeur la plus concrète.