Écrire des skills efficaces pour un agent de code

Pourquoi des skills

Les instructions projet (CLAUDE.md, AGENTS.md) sont chargées à chaque session. Y mettre toutes les procédures de l’équipe les rendrait longues, coûteuses en jetons, et noierait les règles importantes.

Un skill est un dossier de savoir-faire que l’agent ne charge que lorsqu’il en a besoin : une procédure de déploiement, des conventions SQL, la façon de rédiger un article. Seuls son nom et sa description sont présents en permanence ; le reste arrive à la demande.

Structure d’un skill

.claude/skills/
└── deploiement-salesforce/
    ├── SKILL.md              # obligatoire : frontmatter + procédure
    ├── checklist.md          # annexe, lue seulement si la procédure y renvoie
    └── scripts/
        └── verifier-tests.sh # script exécuté, jamais chargé dans le contexte

Le fichier SKILL.md commence par un en-tête YAML avec deux champs essentiels : name (identifiant court, en minuscules et tirets) et description. Le corps décrit la procédure en Markdown. Les annexes et scripts sont facultatifs.

La description, ce qui déclenche

L’agent décide de charger un skill en lisant sa seule description. C’est donc la ligne la plus importante du fichier. Une bonne description dit :

• ce que fait le skill, avec les mots que l’utilisateur emploiera (« déployer », « quick deploy », « valider ») ;
• quand l’utiliser, explicitement ;
• quand ne pas l’utiliser, si un skill voisin risque d’être confondu.

« Aide pour Salesforce » ne se déclenchera jamais au bon moment. « Déployer les métadonnées vers une sandbox ou la production… Utiliser pour toute demande de déploiement » se déclenchera.

Chargement progressif

Un skill bien conçu se lit en trois niveaux :

1. Nom et description : toujours visibles, quelques dizaines de jetons.
2. Corps du SKILL.md : chargé quand le skill est choisi. Le garder court, centré sur les règles et la procédure.
3. Annexes et scripts : une annexe n’est lue que si le corps y renvoie (« en cas d’échec, lire checklist.md ») ; un script est exécuté, et seul son résultat entre dans le contexte.

Un script est préférable à une procédure en prose dès que l’étape est mécanique : il est déterministe, testé, et ne consomme presque pas de contexte.

Exemple complet

Un skill de déploiement pour une organisation fictive, Acme Assurances :

---
name: deploiement-salesforce
description: Déployer les métadonnées Salesforce d'Acme Assurances vers une sandbox ou la production
  (validation, tests Apex, déploiement rapide). Utiliser pour toute demande de déploiement, de
  validation de package ou de quick deploy. Ne pas utiliser pour un simple commit.
---

# Déploiement Salesforce

## Règles
- Jamais de déploiement en production sans validation préalable réussie et accord explicite.
- Niveau de tests en production : RunLocalTests.

## Procédure
1. Vérifier l'org cible : `sf org display --target-org <alias>`.
2. Valider sans déployer :
   `sf project deploy validate --manifest manifest/package.xml --test-level RunLocalTests --target-org <alias>`
3. Lancer `scripts/verifier-tests.sh <id-de-validation>` : il échoue si la couverture est sous 75 %.
4. Si la validation est réussie et l'utilisateur confirme :
   `sf project deploy quick --job-id <id-de-validation> --target-org <alias>`

## En cas d'échec
Lire `checklist.md` (erreurs fréquentes : dépendances manquantes, profils, tests instables).

Les règles critiques (« jamais en production sans accord ») sont en tête. Elles peuvent aussi être imposées par un hook, pour ne pas dépendre de la lecture du skill.

Erreurs fréquentes

• Un skill fourre-tout : un sujet par skill. Deux procédures distinctes font deux skills, avec des descriptions qui se distinguent.
• Une procédure qui raconte : écrire des étapes et des commandes exactes, pas un historique de décisions. Le « pourquoi » tient en une phrase à côté de la règle.
• Des informations dupliquées : une règle vit à un seul endroit ; les autres fichiers y renvoient. Sinon, les copies divergent.
• Un skill jamais testé : demander à l’agent une tâche réaliste, sans citer le skill, et vérifier qu’il le charge et suit la procédure.
• Un skill obsolète : le mettre à jour dans le même commit que le comportement qu’il décrit.