L'Art de Créer des Skills pour Agents IA : Guide Complet

Qu’est-ce qu’un Skill pour Agent IA ?

Un skill (compétence) est un fichier d’instructions markdown (SKILL.md) que les agents IA comme Claude Code ou OpenCode chargent dans leur contexte pour exécuter des tâches spécialisées. Contrairement à un simple prompt, un skill est persistant, structuré et réutilisable.

Skill vs Tool : la distinction fondamentale

Aspect	Tool	Skill
Nature	Fonction atomique (API call, lecture fichier)	Workflow orchestré (séquence d’actions)
Format	Code Python/JS avec schéma JSON	Fichier SKILL.md + ressources optionnelles
Granularité	Une action précise	Une capacité métier complète
Exemple	read_file(), bash()	”Créer un composant React”, “Review de sécurité”

Règle d’or — Un skill orchestre des tools. Ne jamais confondre l’action atomique avec le processus complet.

---

Anatomie d’un Skill

Structure minimale

skill-name/
├── SKILL.md              # Instructions principales (requis)
└── Bundled Resources     # Optionnel
    ├── scripts/          # Code exécutable pour tâches répétitives
    ├── references/       # Documentation chargée selon le contexte
    └── assets/           # Templates, icônes, polices

Le fichier SKILL.md

---
name: security-review
description: Security code review for vulnerabilities. Use when asked to "security review", "find vulnerabilities", "check for security issues", "audit security", "OWASP review".
---

# Security Review

## Workflow

1. Identify the attack surface
2. Check for injection vulnerabilities
3. Review authentication and authorization
4. Report findings in the table format below

Les trois éléments critiques :

1. name — Identifiant unique (doit matcher le nom du dossier)
2. description — Le seul mécanisme de déclenchement. C’est ce que l’agent lit pour décider d’activer le skill.
3. Le corps — Instructions impératives, concises, actionnables.

---

Les 5 Principes du Design de Skills

1. Concision : chaque ligne compte

Le contexte window est partagé entre les instructions du skill et la tâche de l’utilisateur. N’incluez que ce que l’agent ne sait pas déjà.

À inclure :

• Connaissances domaine spécifiques
• Logique de décision non évidente
• Formats de sortie requis
• Exemples concrets

À omettre :

• Connaissances générales de programmation
• Comment utiliser les outils standards (Read, Grep, Bash)
• Instructions vagues (“soyez thorough”, “vérifiez les erreurs”)

Règle — Si un ingénieur senior skipperait la lecture, l’agent n’en a pas besoin non plus.

2. Progressive Disclosure

Structurez en trois niveaux de chargement :

Niveau	Contenu	Quand chargé	Taille cible
Metadata	name + description	Toujours (dans le system prompt)	~100 mots
Instructions	Corps du SKILL.md	Quand le skill se déclenche	<500 lignes
Ressources	Fichiers references/	Sur demande conditionnelle	Illimité

## Étape 3 : Charger le guide langage

| Extension | Lire cette référence |
|-----------|---------------------|
| `.py`     | `references/python.md` |
| `.js`     | `references/javascript.md` |

3. La description comme trigger

La description est le seul mécanisme de déclenchement. Elle doit contenir les phrases que les utilisateurs disent réellement.

Écrire à la troisième personne :

# ✅ Bon — troisième personne
description: Processes Excel files and generates reports. Use when working with spreadsheets.

# ❌ Mauvais — première personne
description: I can help you process Excel files.

# ❌ Mauvais — deuxième personne
description: You can use this to process Excel files.

Pattern efficace :

description: <Ce que fait le skill>. Use when <phrases de trigger réalistes>. <Capacités clés>.

Exemples concrets :

# Bon — inclut des trigger phrases naturelles
description: Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history.

# Bon — inclut des verbes d'action et termes domaine
description: Security code review for vulnerabilities. Use when asked to "security review", "find vulnerabilities", "check for security issues", "audit security", "OWASP review".

# Mauvais — trop vague, pas de trigger phrases
description: A helpful skill for code quality.

# Mauvais — décrit l'interne, pas quand l'utiliser
description: Runs a Python script that parses AST and generates reports.

4. Voix impérative

Les skills sont des instructions pour un agent, pas de la documentation pour des humains.

Impératif (correct)	Descriptif (à éviter)
Read the diff and identify changes	This skill reads the diff and identifies changes
Report findings in the table format below	Findings should be reported in the table format below
Ask the user before making destructive changes	The agent may want to ask the user before making changes

5. Terminologie cohérente

Choisissez un terme par concept et utilisez-le partout. L’incohérence crée de l’ambiguïté.

✅ Faire	❌ Éviter
”API endpoint” partout	”API endpoint”, “URL”, “API route”, “path"
"field” partout	”field”, “box”, “element”, “control"
"extract” partout	”extract”, “pull”, “get”, “retrieve”

---

Patterns Architecturaux

Pattern 1 : Simple (SKILL.md seul)

Quand tout tient dans ~200 lignes sans ressources externes.

brand-guidelines/
└── SKILL.md

Caractéristiques :

• Frontmatter avec name et description uniquement
• Corps organisé en sections ##
• Tables pour logique de décision et exemples
• Pas de références externes

Quand l’utiliser : Le skill fournit un ensemble de règles cohérent ou un workflow procédural court.

Pattern 2 : Workflow (SKILL.md + Scripts)

Quand le skill automatise un workflow multi-étapes avec traitement de données structurées.

iterate-pr/
├── SKILL.md
└── scripts/
    ├── fetch_pr_checks.py
    └── fetch_pr_feedback.py

Caractéristiques :

• SKILL.md documente l’interface de chaque script (arguments, schéma JSON de sortie)
• Scripts utilisent PEP 723 pour les dépendances inline
• Scripts retournent du JSON structuré
• Scripts gèrent les erreurs explicitement
• SKILL.md inclut une section fallback

Quand l’utiliser : Le workflow bénéficie d’extraction de données structurées, d’appels API, ou de processing fragile en bash inline.

Pattern 3 : Domain Expert (SKILL.md + References)

Quand le skill couvre un domaine large avec chargement conditionnel.

security-review/
├── SKILL.md
├── references/
│   ├── injection.md
│   ├── xss.md
│   ├── authentication.md
│   └── ... (17 fichiers)
└── infrastructure/
    ├── docker.md
    └── kubernetes.md

Caractéristiques :

• SKILL.md contient le workflow core et tables de référence rapide
• Fichiers de référence chargés conditionnellement selon le contexte détecté
• Chaque fichier est autonome et focalisé sur un sujet
• SKILL.md inclut un index de fichiers
• Références à un seul niveau de profondeur

Quand l’utiliser : Le domaine est trop large pour un seul fichier, mais l’agent n’a besoin que d’un sous-ensemble pour chaque tâche.

---

Anti-Patterns à Éviter

SKILL.md trop long

Problème : Le fichier dépasse 500 lignes, consommant trop de contexte.

Solution : Extraire le matériel de référence dans references/. Garder SKILL.md focalisé sur le workflow procédural.

Triggers manquants dans la description

Problème : “A skill for helping with code” — l’agent ne peut pas matcher ça avec “review my PR”.

Solution : Inclure les phrases réelles : Use when asked to "review code", "find bugs", "check for issues".

Info de trigger dans le corps au lieu de la description

Problème : Le corps inclut une section “When to Use This Skill”, mais la description est vague. Le corps n’est chargé qu’après le déclenchement.

Solution : Déplacer tout le “quand utiliser” dans le champ description.

Duplication de CLAUDE.md

Problème : SKILL.md répète les conventions du repo déjà dans CLAUDE.md.

Solution : Référencer CLAUDE.md : “Follow the commit conventions in CLAUDE.md” au lieu de copier le format entier.

Chargement inconditionnel de références

Problème : “Read all reference files before starting” — charge 20+ fichiers dans le contexte.

Solution : Utiliser une table de décision pour charger uniquement les références pertinentes.

Scripts sans documentation

Problème : SKILL.md dit uv run <skill-dir>/scripts/tool.py mais ne documente pas les arguments.

Solution : Documenter l’interface de chaque script dans SKILL.md :

### `scripts/tool.py`
Fetches X and returns structured data.

uv run <skill-dir>/scripts/tool.py --flag VALUE

Returns JSON:
{"key": "value", "items": [...]}

Chemins hardcodés

Problème : plugins/my-plugin/skills/my-skill/scripts/tool.py

Solution : Exécuter via uv run <skill-dir>/scripts/tool.py pour que les commandes fonctionnent depuis n’importe où.

---

Le Cycle d’Évaluation

Un skill n’est pas “fini” après la première écriture. Le cycle d’évaluation est essentiel :

Étape 1 : Créer des cas de test

Écrire 2-3 prompts réalistes — le genre de chose qu’un utilisateur dirait vraiment.

{
  "skill_name": "security-review",
  "evals": [
    {
      "id": 1,
      "prompt": "Review this PR for security issues: https://github.com/org/repo/pull/42",
      "expected_output": "Table of vulnerabilities with severity and fix recommendations"
    }
  ]
}

Étape 2 : Exécuter avec et sans skill

Pour chaque cas de test, lancer deux runs en parallèle :

• Avec skill — L’agent a accès au SKILL.md
• Sans skill — L’agent travaille avec ses connaissances de base

Étape 3 : Comparer les résultats

Évaluer qualitativement (l’humain juge) et quantitativement (assertions vérifiables) :

• Le skill a-t-il produit le format attendu ?
• Les recommandations sont-elles actionnables ?
• Le temps/tokens utilisés sont-ils raisonnables ?

Étape 4 : Itérer

Améliorer le skill en fonction du feedback, puis relancer les tests. Répéter jusqu’à satisfaction.

---

Checklist de Création

Avant de déclarer un skill “prêt”, vérifiez :

Domaine	Critère	Question à se poser
Trigger	Description contient des phrases réelles	L’agent peut-il matcher ce que l’utilisateur dirait ?
Structure	SKILL.md < 500 lignes	Si non, les références sont-elles extraites ?
Style	Voix impérative partout	Pas de “this skill does…” ou “the agent should…”
Terminologie	Un terme par concept	Pas de synonymes mélangés
Exemples	Au moins un exemple concret	L’agent peut-il copier le pattern ?
Portabilité	Pas de chemins absolus	Le skill fonctionne-t-il sur une autre machine ?
Références	Chargement conditionnel	Pas de “read all files before starting”
Scripts	Interface documentée	Arguments et format de sortie spécifiés ?

---

Conclusion

Créer un skill efficace, c’est comme écrire un bon API : clair, concis, et prévisible. Le skill doit donner à l’agent exactement ce qu’il besoin, rien de plus, au moment où il en a besoin.

La progressive disclosure est votre meilleur allié : metadata pour le trigger, instructions pour le workflow, références pour la profondeur. Et surtout, testez avant de déployer — un skill non évalué est un skill qui échouera silencieusement en production.