Skills ou fichiers d'instructions : que mettre où ?
CLAUDE.md, AGENTS.md, rules de Cursor, instructions de Copilot ou skill : ce qui est chargé en permanence, ce qui l'est à la demande, et comment répartir vos consignes.
Mis à jour le
Un fichier d'instructions (CLAUDE.md, AGENTS.md, rule de Cursor, instructions de Copilot) est lu par l'agent avant de travailler. Une skill reste en retrait jusqu'à ce qu'une tâche en ait besoin. Cette différence de chargement décide de ce que vous mettez dans l'un ou dans l'autre.
Chargé toujours, chargé à la demande
Les fichiers d'instructions servent de mémoire permanente du projet. Dans Claude Code, CLAUDE.md est lu au début de chaque session ; dans Codex, la chaîne d'AGENTS.md est construite une fois par exécution. Tout ce qu'ils contiennent pèse donc sur le contexte, même quand la tâche n'a aucun rapport.
Une skill se charge en deux temps. Dans Claude Code, l'agent voit d'abord la description de chaque skill ; le texte complet n'est chargé que lorsque la skill est utilisée. La documentation le dit ainsi : le corps d'une skill ne se charge qu'à l'usage, contrairement au contenu de CLAUDE.md. Une procédure de deux cents lignes ne coûte presque rien tant qu'on ne s'en sert pas. Pour les autres agents, vérifiez le comportement sur la page de l'agent ; la logique du format est la même.
Comparatif
| Critère | Fichier d'instructions | Skill |
|---|---|---|
| Chargement | En permanence (au lancement, ou dès que les fichiers concernés sont en jeu pour une rule ciblée) | Description visible d'avance, texte complet quand la tâche correspond |
| Contenu typique | Commandes de build et de test, conventions, architecture, interdits | Procédure en plusieurs étapes, checklist, modèles, exemples |
| Forme | Un fichier Markdown, sans structure imposée | Un dossier avec un SKILL.md (nom, description) et des fichiers annexes |
| Coût en contexte | Payé à chaque session | Quasi nul tant que la skill n'est pas utilisée |
| Déclenchement | Automatique | Par l'agent d'après la description, ou à la main |
Le fichier de chaque agent
| Agent | Fichier principal | Instructions ciblées |
|---|---|---|
| Claude Code | CLAUDE.md (projet, utilisateur, local) ; AGENTS.md lu s'il n'y a pas de CLAUDE.md | Dossier .claude/rules, avec un champ paths pour limiter une rule à certains fichiers |
| Codex | AGENTS.md (global dans ~/.codex, puis du dossier racine jusqu'au dossier courant) | AGENTS.override.md, ou un AGENTS.md dans un sous-dossier |
| Cursor | Rules dans .cursor/rules (.mdc) ; AGENTS.md à la racine accepté | Quatre modes : toujours, selon la description, selon des globs, ou sur mention |
| GitHub Copilot | .github/copilot-instructions.md ; AGENTS.md accepté | Fichiers .instructions.md dans .github/instructions, avec un champ applyTo |
Les rules ciblées de Cursor et de Claude Code sont un entre-deux : elles restent des instructions, mais ne s'appliquent que lorsque des fichiers correspondants entrent en jeu.
Quoi mettre où
Mettez dans le fichier d'instructions ce qui est vrai pour tout le projet et que l'agent ne peut pas deviner :
- les commandes pour lancer les tests, le linter, le build ;
- les conventions de nommage et la structure des dossiers ;
- les pièges connus (une variable d'environnement obligatoire, un dossier à ne pas toucher).
Mettez dans une skill ce qui est une méthode, pas un fait :
- un audit en plusieurs étapes, avec sa checklist ;
- une procédure de publication ou de revue ;
- un modèle de document et ses exemples.
La documentation de Claude Code donne le signal : créez une skill quand vous collez sans cesse les mêmes consignes dans la conversation, ou quand une section de CLAUDE.md est devenue une procédure plutôt qu'un fait.
Garder le fichier court
Visez moins de 200 lignes par CLAUDE.md, selon la documentation de Claude Code : au-delà, le fichier consomme plus de contexte et l'agent le suit moins bien. Cursor recommande de garder chaque rule sous 500 lignes. Codex arrête de lire les fichiers d'instructions une fois atteint 32 Kio cumulés (réglage project_doc_max_bytes).
Un fichier qui grossit se traite en trois gestes :
- Déplacez les procédures dans des skills.
- Déplacez ce qui ne concerne qu'une partie du code dans une rule ciblée.
- Supprimez ce que l'agent déduit seul en lisant le code.
Un fichier partagé entre plusieurs agents
AGENTS.md est lu par Codex, par Cursor et par GitHub Copilot, et Claude Code le lit quand le dépôt n'a pas de CLAUDE.md. Si vous utilisez plusieurs agents, un AGENTS.md commun évite de maintenir plusieurs copies. Dans Claude Code, un CLAUDE.md peut aussi l'importer avec la syntaxe @AGENTS.md.
Les skills suivent le même principe : un même dossier de skill se copie chez chaque agent, seul le dossier d'installation change. La page de chaque agent (Claude Code, Codex, Cursor, GitHub Copilot) l'indique. Pour la différence avec un simple prompt, voyez ressource ou prompt.
Pour aller plus loin
Sources
Questions fréquentes
Une skill remplace-t-elle mon CLAUDE.md ou mon AGENTS.md ?
Non. Le fichier d'instructions porte les faits qui valent pour tout le projet (commandes, conventions, pièges). La skill porte les procédures que l'agent n'a besoin de suivre que pour certaines tâches.
Pourquoi ne pas tout mettre dans CLAUDE.md ?
Parce qu'il est lu au début de chaque session : plus il grossit, plus il occupe de contexte. La documentation de Claude Code conseille de viser moins de 200 lignes par fichier et de ne pas y laisser de procédure longue.
Un fichier d'instructions garantit-il que l'agent obéit ?
Non. Pour Claude Code, ces fichiers sont du contexte, pas une configuration appliquée de force. Pour bloquer une action, il faut un hook, pas une consigne.