Le vrai besoin derrière un bon assistant de code

Un assistant de code, ce n’est pas juste un modèle qui écrit du code : c’est un collègue qui débarque sur le projet à chaque nouvelle session. Claude Code, Cursor, GitHub Copilot ou Codex savent coder, mais ils ne connaissent ni le projet, ni ses conventions, ni ses procédures.

Si on ne leur dit rien, ils devinent. Et ils devinent souvent à côté comme par exemple :

• Mauvais gestionnaire de paquets

• Mauvaise structure de dossiers

• Tests au mauvais endroit

Et parfois, ça va beaucoup plus loin. Ça m’est déjà arrivé : l’IA a renvoyé un mail de facturation à un vrai client. Pas de mailcatcher pour intercepter les envois, aucune rule pour lui dire de ne jamais déclencher de mail réel : elle a fait exactement ce qu’on lui demandait, sans savoir que c’était une mauvaise idée.

Pour leur transmettre ce savoir, la plupart des outils proposent aujourd’hui 2 mécanismes : les rules et les skills. Les deux s’écrivent en Markdown, les deux vivent dans le repo Git : c’est pour ça qu’on les confond.

Pourtant, ils ne font pas du tout la même chose : les rules disent à l’IA comment se comporter, les skills lui apprennent comment faire quelque chose. La question, c’est de savoir quoi mettre où, sans saturer l’IA ni la laisser passer à côté de ce qu’on lui a appris.

Les rules : ce que l’IA doit toujours savoir

Une rule, c’est une consigne qui pose le cadre. Elle ne dit pas comment faire une tâche, elle dit comment on travaille ici :

• « On utilise pnpm, pas npm »

• « Pas de any en TypeScript »

• « Les tests vont dans __tests__, à côté du code testé »

• « Ne jamais déclencher d’envoi de mail réel »

Chaque outil a son format, mais l’idée est la même partout : un ou plusieurs fichiers Markdown, versionnés avec le code, que l’outil injecte dans le contexte de l’IA.

Bon à savoir : AGENTS.md devient le format commun, lu par la plupart des outils. On peut y centraliser les conventions du projet et le référencer depuis les fichiers propres à chaque outil (un CLAUDE.md peut par exemple importer @AGENTS.md). Et pas besoin de partir d’une page blanche : la plupart des outils savent générer un premier fichier à partir du code existant (/init dans Claude Code par exemple). Il faudra juste l’élaguer ensuite.

Côté points forts :

• Fiables : elles sont là à chaque échange, l’IA n’a pas à penser à les consulter

• Simples : un fichier Markdown, rien de plus

En contrepartie :

• Elles occupent le contexte en permanence

• Plus le fichier grossit, moins chaque consigne pèse : un fichier de 800 lignes n’est pas plus complet, il est moins bien suivi

Attention, une rule reste une consigne, pas une garantie. Pour mon mail de facturation, une rule aurait sans doute évité le problème, mais la vraie protection, c’est un mailcatcher en local. Plus généralement, si une règle ne doit jamais être enfreinte, mieux vaut passer par quelque chose qui s’exécute à coup sûr : un hook, un linter, la CI ou la config de l’environnement.

Les skills : ce que l’IA doit savoir faire au bon moment

Un skill, c’est un savoir-faire empaqueté. Concrètement, c’est un dossier avec un fichier SKILL.md et, si besoin, des ressources : scripts, templates, documentation… Le SKILL.md commence par un court en-tête avec un nom et une description, puis les instructions détaillées :

---
name: release
description: Prépare une release : changelog, bump de version, tag Git. À utiliser quand on demande de publier ou de préparer une nouvelle version.
---

# Préparer une release

1. Vérifier que la branche main est à jour et que la CI est verte
2. Générer le changelog avec `scripts/changelog.sh`
3.

---
name: release
description: Prépare une release : changelog, bump de version, tag Git. À utiliser quand on demande de publier ou de préparer une nouvelle version.
---

# Préparer une release

1. Vérifier que la branche main est à jour et que la CI est verte
2. Générer le changelog avec `scripts/changelog.sh`
3.

---
name: release
description: Prépare une release : changelog, bump de version, tag Git. À utiliser quand on demande de publier ou de préparer une nouvelle version.
---

# Préparer une release

1. Vérifier que la branche main est à jour et que la CI est verte
2. Générer le changelog avec `scripts/changelog.sh`
3.

Là où une rule dit « voilà comment on travaille ici », un skill dit « voilà comment on fait cette chose précise » :

• Préparer une release

• Ajouter un nouvel index de recherche

• Faire une revue de PR selon la checklist de l’équipe

• Générer un rapport au format maison

Ce sont des procédures longues, qu’on n’utilise pas à chaque échange, mais qu’on veut voir bien exécutées le jour où on en a besoin.

Un exemple que j’utilise : un skill pour analyser les Core Web Vitals d’un site. Il suit toujours la même méthode : quelles métriques regarder (LCP, INP, CLS), quels seuils, comment présenter les résultats. Le mettre dans les rules n’aurait aucun sens : l’IA traînerait ces consignes sur chaque tâche, alors qu’on en a besoin de temps en temps seulement.

Le format est né chez Anthropic, puis il a été publié comme standard ouvert (Agent Skills) et repris par d’autres outils comme Cursor, GitHub Copilot ou Codex. C’est une vraie différence avec les rules : un même skill peut servir dans plusieurs outils, seul l’emplacement du dossier change (.claude/skills/ pour Claude Code par exemple).

Le gros avantage, c’est qu’un skill peut faire des centaines de lignes et embarquer des scripts sans rien coûter au quotidien. Le revers, c’est que c’est l’IA qui décide de l’utiliser, en lisant sa description. Une description vague comme « aide pour les releases » et le skill reste au placard. Dans le doute, on peut toujours l’appeler à la main (/release par exemple).

Comment ils sont chargés

C’est là que se joue la vraie différence : les rules sont chargées d’office, les skills arrivent seulement quand on en a besoin.

Les rules sont injectées selon des conditions qu’on fixe soi-même :

• Toujours : les fichiers principaux sont lus en entier au début de la session, avant même le premier message

• Selon les fichiers : seulement quand l’IA travaille sur certains chemins (les globs de Cursor, le applyTo de Copilot, les paths de Claude Code)

• Selon la description : quand l’IA juge la rule pertinente (une option de Cursor)

• À la main : quand on l’appelle explicitement

Dans tous les cas, une fois chargée, la rule est là, qu’elle serve ou non à la tâche en cours.

Les skills, eux, sont chargés par étapes (on parle de divulgation progressive) :

1. Au démarrage, l’IA ne voit que le nom et la description de chaque skill

2. Quand une demande correspond, elle lit le SKILL.md complet

3. Si les instructions le demandent, elle ouvre les fichiers annexes ou lance les scripts, dont seul le résultat entre dans le contexte

Résultat : on peut installer des dizaines de skills pour un coût quasi nul, ce qui est impossible avec des rules. Mais tout repose sur la description : c’est la seule chose que l’IA voit tant que le skill n’est pas déclenché, c’est donc elle qui doit dire clairement quoi et quand.

Et les rules chargées sur description, alors ? C’est vrai, elles ressemblent beaucoup à des skills. Mais 2 différences restent : un skill embarque des ressources et des scripts, pas une rule, et il suit un format standard, donc portable d’un outil à l’autre.

Mais du coup, quand utiliser quoi ?

Pour s’y retrouver, voilà ce qui change concrètement entre les deux :

Prenons un projet e-commerce en Next.js, avec Meilisearch pour la recherche :

• Dans les rules (un AGENTS.md à la racine) : la stack, « pnpm uniquement », « composants serveur par défaut », « jamais de secret dans le code », la commande pour lancer les tests

• En skills : release pour publier une version, nouvel-index pour ajouter un index Meilisearch avec ses synonymes et ses facettes, revue-pr pour relire une PR selon la checklist de l’équipe

En résumé :

• L’IA doit le respecter tout le temps ? Rule.

• C’est une procédure, longue ou avec des scripts ? Skill.

Et 2 signaux pour savoir qu’on s’est trompé de case :

• Le fichier de rules contient une section « Comment faire une release » de 60 lignes ? C’est un skill qui s’ignore

• Un skill contient « toujours utiliser pnpm » ? C’est une rule mal rangée : elle ne s’appliquera que quand le skill sera chargé

Conclusion : la meilleure config, c’est celle qu’on ajuste

Le piège le plus courant, c’est de tout mettre dans les rules. Le fichier gonfle, l’IA en suit la moitié, et on se demande pourquoi elle continue à lancer npm.

Le plus simple, c’est de partir des erreurs. Quand l’IA se trompe deux fois sur la même chose, c’est qu’il manque une ligne dans les rules ou un skill quelque part. Comme pour la recherche, ce n’est jamais vraiment fini, et c’est très bien comme ça.

Petit rappel : ces outils évoluent vite. Noms de fichiers, emplacements et modes de chargement sont à vérifier dans la documentation de chaque outil avant de les appliquer.