Agent Skills : le standard portable pour les agents IA

Vous savez déjà créer un skill : un SKILL.md dans .claude/skills/, invocable par /nom. Cette page va plus loin et traite ce qui se joue derrière : pourquoi une skill ne sature pas le contexte, pourquoi le même fichier fonctionne aussi sur Cursor, Copilot ou Gemini CLI, ce que Claude Code ajoute au format de base, et quels risques de sécurité une skill tierce introduit. Public visé : intermédiaire à avancé, déjà à l'aise avec les bases.

Ce que vous allez apprendre

Comprendre le standard ouvert Agent Skills et sa portabilité entre outils
Expliquer la progressive disclosure et ses trois niveaux de chargement
Repérer les extensions propres à Claude Code (dynamic context, sous-agent, contrôle d'invocation)
Auditer une skill tierce comme une dépendance de code avant de l'installer

Prérequis

La page skills Claude Code déjà lue (structure d'un SKILL.md, frontmatter de base)
lab-claude opérationnel avec au moins un skill créé
Claude Code à jour (les exemples ci-dessous sont vérifiés en v2.1.152)

Agent Skills : un standard ouvert, pas une fonctionnalité maison

Une skill est un dossier contenant un fichier SKILL.md, avec deux champs minimaux dans son frontmatter : name et description. Ce format porte un nom et une spécification publique : Agent Skills, documenté sur agentskills.io. Développé d'abord par Anthropic, il a été publié comme standard ouvert fin 2025, puis adopté par un nombre croissant d'agents.

La conséquence est la partie la plus intéressante : une même skill fonctionne sur plusieurs outils sans modification. Le format est reconnu par Claude Code, mais aussi par Cursor, OpenAI Codex CLI, GitHub Copilot (et VS Code), Gemini CLI (voir le guide Gemini CLI), Goose, OpenCode et d'autres. Vous écrivez une procédure une fois, elle suit votre équipe quel que soit l'agent qu'elle utilise.

C'est ce qui rend le sujet stratégique : une skill n'est pas un gadget lié à un éditeur, c'est un actif portable. Investir dans des skills bien écrites, c'est capitaliser sur un format que vous ne réécrirez pas si vous changez d'outil.

La progressive disclosure : pourquoi une skill ne sature pas le contexte

Le mécanisme central du standard s'appelle la progressive disclosure (divulgation progressive). L'idée : ne charger dans le contexte que le strict nécessaire, et le reste à la demande. Le chargement se fait en trois niveaux.

Niveau	Quand c'est chargé	Coût	Contenu
1. Métadonnées	Au démarrage, pour toutes les skills	~100 tokens par skill	`name` et `description`
2. Instructions	Quand la skill est activée	< 5 000 tokens	Le corps du `SKILL.md`
3. Ressources	À la demande uniquement	quasi illimité	Fichiers de `scripts/`, `references/`, `assets/`

Au démarrage, l'agent ne lit que les noms et descriptions de chaque skill installée. C'est assez pour décider laquelle activer, sans charger leur contenu. Quand une tâche correspond à une description, l'agent lit alors le SKILL.md complet. Et les fichiers annexes ne sont lus que si une étape les réclame.

Concrètement, une skill avec un gros fichier references/format.md ne coûte presque rien tant qu'elle n'est pas utilisée. C'est l'inverse d'un CLAUDE.md géant, toujours présent dans le contexte. C'est aussi ce qui distingue les skills des serveurs MCP : là où une skill se résume à quelques tokens au repos, la seule définition du MCP GitHub peut consommer des dizaines de milliers de tokens en amont. Les skills enseignent un savoir-faire, le MCP donne accès à des systèmes externes : ils sont complémentaires, pas concurrents.

Ce que Claude Code ajoute au standard

Claude Code lit le format standard, puis l'étend avec des fonctionnalités propres. Trois sont à connaître.

Le contrôle d'invocation décide qui peut déclencher la skill. Par défaut, vous et l'agent le pouvez. disable-model-invocation: true réserve le déclenchement à l'humain (/nom), user-invocable: false le réserve à l'agent. C'est le bon réflexe pour toute procédure à effet de bord (commit, déploiement).

L'exécution en sous-agent isole une skill du contexte principal. Avec context: fork, le contenu du SKILL.md devient le prompt d'un sous-agent dédié, sans accès à l'historique de la conversation. Pratique pour une tâche longue qui ne doit pas polluer la session.

L'injection de contexte dynamique est la plus puissante, et la plus sensible. La syntaxe !`commande` exécute un shell et insère sa sortie dans le prompt avant que le modèle ne voie quoi que ce soit. Exemple réel, une skill notes-release qui pré-charge les commits :

---
name: notes-release
description: Rédige des notes de version à partir des derniers commits git. À utiliser quand l'utilisateur prépare une release ou un changelog.
allowed-tools: Bash(git log:*) Bash(git describe:*)
---

Commits depuis le dernier tag (injectés avant traitement) :

!`git log $(git describe --tags --abbrev=0 2>/dev/null)..HEAD --oneline || git log -10 --oneline`

À partir de ces commits, suis le format de `references/format.md`.

Au déclenchement, le git log s'exécute en préprocessing : le modèle reçoit déjà la liste des commits, sans avoir à demander un outil. Retenez bien cet ordre, il a des conséquences de sécurité traitées plus bas.

S'ajoutent des champs comme model (forcer un modèle pendant la skill), effort (niveau de raisonnement), hooks (déclencheurs liés au cycle de vie) et paths (activation limitée à certains fichiers). Vous n'en avez pas besoin au début, mais ils existent.

Les slash commands ont fusionné dans les skills

Évolution récente à connaître : les commandes personnalisées ont fusionné dans les skills. Un fichier .claude/commands/deploy.md et un skill .claude/skills/deploy/SKILL.md créent tous deux la commande /deploy et fonctionnent de la même façon. Vos fichiers .claude/commands/ existants continuent de marcher ; en cas de même nom, la skill a la priorité.

On le vérifie sur lab-claude. Le projet contient quatre skills dans .claude/skills/ et une commande ping dans .claude/commands/ping.md. En demandant à Claude Code la liste de ce qu'il voit :

audit-secu
notes-release
prep-pr
valider
ping

La commande ping apparaît dans la même liste que les skills : pour Claude Code, c'est désormais la même brique. La différence n'est plus que dans les fonctionnalités disponibles : une skill peut embarquer un dossier de fichiers de support, un frontmatter de contrôle d'invocation et le chargement automatique par l'agent. Pour toute nouvelle procédure, préférez donc le format skill.

Le déclenchement repose sur la description, pas sur /nom

Le point que beaucoup ratent : il n'y a aucun routage algorithmique. Pas de mots-clés, pas d'expression régulière, pas de détection d'intention codée. L'agent décide d'activer une skill uniquement en comparant la tâche demandée à la description. La description n'est donc pas un résumé, c'est une règle de déclenchement.

On le voit sur lab-claude. Sans taper /notes-release, une simple demande en langage naturel suffit à activer la skill par sa description :

> prepare-moi des notes de version a partir des derniers commits

## 0.1.0 - 2026-06-26

### Ajouts
- Ajoute l'endpoint `/health` pour les sondes de disponibilité.

### Corrections
- Corrige l'arrondi du total panier.

### Sécurité
- Aucun correctif de sécurité dans cette version.

Trois mécanismes se sont enchaînés sans qu'on les invoque explicitement : la skill a été activée par sa description, les commits ont été injectés par le dynamic context, et le format a été lu depuis references/format.md (progressive disclosure niveau 3), ce qui a fait écarter les commits chore:.

D'où la règle d'or, confirmée par tous les retours de terrain : soignez la description. Décrivez la tâche et le moment où l'utiliser, avec des formulations concrètes. Une description vague comme « aide pour le code » ne se déclenche jamais ; une description trop étroite non plus. Testez toujours avec des phrases réelles, pas avec « déclenche ma skill ».

Sécurité : une skill tierce est du code, pas une configuration

C'est la section la plus importante de cette page, et la moins couverte ailleurs. Le !`commande` du dynamic context s'exécute avant que le modèle raisonne. Une skill malveillante peut donc lancer un shell avant toute possibilité de refus. L'équipe Datadog Security Labs a démontré le vecteur : une skill piégée exfiltrait un token GitHub via !`gh auth token` suivi d'un curl vers un serveur distant, le tout exécuté avant que Claude ne voie le prompt. Les défenses au niveau du modèle ne suffisent pas, parce qu'elles arrivent trop tard.

L'ampleur n'est pas théorique. Une étude Snyk (« ToxicSkills », février 2026) a scanné 3 984 skills publiques : 13,4 % présentaient au moins une faille critique, et près de 37 % un problème de sécurité toutes sévérités confondues. On y trouve des secrets en dur, de la prompt injection et des payloads d'exfiltration obfusqués. Ces chiffres proviennent d'analyses indépendantes, pas de la communication officielle.

La règle pratique tient en une phrase : traitez une skill tierce comme une dépendance de code, pas comme un fichier de configuration. Avant d'installer une skill que vous n'avez pas écrite :

Lisez l'intégralité du SKILL.md et de chaque script bundlé, comme une revue de code.
Cherchez les exécutions shell : repérez les motifs !`...` et les allowed-tools larges comme Bash(*).
Désactivez le préprocessing shell si vous n'en avez pas besoin, via le réglage disableSkillShellExecution: true.
N'installez que depuis des sources fiables, et épinglez la version comme pour n'importe quelle dépendance.

Ce réflexe rejoint la logique de la supply chain logicielle : un composant exécutable récupéré ailleurs mérite le même niveau d'audit qu'un paquet npm ou une image Docker.

Pièges fréquents

Symptôme	Cause probable	Correction
Une skill récente n'apparaît pas	Skill ajoutée pendant la session	Redémarrer la session (les skills se chargent au démarrage)
`SKILL.md` ignoré	Nom de fichier incorrect	Le fichier doit s'appeler exactement `SKILL.md` (casse comprise)
Skill jamais chargée	Dossier double-imbriqué	`.claude/skills/nom/SKILL.md`, pas `nom/nom/SKILL.md`
Des skills disparaissent sans erreur	Trop de descriptions, budget du prompt dépassé	Raccourcir les descriptions, fusionner les skills peu utilisées, augmenter `SLASH_COMMAND_TOOL_CHAR_BUDGET`
Skill jamais déclenchée seule	`description` trop vague ou abstraite	Décrire la tâche et le moment d'usage, avec des termes concrets

Le quatrième cas est le plus sournois : au-delà d'un certain volume de descriptions, les skills excédentaires ne sont plus annoncées à l'agent, sans aucun avertissement. Si une skill cesse mystérieusement de se déclencher après en avoir ajouté d'autres, suspectez ce plafond.

À retenir

Agent Skills est un standard ouvert (agentskills.io), pas une fonctionnalité propre à un éditeur : une skill est portable entre Claude Code, Cursor, Copilot, Gemini CLI et d'autres.
La progressive disclosure charge les skills en trois niveaux : métadonnées au démarrage, instructions à l'activation, ressources à la demande. Coût quasi nul au repos.
Claude Code étend le standard : contrôle d'invocation, exécution en sous-agent (context: fork), et dynamic context (!`...`).
Les slash commands ont fusionné dans les skills : .claude/commands/x.md et .claude/skills/x/SKILL.md créent tous deux /x.
Le déclenchement repose entièrement sur la description : c'est une règle, pas un résumé.
Une skill tierce est du code exécutable : auditez-la comme une dépendance avant de l'installer.

Prochaines étapes

Créer un skill (les bases) Structure SKILL.md, frontmatter, invocation, arguments sur lab-claude

Skills avancées (scripts) Déporter la logique dans un script, ressources à la demande, allowed-tools sûrs

Quelle brique choisir CLAUDE.md, rules, hooks, skills : la bonne case pour chaque besoin

Subagents Claude Code Isoler le contexte et déléguer, le mécanisme derrière context: fork

Gemini CLI Le même format de skills sur l'agent de Google