J’ai acheté du paprika trois fois, parce que j’en rangeais à trois endroits différents.
Dans l’appartement, il y avait déjà une étagère à épices au-dessus des plaques de cuisson. Quand elle a été pleine, j’ai aménagé un tiroir. Puis j’ai ajouté une étagère dans le placard à provisions. Chaque rangement se tenait au moment où je le faisais. Mis bout à bout, ils rendaient le paprika étonnamment difficile à trouver.
C’est un ami venu cuisiner chez moi qui a mis le problème en évidence. J’ai passé la soirée derrière lui : la bonne poêle est sous l’évier, ce sel-là, c’est du gros sel, le four chauffe fort. Il cuisine mieux que moi. Il avait juste besoin qu’on le guide dans ma cuisine.
En août, je me suis rendu compte que j’avais fait la même chose avec nos dépôts.
Les règles en double
Les projets OwlMeans ne contiennent pas que du code source. Ils embarquent des instructions pour l’agent de code : où se trouvent les choses, quelles commandes lancer, et ce qui doit survivre à une modification.
On prenait en charge Claude Code et GitHub Copilot. Une règle pour l’un devenait une skill sous .claude/skills/ ; l’autre en recevait une copie sous .github/instructions/. Les cartes du projet, les scripts shell et la mémoire ont fini par avoir chacun leur jumeau.
Un seul commit a touché douze fichiers de skills et onze versions miroirs. Chaque correction s’accompagnait d’une petite question : avais-je corrigé l’autre copie ?
Dans OwlMeans Common, le ménage a supprimé 213 fichiers d’instructions en double. Ce chiffre décrit le changement dans notre dépôt. Il ne dit rien de la vitesse qu’un agent aurait gagnée.
À la place, on a mis un seul dossier .agents/ de référence et un AGENTS.md à la racine. Les skills, les règles, les scripts et la mémoire partagée ont chacun trouvé leur place. Les fichiers propres à chaque agent sont devenus des ponts vers cette source.
Le format commun
AGENTS.md donne à un agent les instructions du projet dans un simple fichier Markdown. La spécification Agent Skills définit la structure d’un dossier de skill et de son SKILL.md.
Les deux règlent des problèmes différents. Le fichier racine dit à l’agent comment travailler dans ce dépôt. Une skill contient une procédure qu’il peut charger pour une tâche précise.
La spécification des skills n’impose pas de répertoire parent. .agents/skills/, c’était notre convention à nous, retenue en fonction des outils qu’on utilisait. Je ne devrais pas le présenter comme un répertoire que tous les agents se sont engagés à détecter.
La distinction compte dès que tu ajoutes un autre outil. Un texte partagé ne sert que si l’outil le charge vraiment.
Le pont vers Claude
Notre configuration d’août gardait un petit CLAUDE.md dont la première instruction était @AGENTS.md. Un script générait un lien symbolique par skill dans .claude/skills/.
Claude Code avait ainsi les points d’entrée qu’il attendait, sans nous laisser un jeu d’instructions de plus à maintenir. Le hook de session rafraîchissait les liens.
On en est venus aux liens par skill à force d’essais. Dans notre configuration, lier tout le répertoire des skills avait échoué. C’est une observation sur ce montage-là, pas une règle définitive pour toutes les futures versions de Claude Code.
J’ai revérifié la demande de prise en charge native d’AGENTS.md le 15 octobre 2026 : elle était toujours ouverte. Si tu fais une installation aujourd’hui, consulte la documentation actuelle de Claude Code sur la mémoire et teste ce que l’outil lit. Notre pont, lui, continue d’indiquer explicitement la source qu’il importe.
Les instructions qui méritent d’être gardées
Déplacer les fichiers a réglé les doublons. Ça n’a pas rendu leur contenu utile pour autant.
Une skill générique sur la façon d’écrire du bon code n’apprend pas grand-chose à un agent sur nos entrypoints ou nos slots de projet. Les instructions utiles expliquent cette base de code : quel package possède une ressource, quelle frontière une modification doit respecter, et quelle vérification détecte l’erreur.
Les packages OwlMeans Common embarquent des consignes à côté de leur code. Un projet généré peut installer ces consignes via @owlmeans/agent-skills. Les métadonnées des packages fournissent les instructions ; le dépôt fournit le contexte local.
Il faut quand même que quelqu’un entretienne les deux.
Notre règle : après tout travail planifié d’une certaine ampleur, on revoit les skills concernées. Si une commande, un chemin ou un comportement a changé, on réécrit l’instruction qui le décrit. Une skill énonce la règle actuelle. Une note datée qui dit que l’ancienne règle ne marche plus laisse au prochain agent le soin de décider quel paragraphe l’emporte.
Ça a un coût. Certaines tâches se terminent par du travail de documentation alors que le code passe déjà. Je préfère le payer tant que je me rappelle encore pourquoi l’implémentation a changé.
La mémoire par sous-système
La mémoire souffrait d’un autre genre de doublon. On y tenait le récit des tâches.
Un fichier qui portait le nom d’une investigation me disait ce qui s’était passé cette semaine-là. Pour savoir ce qui était encore vrai sur le routage, je devais lire plusieurs investigations et déterminer laquelle remplaçait les autres.
On a réorganisé la mémoire autour du projet : routage, traductions, déploiement, services externes. Un index relie ces nœuds aux chemins qu’ils couvrent. L’agent lit d’abord cette carte, puis ouvre les nœuds dont il a besoin.
Chaque écriture met à jour le fait correspondant là où il se trouve. Elle n’ajoute pas un nouveau récit daté sous un récit périmé. Un travail encore en cours peut porter une date, mais des consignes établies ne devraient pas obliger à reconstituer la session.
Dans le dépôt de la plateforme, vingt fichiers chronologiques sont devenus onze nœuds structurels. Ce sont les chiffres qu’on a relevés pendant la réorganisation. Le résultat utile, c’est que je savais où chercher.
Une mémoire a quand même besoin d’être corrigée. Sa forme ne peut pas empêcher qu’on y enregistre une hypothèse fausse, et un index court ne peut pas garantir que l’agent charge la bonne page. Elle nous donne un endroit où corriger l’hypothèse quand on la découvre.
Les deux semaines
La réorganisation a pris deux semaines. J’en ai passé une partie sur les conventions de répertoires, et une autre sur les petits problèmes de compatibilité qui n’apparaissent que quand on lance un autre agent.
Les projets générés par OwlMeans embarquent des consignes d’agent. Dans les missions des Services OwlMeans, on adapte aussi les skills et les métadonnées au projet livré. Garder ces consignes utiles reste le travail de la personne qui maintient le dépôt.
Mon ami a toujours besoin de savoir que le four chauffe fort. Au moins, j’ai maintenant un seul endroit où l’écrire.
Initialement publié le 13 août 2026. Révisé le 15 octobre 2026 pour distinguer les formats communs de notre convention de répertoires et pour dater les observations sur la compatibilité des outils.