Création de compétence (skill authoring)

Que fait Création de compétence (skill authoring) ?

Guide pour créer une compétence qui change réellement le comportement de l'agent, pas un document que personne ne lit.

Principe fondamental : une compétence est une instruction opérationnelle, pas un article. Si l'agent ne fait rien de différent après avoir chargé cette compétence, celle-ci a échoué.

Comment utiliser cette compétence

Cette compétence s'utilise par conversation, pas en une seule fois. Le déroulement :

1. L'utilisateur déclenche la compétence (exemple : "utilise la compétence skill-authoring, je veux créer une compétence pour mon agent").
2. L'agent arrête d'écrire et commence l'entretien de l'Étape 1 : une question à la fois, en attendant la réponse.
3. Une fois les cinq questions répondues, l'agent exécute les Étapes 2 à 5 et montre le brouillon à l'utilisateur.
4. Après accord de l'utilisateur, l'agent écrit le fichier (Étape 6), puis exécute le test de déclenchement (Étape 7) et la checklist (Étape 8).

Règles pour l'agent :

• N'écris pas le fichier SKILL.md avant que les cinq questions de l'Étape 1 aient reçu une réponse. Un brouillon prématuré stoppe l'entretien.
• Ne pose pas les cinq questions en même temps. Une par tour, avec un court exemple pour chaque question.
• Si l'utilisateur veut seulement "un exemple rapide", pose uniquement les questions 1 et 4, puis continue.
• Mentionne dès le début que le résultat final est un seul fichier SKILL.md prêt à l'emploi.

Quand cette compétence est active

• L'utilisateur dit "créer une compétence", "fabriquer une compétence", "comment créer une compétence", "une compétence pour mon agent".
• L'utilisateur a une idée de capacité pour son agent mais ne sait pas comment la formaliser.
• Une compétence existante ne se déclenche jamais ou n'est pas suivie par l'agent.
• Il faut décider : cela doit-il être une compétence, un agent, une commande ou un hook ?

Pour chercher une compétence existante, utilise d'abord skill-scout. Pour auditer un empilement de compétences, utilise skill-stocktake.

Étape 0 – Règles de base avant d'écrire

Une bonne compétence possède quatre propriétés :

Propriété	Signification
Spécifique	Répond à un seul type de travail, pas à "tout ce qui concerne le back-end"
Opérationnelle	Contient des étapes, des commandes, des exemples concrets, pas de la théorie
Déclenchable	La description contient les mots réellement utilisés par l'utilisateur
Limité	Moins de 500 lignes ; idéalement 100 à 250 lignes

Si l'idée de la compétence ne respecte pas ces quatre critères, commence par améliorer l'idée, n'écris pas le fichier.

Étape 1 – Capture le vrai problème, pas une fonctionnalité

Ne pars pas de "une compétence pour le test". Pars d'un échec concret.

Pose ces cinq questions à l'utilisateur (une par une, pas en même temps) :

1. Qu'est-ce que l'agent fait de mal ou de façon incohérente en ce moment ? Donne un exemple concret.
2. Quand cela se produit-il ? (écriture de code, revue de PR, déploiement, réponse à l'utilisateur, analyse de données)
3. À quoi ressemble un bon résultat ? Montre un exemple de sortie que l'utilisateur juge satisfaisante.
4. Quelles informations l'agent ne connaît pas et doit apprendre via cette compétence ? (conventions d'équipe, ordre des étapes, pièges)
5. Qu'est-ce que l'agent ne doit pas faire lorsqu'il exécute cette compétence ?

Les réponses aux questions 4 et 5 constituent le contenu réel de la compétence. Les réponses aux questions 1 et 2 constituent la description.

Si l'utilisateur ne peut pas répondre à la question 1, arrête le processus. Il n'y a pas de compétence à créer – seulement un souhait. Dis-le-lui.

Étape 2 – Choisis la forme appropriée

Ne transforme pas tout en compétence. Choisis la forme la plus économique qui résout le problème.

Besoin	Forme	Raison
Connaissances/conventions utilisées régulièrement lors de l'écriture de code	Compétence	Chargée automatiquement, pas besoin de l'appeler
Tâche autonome en plusieurs étapes avec contexte séparé	Agent	Peut être exécutée en parallèle, a son propre contexte
Action que l'utilisateur déclenche consciemment avec des arguments	Commande	/{nom} explicite, pas automatique
Comportement automatique sur un événement (avant commit, après édition)	Hook	S'exécute sans décision du modèle
Règle courte qui s'applique à toutes les tâches	Règle	Toujours active, sans déclencheur
Explication longue destinée à être lue par un humain	Document	Pas besoin d'être chargé par l'agent

Règle empirique :

• Besoin d'un déclencheur ? Compétence.
• Besoin d'un contexte séparé ou d'outils limités ? Agent.
• Besoin d'être appelée manuellement avec des paramètres ? Commande.
• Besoin de s'exécuter sans être demandée ? Hook.
• Besoin d'être toujours vraie, jamais violée ? Règle.
• Besoin d'être lue par un humain, pas par un agent ? Document.

En cas de doute entre compétence et règle : si le contenu fait moins de 10 lignes et s'applique partout, c'est une règle.

Étape 3 – Vérifie les doublons d'abord

Avant d'écrire, cherche d'abord. Le dossier des compétences varie selon le harnais – adapte-le à celui de l'utilisateur :

Harnais	Dossier des compétences
Claude Code	~/.claude/skills/ ou .claude/skills/ dans le projet
OpenCode	~/.config/opencode/skills/ ou .opencode/skills/
Cursor	.cursor/skills/
Codex	.agents/skills/

# compétences déjà installées (remplace <dossier-competences> selon le tableau ci-dessus)
grep -ril "mots-clés" <dossier-competences> --include=SKILL.md

# si vous êtes dans un dépôt qui contient un dossier skills/
grep -ril "mots-clés" skills --include=SKILL.md

Si l'utilisateur ne connaît pas son dossier de compétences, explique le tableau ci-dessus et demande-lui de choisir le harnais qu'il utilise. Ne devine pas.

S'il existe déjà un équivalent proche, choisis : l'utiliser tel quel, l'étendre, ou en créer une nouvelle. Des compétences en double rendent l'agent confus et alourdissent le contexte.

Étape 4 – Rédige la description (la partie la plus cruciale)

La description est la seule partie que l'agent lit pour décider de charger ou non la compétence. Une erreur ici et la compétence est morte.

Formule :

[activité réalisée] + [contexte déclencheur] + [mots-clés utilisés par l'utilisateur] + [quand NE PAS l'utiliser]

Exemple mauvais :

description: Aide pour les tests

Exemple bon :

description: Modèles de test React avec Vitest et Testing Library - rendu, événements utilisateur, simulation réseau et assertions d'accessibilité. À utiliser lors de l'écriture ou de la correction de tests de composants React. Pas pour les tests E2E (utiliser e2e-testing).

Règles :

• Mentionne les mots réellement tapés par l'utilisateur, pas des termes internes.
• Mentionne les limites pour que la compétence n'empiète pas sur le travail d'une autre.
• Une seule ligne, sans saut de ligne à l'intérieur de la chaîne.
• Évite les mots génériques uniques comme "code", "aide", "divers".

Test rapide : ferme le fichier, lis seulement la description. Si toi, en tant qu'agent, tu ne sais pas exactement quand la charger, réécris-la.

Étape 5 – Structure le contenu

Ordre des sections qui a fait ses preuves :

---
name: nom-de-la-competence
description: <formule de l'Étape 4>
metadata:
  origin: ECC
---

# Titre

Un paragraphe : ce que cette compétence change dans le comportement de l'agent.

## Quand c'est actif
Liste de déclencheurs concrets.

## Cœur
Étapes de travail, tableau de décision ou règles. Cela constitue 70 % du contenu de la compétence.

## Exemples
Un exemple erroné, un exemple correct. Concrets, pas des espaces réservés.

## Anti-patrons
Erreurs à éviter, avec une brève justification.

## Checklist
Cases à cocher vérifiables.

## Compétences liées
Deux à quatre noms de compétences.

Règles d'écriture du contenu :

• Phrases impératives ("Fais X"), pas de descriptions passives ("X peut être fait").
• Tableaux pour les décisions, listes numérotées pour les étapes, blocs de code pour les commandes.
• Chaque règle doit être vérifiable – "écris du code propre" ne l'est pas, "chaque fonction fait au maximum 50 lignes" l'est.
• Pas d'espaces réservés comme [insérer ici], TODO, ou ... dans les parties exécutées par l'agent.
• Pas d'identité de produit externe copiée textuellement – prends l'idée, réécris-la dans son propre contexte.
• Pas de secrets : clés API, jetons, chemins privés absolus, noms internes d'entreprise.

Limite de longueur : 500 lignes (maximum absolu 800). Si c'est plus long, divise en deux compétences ou déplace les détails dans references/ dans le même dossier de compétence.

Étape 6 – Écris le fichier

Avant d'écrire, pose deux dernières questions :

1. Langue de la compétence – la langue que l'utilisateur utilise quotidiennement, ou l'anglais pour la portabilité ? Suis la réponse, ne choisis pas arbitrairement.
2. Nom du dossier – propose un nom en kebab-case descriptif (exemple : test-composants-react), demande l'approbation.

Puis écris dans <dossier-competences>/<nom>/SKILL.md. Règles à ne pas enfreindre :

• Le champ name: dans l'en-tête doit être exactement identique au nom du dossier. Sans cela, certains harnais refusent de charger la compétence.
• Montre le brouillon complet à l'utilisateur d'abord, puis enregistre. N'enregistre pas en cachette.
• Pas d'espaces réservés (TODO, [insérer ici], ...) dans les parties qui seront exécutées par l'agent.
• Après l'enregistrement, signale le chemin complet et une phrase pour déclencher : "Ensuite, demande à l'agent d'utiliser la compétence <nom> quand <déclencheur>."

Étape 7 – Teste avant utilisation

Trois tests minimaux. N'en saute aucun.

Test 1 – Déclenchement positif (activation) Donne à l'agent une tâche qui devrait déclencher cette compétence, sans mentionner le nom de la compétence.

"Peux-tu écrire un test pour le composant LoginButton ?"

Réussi si la compétence est chargée. Échoué si la description manque de mots-clés.

Test 2 – Déclenchement négatif (pas d'activation) Donne une tâche similaire mais hors de son domaine.

"Peux-tu écrire un test E2E pour le flux de connexion ?"

Réussi si la compétence N'EST PAS chargée (ou si l'agent choisit une autre compétence appropriée). Échoué si la description est trop large.

Test 3 – Exécution Demande à l'agent d'effectuer une tâche qui déclenche réellement la compétence, puis compare la sortie avec et sans la compétence.

Sans compétence : l'agent écrit un test style X
Avec compétence : l'agent écrit un test style Y (conforme aux conventions d'équipe)

Réussi s'il y a une différence de comportement démontrable. Si la sortie est identique, la compétence est inutile – supprime-la ou fusionne-la.

Étape 8 – Checklist prêt à livrer

• Le fichier se trouve dans <dossier-competences>/{nom}/SKILL.md, et name: est exactement identique au nom du dossier
• La description tient en une ligne, contient les mots-clés de l'utilisateur et les limites du périmètre
• La description n'utilise pas de bloc littéral (|), seulement une chaîne sur une ligne
• Il y a une section "Quand c'est actif" explicite
• Chaque règle est vérifiable, pas de "écris du bon code"
• Il y a au moins un exemple erroné et un exemple correct
• Il y a des anti-patrons
• Moins de 500 lignes
• Pas de secret, jeton ou chemin privé absolu
• Les tests 1, 2 et 3 ont été exécutés et leurs résultats notés
• L'Étape 3 a été exécutée, pas de doublon
• Mentionne 2 à 4 compétences liées dans la section finale

Validation automatique seulement si disponible dans le dépôt de l'utilisateur :

# ECC / dépôt avec validateur de compétences
node scripts/ci/validate-skills.js

S'il n'y a pas de validateur, vérifie manuellement les quatre points les plus souvent échoués : name: correspond au dossier, description sur une seule ligne, moins de 500 lignes, et pas d'espaces réservés. Mentionne à l'utilisateur que cette vérification manuelle est utilisée.

Modèle prêt à l'emploi

---
name: nom-de-la-competence
description: <activité> - <périmètre>. À utiliser quand <déclencheur concret>. Pas pour <hors périmètre>.
metadata:
  origin: ECC
---

# Nom de la compétence

Ce qui change dans le comportement de l'agent après le chargement de cette compétence.

## Quand c'est actif
- <déclencheur 1>
- <déclencheur 2>

## Étapes
1. <première étape directement exécutable>
2. <deuxième étape>
3. <vérification>

## Exemples
Erroné : <code ou réponse qui apparaît souvent>
Correct : <version souhaitée, avec brève justification>

## Anti-patrons
- <erreur> - <pourquoi c'est mauvais>

## Checklist
- [ ] <ce qui peut être vérifié par machine ou à l'œil>

## Compétences liées
- `<competence-a>`, `<competence-b>`

Anti-patrons de création

• Compétence sans déclencheur. description vague, la compétence n'est jamais chargée. C'est la cause d'échec la plus courante.
• Compétence mur de texte. 900 lignes de théorie sans une seule commande. L'agent la charge puis l'ignore.
• Compétence "sois utile". Sans connaissance spécifique, le résultat est identique à celui sans compétence.
• Compétence en double. Deux compétences revendiquent le même domaine ; l'agent choisit au hasard.
• Copier textuellement la compétence de quelqu'un d'autre. Y compris les instructions cachées et les dépendances dont tu n'as pas conscience.
• Compétence avec secret ou chemin privé. Se propage lorsque la compétence est partagée.
• Écrire une compétence pour un seul événement. Si elle n'est utilisée qu'une fois, ce n'est pas une compétence – c'est une documentation ou une commande.
• Créer une compétence sans chercher d'abord. Exécute toujours l'Étape 3.

Quand il ne faut PAS créer de compétence

Dis-le franchement à l'utilisateur si l'un de ces cas s'applique :

• Le problème est un bug dans le code, pas un manque de connaissance de l'agent.
• Il suffit de l'exécuter une seule fois – donne une instruction directe.
• Le contenu fait moins de 10 lignes de règles générales – c'est une règle.
• Il suffit de l'ajouter dans AGENTS.md ou CLAUDE.md du projet.
• Il existe déjà une compétence qui couvre 80 % du besoin – étends celle qui existe.

Compétences liées

• skill-scout – cherche les compétences existantes avant d'en créer de nouvelles
• skill-stocktake – audite la qualité des compétences qui s'accumulent
• skill-comply – mesure si les compétences sont réellement suivies par l'agent
• agent-harness-construction – conçoit les outils et les limites d'action de l'agent