Dans le premier article de cette série, on a vu ce qu’est une skill. Maintenant, on en crée une.
C’est un fichier Markdown. Pas de code, pas de configuration. Juste du texte.
La structure d’un SKILL.md
Un SKILL.md se divise en deux parties : un en-tête YAML et un corps en Markdown.
ma-skill/
└── SKILL.md
L’en-tête contient les métadonnées. Deux champs sont obligatoires : name et description. Les autres sont optionnels.
---
name: nom-de-ma-skill
description: Ce que la skill fait et quand l'utiliser.
license: MIT
compatibility: Requires git
metadata:
author: gabriel
version: "1.0"
allowed-tools: Bash(git:*)
---
name doit être en minuscules avec des tirets, maximum 64 caractères, et correspondre au nom du dossier.
description est le champ le plus important. C’est ce que l’agent lit pour décider si votre skill est pertinente.
compatibility sert à préciser les dépendances de l’environnement, par exemple Requires Python 3.14+ and uv ou Requires git, docker. La plupart des skills n’en ont pas besoin.
allowed-tools pré-approuve des outils que la skill peut utiliser sans demander confirmation à chaque fois. À utiliser avec précaution, surtout pour shell et bash.
Le corps du fichier, après le frontmatter, contient vos instructions en Markdown. L’agent les suit quand la skill est activée.
La description, c’est la clé
Si votre skill ne se déclenche pas, c’est presque toujours la description.
L’agent ne lit pas le contenu de vos skills en permanence. Il lit seulement la description au démarrage, puis décide si la skill est pertinente selon votre demande. Si la description est trop vague, la skill reste inactive.
Une bonne description dit ce que la skill fait, et quand l’utiliser. Elle inclut les mots-clés que vous utiliserez naturellement dans vos demandes.
Description trop vague :
description: Aide avec les plans et les idées.
Description efficace :
description: Interview the user relentlessly about a plan or design until
reaching shared understanding. Use when asked to stress-test a plan,
review a design, or when user says "grill me".
La deuxième version dit explicitement quand l’agent doit charger la skill.
grill-me : l’exemple simple
Le SKILL.md de grill-me tient en quinze lignes :
---
name: grill-me
description: Interview the user relentlessly about a plan or design until
reaching shared understanding, resolving each branch of the decision tree.
Use when user wants to stress-test a plan, get grilled on their design,
or mentions "grill me".
---
Interview me relentlessly about every aspect of this plan until we reach
a shared understanding. Walk down each branch of the design tree,
resolving dependencies between decisions one-by-one. For each question,
provide your recommended answer.
Ask the questions one at a time.
If a question can be answered by exploring the codebase, explore the
codebase instead.
Description précise, instructions directes.
github-actions-failure-debugging : l’exemple technique
Cette skill vient directement de la documentation officielle de GitHub. Elle s’appuie sur des outils externes, notamment le GitHub MCP Server.
---
name: github-actions-failure-debugging
description: Debug failing GitHub Actions workflows. Use when a workflow
is failing, a build is broken, or when asked to investigate a CI failure.
---
To debug failing GitHub Actions workflows in a pull request, follow this
process, using tools provided from the GitHub MCP Server:
1. Use the `list_workflow_runs` tool to look up recent workflow runs for
the pull request and their status.
2. Use the `summarize_job_log_failures` tool to get an AI summary of the
logs for failed jobs, to understand what went wrong without filling your
context window with thousands of lines of logs.
3. If you still need more information, use the `get_job_logs` or
`get_workflow_run_logs` tool to get the full, detailed failure logs.
4. Try to reproduce the failure yourself in your own environment.
5. Fix the failing build. If you were able to reproduce the failure
yourself, make sure it is fixed before committing your changes.
La skill ne contient pas de code. Elle donne des instructions à l’agent sur quels outils utiliser et dans quel ordre. L’agent fait le reste.
Pour des skills plus complexes, vous pouvez ajouter des scripts, des fichiers de référence ou des templates dans des sous-dossiers :
github-actions-failure-debugging/
├── SKILL.md
├── scripts/
│ └── parse-logs.sh
└── references/
└── common-errors.md
Le SKILL.md référence ces fichiers par chemin relatif, et l’agent les charge au besoin.
Où mettre ses skills
Il y a deux portées : par projet et personnelle.
Par projet : la skill est dans votre dépôt et suit votre code. Elle est disponible pour tous ceux qui travaillent sur le projet. Placez-la dans .github/skills/, .claude/skills/ ou .agents/skills/ à la racine de votre dépôt.
Personnelle : la skill est disponible dans tous vos projets. Placez-la dans ~/.copilot/skills/, ~/.claude/skills/ ou ~/.agents/skills/ selon l’agent.
grill-me est une bonne candidate pour une skill personnelle. github-actions-failure-debugging a plus de sens au niveau du projet, surtout si vous voulez y inclure des références spécifiques à votre pipeline.
Particularités par agent
Le standard est commun, mais chaque plateforme a ses différences.
GitHub Copilot ajoute deux champs dans le frontmatter : user-invocable pour contrôler si la skill apparaît dans le menu / du chat, et disable-model-invocation pour empêcher l’agent de la charger automatiquement. Utile quand vous voulez une skill qui ne se déclenche que si vous la demandez explicitement.
OpenAI Codex CLI lit les skills depuis ~/.codex/skills et supporte un fichier config.toml pour activer ou désactiver des skills individuellement sans les supprimer.
ChatGPT supporte les skills, mais elles ne se synchronisent pas encore entre les produits OpenAI. Une skill dans ChatGPT n’est pas automatiquement disponible dans Codex CLI, et vice-versa.
Claude expose les skills via l’API /v1/skills avec le header skills-2025-10-02, ce qui permet de les gérer programmatiquement dans vos propres applications.
Par où commencer
Pour créer votre première skill, demandez à votre agent de le faire pour vous. Décrivez ce que vous voulez, et il génère le SKILL.md. Vous n’avez qu’à ajuster la description.
Pour vous inspirer, anthropics/skills et github/awesome-copilot contiennent des dizaines d’exemples concrets. La spec complète est sur agentskills.io.
Bonne création, et si votre skill ne se déclenche pas, vérifiez la description en premier.
Cet article a été rédigé avec l’aide de l’IA et révisé par moi.