Agent Skills : donner de la mémoire procédurale à vos agents

Les agents IA ont un problème que les développeurs ont tendance à résoudre de la mauvaise façon. Quand un agent doit savoir comment gérer un workflow GitFlow, respecter les conventions d’un projet, ou suivre un process de déploiement, le réflexe c’est de bourrer le system prompt. Résultat : un monolithe de 4 000 tokens chargé à chaque conversation, dont 80 % sont hors de propos selon la tâche.

Agent Skills est une réponse structurée à ce problème. Un format ouvert, simple, adopté par une trentaine d’outils. Pas une révolution, une convention qui s’avère efficace.

Un format pour donner de la mémoire procédurale aux agents

Le problème n’est pas que les agents sont stupides. C’est qu’ils naissent amnésiques à chaque conversation, et que le seul mécanisme pour leur donner du contexte est le prompt, un canal qui a un coût et une limite.

La mémoire des agents, aujourd’hui, se décline en deux grandes familles. La mémoire sémantique : les connaissances générales, ce que le modèle a appris à l’entraînement. La mémoire procédurale : comment faire quelque chose dans un contexte précis, les conventions de ton projet, le workflow de déploiement, la liste des composants MDX disponibles.

C’est cette deuxième qu’on cherche à injecter. Et le format Agent Skills propose une réponse concrète : un dossier contenant un fichier SKILL.md avec deux éléments en frontmatter YAML, un name et une description, suivis d’instructions en markdown.

mon-skill/
├── SKILL.md          # Instructions + frontmatter (name, description)
├── scripts/          # Scripts exécutables (optionnel)
├── references/       # Fichiers de référence (optionnel)
└── assets/           # Ressources statiques (optionnel)

Le frontmatter ressemble à ça :

---
name: git-workflow
description: >
  Guides teams through GitFlow branch conventions, Conventional Commits
  formatting, and GitLab Merge Request creation. Use when a user wants
  to create a branch, write a commit message, or open a Merge Request.
---

Ce qui suit dans le fichier : les instructions complètes, structurées comme un guide pratique.

Le format a été initié chez Anthropic et est maintenant adopté par une quarantaine d’outils : Cursor, GitHub Copilot, Gemini CLI, OpenCode, VS Code, OpenHands, Amp, Letta. L’idée a fait son chemin vite, parce qu’elle résout un vrai problème sans introduire de complexité excessive.

Progressive disclosure : pourquoi c’est la bonne architecture

La force du format n’est pas dans la structure du fichier. Elle est dans la façon dont les outils le chargent.

L’approche naïve, c’est de tout mettre dans le contexte au démarrage. Mais un skill de 2 000 tokens multiplié par 10 skills installés, c’est 20 000 tokens permanents. Soit 15 à 20 % de la fenêtre de contexte d’un modèle moyen, consommés avant que l’utilisateur ait tapé quoi que ce soit.

Agent Skills résout ça avec un mécanisme en trois temps :

sequenceDiagram
    participant U as Utilisateur
    participant A as Agent
    participant S as Skill Store

    Note over A,S: Au démarrage de l'outil
    A->>S: Charger name + description de chaque skill
    S-->>A: Liste des skills disponibles (metadata seulement)

    Note over U,A: À chaque message utilisateur
    U->>A: "Je veux créer une branche GitFlow"
    A->>A: Matcher la requête contre les descriptions
    A->>S: Activer git-workflow → charger SKILL.md complet
    S-->>A: Instructions complètes (2000 tokens)

    Note over A,S: Pendant l'exécution
    A->>S: Charger scripts/create-branch.sh si nécessaire
    S-->>A: Script exécutable
    A-->>U: Réponse guidée par le skill

Étape 1 - Discovery. Au démarrage, l’outil charge uniquement le name et la description de chaque skill. Quelques dizaines de tokens par skill, pas plus. L’agent a une carte, pas le territoire.

Étape 2 - Activation. Quand la requête de l’utilisateur correspond à la description d’un skill, l’outil charge le contenu complet de SKILL.md. Le skill est injecté dans le contexte juste-à-temps, pour la conversation où il est pertinent.

Étape 3 - Exécution. Si le skill référence des scripts ou des fichiers dans scripts/ ou references/, ils sont chargés à la demande pendant l’exécution, pas systématiquement.

L’alternative classique, un gros system prompt statique, n’a aucune des deux propriétés. Là, l’empreinte contexte grandit avec la tâche. Et les instructions vivent dans des fichiers dédiés, pas noyées dans une config globale.

Écrire un bon skill : plus dur qu’il n’y paraît

La structure du fichier est triviale. La difficulté est ailleurs.

Le problème du triggering

Un skill n’est utile que s’il se déclenche au bon moment. Et le seul mécanisme de déclenchement, c’est la description dans le frontmatter. C’est elle que l’agent lit pour décider si le skill est pertinent.

Deux types d’erreurs sont possibles. L’under-triggering : la description est trop vague ou trop courte, le skill ne se déclenche jamais même quand il le devrait. L’over-triggering : la description est trop large, le skill s’injecte sur des requêtes qui n’ont rien à voir, pollue le contexte et perturbe le comportement de l’agent.

# Description trop vague -- under-triggering probable
description: "Aide avec le code Git"

# Description trop large -- over-triggering probable
description: "Utilisé pour tout ce qui concerne le développement logiciel, les branches, les commits, les déploiements, CI/CD..."

# Description calibrée -- triggering précis
description: >
  Guides teams through GitFlow branch conventions, Conventional Commits
  formatting, and GitLab Merge Request creation via git push options.
  Use when a user wants to create a branch following GitFlow, write a
  compliant commit message, or open a Merge Request on GitLab.

La description doit contenir assez d’information pour que le modèle comprenne quand charger le skill, et assez de précision pour qu’il sache quand ne pas le charger.

La qualité des instructions

Une fois le skill déclenché, la qualité des instructions détermine l’utilité réelle. Quelques patterns qui fonctionnent mal :

Les instructions trop abstraites. “Suis les bonnes pratiques de GitFlow” ne dit rien à un agent. “Crée toujours une branche depuis develop, nomme-la feature/<ticket-id>-<description-courte>, et ouvre une MR vers develop”, là c’est actionnable.

Les instructions sans exemples. Les exemples de code, de commandes, ou de formats attendus ancrent les instructions dans quelque chose de concret. Un exemple vaut souvent mieux qu’un paragraphe de prose.

Les instructions qui dupliquent le system prompt. Si le skill répète des choses que l’agent sait déjà, c’est du bruit. Un skill doit apporter de la connaissance incrémentale, ce qui est spécifique au contexte, au workflow, au projet.

skill-creator : le skill pour créer des skills

Créer un skill sans méthode, c’est rédiger un SKILL.md approximatif, le poser dans un dossier, et croiser les doigts pour que ça se déclenche au bon moment. Ça marche parfois.

skill-creator encode un processus en 6 étapes et embarque 3 scripts pour automatiser les parties mécaniques — c’est un skill que j’ai développé et publié dans mon repo de skills. L’idée : l’agent se concentre sur le contenu, les scripts gèrent le reste.

flowchart TD
    A[Comprendre le skill\navec des exemples concrets] --> B[Planifier les ressources\nscripts / references / assets]
    B --> C[Initialiser depuis un template\ninit_skill.py]
    C --> D[Éditer SKILL.md\net les ressources]
    D --> E[Valider et packager\npackage_skill.py]
    E --> F{Skill testé\nsur des cas réels}
    F -->|Améliorations nécessaires| D
    F -->|Satisfaisant| G[Skill distribué]

    style G fill:#22c55e,color:#fff
    style F fill:#f59e0b,color:#fff

1. Comprendre avant d’écrire

Avant de toucher un fichier, skill-creator demande des exemples concrets. Pas “à quoi sert le skill”, mais “montre-moi comment un utilisateur l’appellerait”. Ce que tu dirais à l’agent, mot pour mot.

La distinction compte. Une description générique comme “aide avec Git” ne triggera pas correctement parce qu’elle n’est pas ancrée dans des cas réels. Partir des exemples force à calibrer le périmètre, et notamment à définir ce que le skill ne doit pas attraper, ce que la plupart des auteurs oublient.

2. Planifier les ressources bundlées

Un skill, c’est plus qu’un SKILL.md. Selon le domaine, trois types de ressources peuvent être embarquées :

• scripts/ : du code exécutable pour les tâches répétitives ou qui nécessitent une fiabilité déterministe. Un script Python qui fait tourner une rotation de PDF, une CLI qui génère un rapport. L’avantage : l’agent peut l’exécuter sans le charger en contexte.
• references/ : de la documentation chargée à la demande. Schémas de base de données, specs d’API, guides de workflow détaillés. Ça garde le SKILL.md lean sans sacrifier la profondeur.
• assets/ : des fichiers utilisés dans la sortie produite par l’agent, pas lus par lui. Templates PowerPoint, boilerplate HTML/React, fontes. L’agent les copie ou les référence, il ne les ingère pas.

3. Initialiser depuis un template

Une fois le périmètre clair, l’agent exécute init_skill.py pour générer la structure complète. Tu n’as rien à taper — l’agent s’en charge et te montre ce qui a été créé :

mon-skill/
├── SKILL.md               # Template avec TODO et guidance structurelle
├── scripts/
│   └── example.py         # Script d'exemple commenté
├── references/
│   └── api_reference.md   # Doc de référence à remplacer
└── assets/
    └── example_asset.txt  # Placeholder à supprimer ou remplacer

Le template SKILL.md inclut une section “Structuring This Skill” qui propose quatre patterns d’organisation selon le type de skill : workflow-based, task-based, reference/guidelines, capabilities-based. Elle se supprime une fois le choix fait.

4. Écrire le SKILL.md

Le template généré contient des TODO explicites. skill-creator guide leur remplissage dans l’ordre : d’abord les ressources bundlées (scripts, references, assets), ensuite le SKILL.md lui-même, parce que les instructions font référence aux ressources, pas l’inverse.

La description est rédigée en style impératif (“Use this skill when…”) avec des signaux négatifs explicites :

---
name: git-workflow
description: >
  Guides teams through GitFlow branch conventions, Conventional Commits
  formatting, and GitLab Merge Request creation via git push options.
  Use when a user wants to create a branch following GitFlow, write a
  compliant commit message, or open a Merge Request on GitLab.
  Do NOT use for general Git questions, rebases, or repository setup.
---

5. Valider et packager

Quand le skill est prêt, tu demandes à l’agent de le packager. Il exécute package_skill.py, qui fait deux choses dans l’ordre : valider d’abord, packager ensuite. Pas de zip si la validation échoue.

La validation (quick_validate.py) vérifie :

• Le frontmatter YAML est valide
• name est en hyphen-case, 64 caractères max, et correspond exactement au nom du répertoire
• description est présente, sans chevrons, 1024 caractères max
• Le champ optionnel compatibility respecte la limite de 500 caractères

Ce dernier point est le piège le plus fréquent. Si le frontmatter dit name: pdf-processor mais que le dossier s’appelle pdf-tool, la validation échoue. Renommer l’un ou l’autre.

6. Itérer sur des cas réels

Un skill qui “a l’air bien” en théorie rate souvent les requêtes réelles. La dernière étape du workflow, c’est d’utiliser le skill sur de vraies tâches, observer où ça coince, description qui ne triggere pas, instructions trop abstraites, ressource manquante, et corriger.

skill-creator guide cette itération avec le même contexte frais que la session de création. Pas besoin de re-expliquer le périmètre du skill.

Installation et premier usage

Agent Skills est un standard — chaque outil compatible charge les skills depuis un dossier local ou un repo Git selon sa propre configuration. La liste complète est sur agentskills.io.

Pour installer skill-creator :

npx skills add https://github.com/azrod/skills --skill skill-creator

Pour créer un nouveau skill :

# Dans OpenCode ou tout outil compatible Agent Skills
> Je veux créer un skill pour gérer les conventions de mon projet

L’agent détecte la requête, active skill-creator, et guide le processus.

Pour distribuer ses propres skills : un repo Git avec des dossiers respectant la structure skill-name/SKILL.md, partagé via npx skills add <url>. Pas de registry central, pas de publish step, juste Git.