CLAUDE.md, SKILL.md et MCP : quel niveau contient quelles instructions ?

Les nouveaux utilisateurs de Claude Code et d’autres agents de codage similaires ont tendance à commettre la même erreur au cours du premier mois : ils ouvrent CLAUDE.md et continuent à écrire des guides de style, des étapes de déploiement, des listes de contrôle pour les revues, des schémas de bases de données brutes, jusqu’à ce que le fichier atteigne 600 ou 900 lignes. On suppose alors que plus de contexte au départ rendra l’agent plus intelligent.

C’est tout le contraire qui se produit. La mémoire de travail se remplit, les réponses deviennent moins précises, et les instructions qui fonctionnaient auparavant cessent de le faire. Quelque chose ne va pas, mais il est difficile de déterminer quoi. Pour chaque demande simple, le modèle doit d’abord parcourir des centaines de lignes d’instructions irrelevantes avant d’arriver à une seule ligne de code. Ce n’est ni la faute du modèle, ni celle des instructions : un simple fichier de texte a simplement été chargé de réaliser trois tâches différentes.

Les agents de codage modernes fonctionnent au mieux lorsque les instructions sont divisées en trois couches distinctes : des règles de projet toujours actives, des compétences de tâche chargées sur demande, et des connexions à des outils en temps réel via MCP. En maintenant ces couches séparées, le modèle ne reçoit que ce dont il a besoin, au moment où il en a besoin.

Pourquoi trois couches ?

Il est légitime de se demander pourquoi trois couches plutôt qu’un seul grand fichier ou dix petits fichiers spécialisés. Chaque couche traite un problème différent, et ces problèmes se chevauchent moins que prévu.

• CLAUDE.md gère les éléments qui doivent toujours être vrais.
• SKILL.md gère les éléments qui ne sont importants que parfois.
• MCP gère les données qui deviennent obsolètes dès qu’elles sont enregistrées.

Il s’agit de trois modes de défaillance distincts et non de trois variantes d’un seul. En intégrant les compétences dans CLAUDE.md, on obtient un fichier encombré qui est chargé intégralement à chaque session, que l’on ait besoin ou non d’une liste de contrôle de déploiement. Tout ajout supplémentaire s’avère être une subdivision de l’un des trois modes de défaillance existants et non une tâche nouvelle.

Qu’est-ce qui doit figurer dans CLAUDE.md ou AGENTS.md ?

Imaginez CLAUDE.md comme une note laissée pour un ingénieur dès le premier jour. Ce n’est pas le document complet d’intégration, mais simplement quelques règles non écrites que tout le monde dans l’équipe connaît déjà, comme le fait de ne pas utiliser de composants de classe ici, ou de ne jamais toucher directement à la base de données mais d’utiliser plutôt la couche de services.

Le fichier se trouve dans la racine du projet, et Claude Code le lit automatiquement au début de chaque session. Personne ne l’appelle ni ne le demande. Il est simplement présent, tout comme la mémoire des conventions de l’équipe est présente lorsque l’on s’assoit pour coder.

De bons critères sont les conventions de codage, la structure du projet, des contraintes strictes, des règles de sécurité telles que l’interdiction d’exposer les clés API dans le code, ainsi que le rôle que l’agent doit adopter lors de la révision du travail.

De mauvais critères sont un guide de déploiement en 40 étapes, un schéma de base de données, ou tout élément qui n’est pertinent qu’une fois tous les dix jours. C’est ce deuxième groupe qui entraîne le plus d’erreurs. Si quelque chose n’est pas valable à chaque session, il ne devrait probablement pas y figurer. Un CLAUDE.md qui tente d’être tout finit par être une version lente et encombrée de rien du tout.

Il existe également une version globale à ~/.claude/CLAUDE.md qui s’applique à tous les projets. Les gens y conservent généralement leurs habitudes personnelles, comme le style préféré pour les messages de commit ou la langue à utiliser pour les réponses, et placent les règles spécifiques au projet dans le fichier du projet lui-même.

Un fichier qui remplit sa fonction ressemble à ceci, adapté d’un ensemble de directives comportementales largement diffusées.

# CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

C’est court et précis, et rien à l’intérieur n’a besoin d’être révisé la semaine prochaine. Voici à quoi cela ressemble lorsqu’il y a un problème, un schéma courant dans les versions initiales.

# Project Notes

Our database has these tables: users, orders, products, sessions,

audit_log (schema pasted below, 340 lines)...

To deploy, first SSH into staging, then run these 47 commands...

Here's our Slack webhook URL for notifications: hooks.slack.com/...

When reviewing PRs, check for: [12 paragraphs of instructions]

Chaque élément de cet autre exemple est incorrect pour CLAUDE.md, et ce, pour des raisons différentes. Un schéma devient obsolète dès qu’on y ajoute une colonne. Les étapes de déploiement décrivent une seule tâche nommée. Une URL de webhook est un secret qui doit être stocké dans une variable d’environnement, et non dans du markdown commité. Les instructions de revue des PR sont en réalité une compétence déguisée sous les traits de CLAUDE.md.

Un test utile : cette affirmation resterait-elle vraie si on la relisait dans trois mois, un mardi au hasard, en faisant quelque chose d’indépendant ? Si ce n’est pas le cas, elle ne doit pas figurer dans le fichier.

SKILL.md : une expertise qui n’apparaît que lorsque c’est nécessaire

Agent Skills est apparu chez Anthropic en octobre 2025, conçu de manière à ce que les instructions relatives à une tâche spécifique puissent être stockées dans un dossier et chargées au besoin, plutôt que de occuper constamment le contexte. En décembre 2025, ce format a été ouvert en tant que norme indépendante, et d’autres outils l’ont rapidement adopté. VS Code, Cursor, l’IDE Antigravity de Google, Gemini CLI, Goose ainsi que plusieurs autres agents de codage prennent désormais en charge le même format SKILL.md utilisé par Claude Code. C’est ce même principe qui a fait de MCP la norme du secteur pour les connexions entre outils.

L’idée est utile une fois qu’on la comprend : toutes les connaissances n’ont pas besoin d’être constamment stockées dans la mémoire de l’agent. La plupart des connaissances d’un ingénieur ne deviennent pertinentes que pour une tâche spécifique. Personne ne se souvient de la liste de contrôle de déploiement en écrivant une fonction d’aide. Les compétences suivent cette logique : un dossier contenant SKILL.md reste inutilisé jusqu’à ce qu’une demande comme « examiner cette PR » arrive, et c’est alors que Claude utilise la véritable liste de contrôle d’examen.

Un fichier de compétence commence par une brève description, appelée frontmatter, qui indique ce que fait la compétence et quand elle doit être déclenchée. Lorsqu’un message correspond, Claude charge le reste du contenu. S’il ne correspond pas, aucun de ces éléments n’occupe d’espace dans la conversation. C’est pourquoi les compétences semblent plus légères que si tout était stocké dans CLAUDE.md. Une compétence pour l’examen des demandes de pull request, une autre pour les migrations de base de données et encore une autre pour les notes de version ne se disputent pas d’espace tant que cette tâche précise n’est pas en cours.

.claude/skills/
├── code-review/
│   └── SKILL.md
├── pr-description/
│   └── SKILL.md
└── anti-sycophancy/
    └── SKILL.md

Les compétences au niveau du projet se trouvent dans .claude/skills/ à l’intérieur du répertoire. Les compétences personnelles qui doivent suivre un utilisateur partout se trouvent dans ~/.claude/skills/. Cette séparation reflète celle de CLAUDE.md : projet contre global. Une version réelle, simplifiée :

---
name: production-code-validation-checklist
description: "Run this checklist before pushing code to GitHub"
---

# Production Code Validation Checklist

**Run this checklist before pushing code to GitHub.**

This is not optional. This is how you prevent broken repositories.

## Secrets Audit
- [ ] Searched for: password, secret, token, key, api_key, credential
- [ ] All secrets are in environment variables or .env, not in code
- [ ] .env file is in .gitignore

## Failure Scenario Testing: Deliberately Break It
This is the most important step. Production code breaks. Can your code
handle it?
- [ ] Run without a required environment variable, does it fail with a
      clear error?
- [ ] Simulate a timeout on any HTTP request, does the code handle it?
- [ ] Feed it empty input, null input, and malformed input, one at a time

## Final Production Readiness Assessment
Choose ONE:
- [ ] PROTOTYPE: concept proven, not production ready
- [ ] DEVELOPMENT READY: works for development, not production
- [ ] PRODUCTION CANDIDATE: ready for real-world testing
- [ ] PRODUCTION VERIFIED: tested in a real environment, known to work

**If you cannot check a box, you are not done.**

Remarquez ce qu’il évite. Il ne respecte pas non plus de conventions de codage ni de schéma de base de données. Il dispose d’une tâche nommée, déclenchée par un type de moment donné, et c’est ce qui fait de lui une compétence et non un CLAUDE.md simplifié. Le critère simple est de déterminer si quelque chose n’est nécessaire que lors de l’exécution d’une tâche spécifique et nommée. Dans ce cas, il s’agit d’une compétence et non d’une règle.

MCP : accès, pas seulement connaissances

CLAUDE.md et SKILL.md sont tous deux des fichiers Markdown écrits par quelqu’un. MCP est différent. Il relie Claude, pendant son exécution, à une ressource en dehors du chat, qu’il s’agisse d’une base de données, de GitHub, de Slack, du système de fichiers ou de tout autre élément connecté.

Dans un projet axé sur RAG, la connexion directe à Chroma est un cas typique. Le serveur officiel chroma-mcp expose des collections en tant qu’outils que Claude peut interroger.

{
  "mcpServers": {
    "chroma": {
      "command": "uvx",
      "args": [
        "chroma-mcp",
        "--client-type", "persistent",
        "--data-dir", "/path/to/your/chroma/data"
      ]
    }
  }
}

Dans Claude Code, la configuration s’effectue avec une seule commande, sans nécessité d’édition manuelle du JSON.

claude mcp add --scope project chroma \
  -- uvx chroma-mcp --client-type persistent --data-dir ./chroma-data

Celui-ci enregistre le serveur et écrit la configuration dans .mcp.json au sein du projet, ce qui peut être soumis pour que toute l’équipe dispose de la même connexion sans avoir à la configurer manuellement. Claude Code propose trois niveaux d’accès : local, ce qui correspond à un utilisateur sur une seule machine ; projet, ce qui signifie que la configuration est stockée dans le répertoire de version et partagée ; et utilisateur, ce qui désigne tous les projets auxquels une personne a accès. Le même schéma projet contre global apparaît une troisième fois, ce qui le rend facile à retenir une fois remarqué.

Le protocole a connu une croissance si rapide que cette évolution fait désormais partie intégrante de son histoire. Le registre officiel des serveurs compte plus de 9 000 serveurs, et les téléchargements mensuels du SDK de référence sont passés d’environ 2 millions à près de 100 millions en environ 16 mois, selon les chiffres partagés par Anthropic. Il ne s’agit plus d’une fonctionnalité de niche. Quiconque colle encore un schéma ou une proposition sur GitHub dans une requête effectue manuellement ce que fait en temps réel une connexion MCP, et la copie collée devient obsolète dès qu’il y a un changement côté source.

Arbre de décision

1. Faut-il que cela s’applique à chaque session, quel que soit le travail ? Si oui, l’inclure dans CLAUDE.md. Sinon, continuer.
2. S’agit-il d’une tâche spécifique, nommée, répétable avec ses propres étapes ? Si oui, en faire un SKILL.md. Sinon, continuer.

Clude a-t-il besoin de données à jour, ou doit-il agir en dehors de la conversation ? Si c’est le cas, utilisez MCP. Sinon, cela n’a peut-être même pas sa place dans la configuration de l’agent. Certaines choses sont mieux laissées en tant que documentation que personne ne demande à une IA de mémoriser.

Un piège de nommage

Tout utilisateur qui passe d’un outil à un autre finira par se heurter à ce problème. Claude Code et Cursor lisent CLAUDE.md, tandis que Codex CLI ainsi que quelques autres environnements d’exécution utilisent AGENTS.md, qui remplit la même fonction sous un nom différent. Antigravity de Google, développé par l’ancienne équipe Windsurf suite à l’accord conclu avec Google au milieu de 2025, emploie également sa propre convention AGENTS.md. Pourtant, tous ces outils — Claude Code, Cursor, Codex et Antigravity — lisent le même format SKILL.md pour décrire les compétences. Ainsi, la couche des règles varie selon l’outil, mais la couche des compétences reste uniforme. Cela est important avant de supposer qu’une compétence écrite pour un agent doit être réécrite pour un autre.

L’habitude qui résout le problème

Avant d’ajouter un paragraphe dans CLAUDE.md, demandez à quel des trois répertoires il doit être affecté. Une grande partie du contenu stocké dans CLAUDE.md correspond en réalité à des compétences qui n’ont jamais eu de dossier dédié. Cette pratique constitue une forme d’ingénierie contextuelle sous une autre forme : choisir ce que l’agent voit et au moment opportun, au lieu de tout mettre dans le premier fichier ouvert en espérant que le modèle s’en occupe. Ouvrez un CLAUDE.md et comptez combien de paragraphes représentent en fait des compétences portant la mauvaise extension de fichier. Ce chiffre est généralement supérieur à ce que l’on pourrait imaginer.