07 - Skills (Agent Skills)#

Une skill, c'est ton savoir-faire range dans un dossier que l'agent ouvre tout seul, au bon moment, sans que tu aies a le reexpliquer.

Temps de lecture : 8 min | Niveau : Debutant

Ce que tu sauras faire apres#

• Expliquer en une phrase ce qu'est une skill.
• Distinguer une skill d'un prompt, d'une commande personnalisee et d'un sous-agent.
• Choisir le bon mecanisme selon ton besoin, sans hesiter.
• Parcourir cette section dans le bon ordre.

🎯 Le probleme que les skills resolvent#

Tu travailles sur un entrepot de donnees. A chaque fois que tu demandes une requete SQL a l'agent, tu retapes la meme chose :

Ecris-moi une requete sur la table fact_commandes. Attention : on filtre toujours is_test = false, les montants sont en centimes, la colonne de date c'est date_commande en UTC, et on nomme les CTE en snake_case.

Tu l'ecris lundi. Tu le reecris mardi. Tu l'oublies mercredi, et la requete est fausse.

Une skill capture ces regles une fois pour toutes dans un dossier. L'agent les charge automatiquement quand tu parles de SQL, et seulement a ce moment-la.

La documentation Anthropic compare une skill a un document d'onboarding que tu preparerais pour un nouveau collegue : il ne le relit pas en entier tous les matins, il l'ouvre au chapitre utile quand il en a besoin.

Les 4 mecanismes a ne pas confondre#

Avant de plonger, mettons de l'ordre. Quatre choses se ressemblent mais ne servent pas a la meme chose.

• Prompt : ce que tu tapes dans la conversation. Vit le temps d'un message.
• Commande personnalisee : un fichier Markdown que tu declenches avec /nom. Dans Claude Code, les commandes personnalisees ont ete fusionnees avec les skills : un fichier .claude/commands/deploy.md et une skill .claude/skills/deploy/SKILL.md creent tous les deux /deploy et fonctionnent pareil. L'ancien format continue de marcher (il accepte le meme frontmatter, sauf name et paths), mais la doc recommande d'ecrire les nouveautes en skill.
• Skill : un dossier qui contient un SKILL.md, plus si besoin des fichiers de reference et des scripts. Peut etre declenchee par toi (/nom) ou par l'agent lui-meme quand ta demande correspond a sa description.
• Sous-agent (subagent) : un assistant specialise qui travaille dans sa propre fenetre de contexte, avec son propre prompt systeme et ses propres outils, et qui te renvoie seulement un resume.

Tableau comparatif#

Et le CLAUDE.md dans tout ca ?#

Le fichier CLAUDE.md (les instructions persistantes de ton projet) est charge au debut de chaque conversation, systematiquement. C'est sa force et sa faiblesse : toujours la, toujours paye en tokens.

Une skill, elle, est chargee a la demande. La doc Claude Code le dit clairement : le contenu d'une skill ne coute rien tant qu'elle n'est pas invoquee.

Regle simple. Ce qui vaut pour tout le projet, tout le temps, et tient en 20 lignes : CLAUDE.md. Ce qui vaut pour un type de tache et fait 200 lignes de detail : une skill.

🧭 Comment choisir en 10 secondes#

Pose-toi les questions dans cet ordre.

1. Je le ferai une seule fois ? Un prompt suffit.
2. Je le refais souvent, et ca tient en un paragraphe ? Une skill courte, declenchee a la main.
3. Je le refais souvent, et il y a du detail (schemas, conventions, exemples) ? Une skill avec fichiers de reference. C'est le coeur de cette section.
4. Le travail va generer 3000 lignes de logs que je ne relirai jamais ? Un sous-agent.
5. Je veux distribuer plusieurs skills, agents et hooks a mon equipe en un bloc ? Un plugin (voir section 08).

📚 Plan de la section#

Lis dans cet ordre.

1. 01-quest-ce-quune-skill.md — Le concept, la divulgation progressive, ou se rangent les skills.
2. 02-anatomie-de-skill-md.md — Le frontmatter champ par champ, le corps, les fichiers annexes, et comment ecrire une description qui declenche.
3. 03-creer-sa-premiere-skill.md — Tutoriel complet : la skill convention-sql-equipe, de zero jusqu'au test.
4. 04-exemples-skills-data.md — 4 skills pretes a adapter pour la data.
5. 05-bonnes-pratiques.md — Les regles d'or et les pieges courants.

🌍 Ou les skills fonctionnent#

Les skills ne sont pas un gadget d'un seul outil.

• Claude Code : skills personnelles (~/.claude/skills/) ou projet (.claude/skills/), sur ton disque, sans upload.
• API Claude : skills prebuilt (pptx, xlsx, docx, pdf) et skills personnalisees, via l'outil d'execution de code.
• claude.ai : skills prebuilt actives, et skills personnalisees a televerser en zip depuis Reglages > Fonctionnalites (offres Pro, Max, Team et Enterprise, avec l'execution de code activee).
• Hors Anthropic : le format a ete publie comme standard ouvert sur agentskills.io, et il est adopte par d'autres agents (Gemini CLI, Cursor, GitHub Copilot / VS Code, OpenCode, Goose, Codex, entre autres).

Point important. Les skills personnalisees ne se synchronisent pas entre ces surfaces. Une skill televersee sur claude.ai n'est pas disponible via l'API, et les skills Claude Code vivent sur ton disque, separees des deux autres. Tu les geres separement pour chaque surface.

🚀 Template : ta premiere skill en 3 minutes#

Si tu veux juste demarrer sans lire le reste, copie ce bloc, remplace les champs entre crochets, et colle-le dans une session Claude Code.

Cree une skill projet dans .claude/skills/[NOM_EN_MINUSCULES_AVEC_TIRETS]/SKILL.md.

Ce qu'elle doit faire : [CE_QUE_TU_REFAIS_SOUVENT, EN_2_LIGNES].
Les regles que je repete a chaque fois :
- [REGLE_1]
- [REGLE_2]
- [REGLE_3]

Contraintes pour le fichier :
- description a la troisieme personne, disant ce que ca fait ET quand l'utiliser,
  avec ces mots declencheurs : [MOT_1], [MOT_2], [MOT_3]
- SKILL.md sous 80 lignes, le detail dans reference/[NOM_FICHIER].md
- n'ecris pas ce que tu sais deja faire, garde uniquement mes regles a moi

Ensuite, explique-moi en 3 lignes comment la tester.

Puis ouvre une nouvelle demande normale, sans nommer la skill, et verifie qu'elle se declenche toute seule. C'est le seul vrai test.

A retenir#

• Une skill, c'est un dossier avec un SKILL.md, plus des ressources optionnelles.
• Sa force : elle ne coute presque rien tant qu'elle n'est pas utilisee (~100 tokens de metadonnees).
• Elle peut se declencher toute seule si sa description est bien ecrite. C'est la difference majeure avec une commande.
• Dans Claude Code, commandes personnalisees et skills sont desormais le meme mecanisme : /nom.
• CLAUDE.md est toujours charge. Une skill est chargee a la demande.
• Le format est un standard ouvert, donc ce que tu apprends ici se reutilise ailleurs.

Depots GitHub a explorer#

Ces depots te donnent des SKILL.md reels : le format officiel, l'outil qui ecrit les skills a ta place, et des collections deja utilisees en production.

Clone anthropics/skills en premier. Tu y as le squelette (template/) et la spec (spec/) dans le meme depot : tu copies le template, tu remplis, et tu verifies chaque champ contre la spec sans changer d'onglet.

Enchaine avec dbt-labs/dbt-agent-skills : c'est le meme format, mais sur un vrai projet data, avec les fichiers de reference dont parle la section 03.

Sources#

• Agent Skills in Claude Code
• Agent Skills - Overview
• Skill authoring best practices
• Slash commands
• Subagents
• How Claude remembers your project
• Plugins overview
• agentskills.io
• Agent Skills, annonce Anthropic