Le CLAUDE.md de Karpathy, expliqué : un fichier derrière une recherche de Skills

Sur Google Trends, dans le monde entier, au cours des sept derniers jours et consulté le 23 octobre 2026, « karpathy skills » apparaît comme une requête en forte hausse sous la requête source « claude skills ». Toute personne qui suit cette recherche aboutit au même endroit : github.com/multica-ai/andrej-karpathy-skills, un dépôt qui affichait 222 612 étoiles sur GitHub, consulté le 23 octobre 2026. Sa description ne contient pas du tout le mot « skill ». Elle indique : « Un unique fichier CLAUDE.md pour améliorer le comportement de Claude Code, tiré des observations d'Andrej Karpathy sur les pièges du codage avec les LLM. »

L’écart entre la requête et l’objet n’est pas un simple détail technique. Une skill et un fichier CLAUDE.md sont des mécanismes différents qui accomplissent un travail différent, et presque toutes les affirmations formulées à propos de ce dépôt dépendent soit de la connaissance de celui dont il s’agit, soit supposent discrètement le mauvais. Les consignes qu’il contient tiennent dans un seul fichier. Le dépôt autour de ce fichier comporte aussi un manifeste de plugin et un dossier sous skills, ce qui explique probablement le mot saisi dans la barre de recherche. Séparer le conditionnement du contenu utile est la première démarche réellement utile ici.

Les chiffres, tous issus de GitHub et relevés le 23 octobre 2026 : 222 612 étoiles, 22 321 forks, créé le 27 janvier 2026, dernier push le 20 avril 2026, licence MIT. C’est cette dernière paire qui est intéressante. Le dépôt n’a reçu aucun push depuis environ six mois, et le nombre d’étoiles a continué d’augmenter malgré tout.

Le fichier fait le travail ; l’emballage explique le terme de recherche.

Ouvrez le dépôt et l’incohérence saute aux yeux dans la liste des fichiers. Il y a CLAUDE.md à la racine, et à côté CURSOR.md, EXAMPLES.md, un dossier .cursor/rules contenant les mêmes directives sous forme de règle de projet Cursor, un dossier .claude-plugin, et un répertoire skills/karpathy-guidelines. La méthode d’installation recommandée dans le README est la place de marché des plugins, et elle présente le résultat comme rendant « la compétence disponible dans tous vos projets ».

Le terme de recherche n’est donc pas tant erroné qu’imprécis. Il y a un dossier skills. Il y a un plugin. Ce qui n’existe pas, en revanche, c’est un ensemble de compétences distinctes remplissant chacune une tâche différente, c’est-à-dire la forme que les gens désignent généralement par « skill pack » : un dossier contenant un SKILL.md et les fichiers de support nécessaires à cette capacité, que l’on invoque pour une seule tâche. Ici, l’ensemble des consignes tient dans un seul document d’instructions permanentes, et le plugin existe pour apporter ce document dans un projet.

Que cette distinction vous importe dépend de ce que vous attendiez de la recherche. Si vous cherchiez une boîte à outils, ce n’en est pas une. Si vous vouliez un court recueil de règles qui change le comportement d’un agent de codage à l’échelle d’un projet, c’est exactement ce que c’est, et il vaut la peine de comprendre pourquoi quelqu’un l’écrirait sous forme de fichier plutôt que de compétences.

Les plaintes contre lesquelles il a été rédigé

La source indiquée dans le README est une publication d’Andrej Karpathy sur X, que le README cite pour trois critiques sur la manière dont les modèles écrivent du code. Elles valent la peine d’être lues en entier, car les quatre principes leur correspondent presque un à un.

Le premier : les modèles « font de mauvaises suppositions à votre place et les suivent sans vérifier », et « ne gèrent pas leur confusion, ne cherchent pas à obtenir des clarifications, ne signalent pas les incohérences, ne présentent pas les compromis, ne contestent pas quand ils le devraient. » Notez ce qui est décrit. Il ne s’agit pas d’une plainte concernant des réponses fausses. Il s’agit d’une plainte concernant des réponses fausses mais fluides, formulées sans hésitation, où l’incertitude qui aurait dû donner lieu à une question a plutôt produit du code assuré.

La deuxième : ils « aiment vraiment à compliquer à l’excès le code et les API, gonfler les abstractions, ne nettoient pas le code mort… mettent en œuvre une construction boursouflée de plus de 1000 lignes alors que 100 suffiraient ». Celle-là est familière à quiconque a demandé une fonctionnalité et a reçu un framework.

Le troisième est plus subtil et, pour quiconque relit des diffs, le plus coûteux : ils « continuent parfois de modifier ou supprimer, comme effets secondaires, des commentaires et du code qu'ils ne comprennent pas suffisamment, même si cela est orthogonal à la tâche ». Une modification orthogonale d'un seul commentaire est anodine en soi. Multipliée à l'échelle d'une base de code, c'est ainsi qu'une file de relecture se remplit de changements que personne n'a demandés, et qu'un commentaire expliquant un contournement disparaît avant que quiconque apprenne pourquoi ce contournement existait.

Quatre principes, et l'épreuve que chacun laisse derrière lui

Le fichier encode quatre principes. Chacun s’accompagne d’un court ensemble de règles, et deux d’entre eux énoncent un test en une seule ligne que l’on peut appliquer à un diff sans rien installer. C’est dans les règles que transparaît le caractère du fichier.

Réfléchir avant de coder

L’instruction du titre est « Ne présumez pas. Ne cachez pas la confusion. Exposez les compromis. » En dessous : énoncez explicitement les hypothèses et posez des questions plutôt que de deviner ; présentez plusieurs interprétations lorsque la demande est ambiguë ; exprimez votre désaccord lorsqu’une approche plus simple existe ; arrêtez-vous lorsque vous êtes confus, nommez ce qui n’est pas clair et demandez une clarification. Cela vise directement la première plainte. Le mécanisme n’est pas « soyez plus prudent » — il consiste à convertir les choix silencieux en choix visibles, afin qu’un relecteur puisse être en désaccord avant que le code existe plutôt qu’après.

La simplicité avant tout

La règle est le minimum de code qui résout le problème, sans rien de spéculatif : aucune fonctionnalité au-delà de ce qui a été demandé, aucune abstraction pour du code à usage unique, aucune flexibilité ni configurabilité que personne n’a demandée, aucune gestion d’erreur pour des scénarios impossibles, et « si 200 lignes pouvaient en faire 50, réécrivez-le ». Le test tient en une seule question — un ingénieur senior dirait-il que c’est trop compliqué ? — ce qui relève d’un jugement, et l’est ouvertement.

Modifications chirurgicales

Ici, le fichier scinde l’instruction en deux, ce qui est l’élément le plus utile qu’il contient. Lorsque vous modifiez du code existant : n’améliorez pas le code, les commentaires ou le formatage adjacents ; ne refactorisez pas ce qui n’est pas cassé ; alignez-vous sur le style existant même si vous feriez autrement ; signalez le code mort sans rapport plutôt que de le supprimer. Lorsque vos propres modifications créent des orphelins : supprimez les imports, variables et fonctions que vos modifications ont rendus inutilisés, mais laissez le code mort préexistant tranquille, sauf demande contraire. Le test est que chaque ligne modifiée se rattache directement à la demande.

Exécution pilotée par les objectifs

Définissez des critères de réussite et bouclez jusqu’à vérification. Le README présente la transformation sous forme de paires. Au lieu d’« ajouter une validation », écrivez des tests pour les entrées invalides, puis faites-les passer. Au lieu de « corriger le bug », écrivez un test qui le reproduit, puis faites-le passer. Au lieu de « refactoriser X », assurez-vous que les tests passent avant et après. Pour un travail en plusieurs étapes, il demande un plan court dans lequel chaque étape nomme sa propre vérification. Le README cite à nouveau Karpathy ici : « Les LLMs sont exceptionnellement doués pour boucler jusqu’à atteindre des objectifs précis… Ne lui dites pas quoi faire, donnez-lui des critères de réussite et regardez-le aller. »

Un fichier, une compétence et un plugin sont trois choses différentes.

Il est utile d’être précis sur le mécanisme, car le comportement pratique diffère. CLAUDE.md est un fichier d’instructions de projet : un texte que Claude Code lit comme contexte permanent pour un dépôt, présent qu’il ait été demandé ou non lors de ce tour. Une skill est un dossier contenant un SKILL.md qui décrit quand la capacité doit être utilisée, chargée lorsqu’une tâche l’exige et pas avant. Un plugin est un paquet de distribution, installé via une marketplace, qui peut contenir des skills, des commandes et d’autres composants. Ces distinctions portent sur le moment où les instructions entrent dans le contexte et sur qui en décide, non sur la qualité.

En ce sens, un CLAUDE.md est le plus direct des trois. Il est toujours actif dans ce projet, il s'applique à chaque tâche qui y est menée, et il occupe du contexte à chaque tour, que le travail consiste à corriger une faute de frappe d'une ligne ou à réaliser une migration. Le README du fichier reconnaît lui-même ce coût dans une section intitulée Tradeoff Note : les directives privilégient la prudence plutôt que la vitesse et, pour les tâches triviales — corrections de fautes de frappe simples, évidences tenant en une ligne —, il convient de faire preuve de discernement. Il y est précisé que l'objectif est de réduire les erreurs coûteuses lors des travaux non triviaux, et non de ralentir les tâches simples.

C’est une description juste de ce qu’un fichier d’instructions permanentes peut faire. Il ne peut pas ajouter une capacité que le modèle n’a pas. Il peut seulement rendre le comportement existant du modèle plus ou moins probable. C’est pourquoi le fichier est rédigé sous forme de contraintes — ne fais pas ceci, demande avant cela — plutôt que d’encouragement à faire mieux.

Ce que mesurent 222 612 étoiles

Ils mesurent l’attention. Ce n’est pas un rejet, et ce n’est pas rien : un dépôt créé en janvier 2026 et ayant fait l’objet d’un dernier push en avril avait atteint 222 612 étoiles et 22 321 forks au 23 octobre 2026, sur GitHub, consulté ce jour-là, ce qui signifie qu’il a été largement partagé et forké par des personnes qui voulaient en avoir leur propre copie. Un nombre d’étoiles est un indicateur raisonnable du nombre de personnes ayant trouvé quelque chose qui valait la peine d’être mis en signet.

Ce n’est pas une mesure indirecte de l’effet, et le dépôt ne prétend pas le contraire. Ce qui n’est publié nulle part dans celui-ci : aucun benchmark comparant les résultats avec et sans le fichier, aucune méthodologie pour mesurer s’il fonctionne, et aucune comparaison avec un témoin. Il n’y a pas de comparaison avant/après sur une base de code réelle, pas d’étude auprès de relecteurs, pas de taux d’incidents. Un fichier comme celui-ci est une hypothèse sur le comportement du modèle, formulée avec élégance, et personne n’a mené l’essai.

Ce que le README propose à la place, c’est une section intitulée Comment savoir que ça fonctionne, qui énumère quatre choses que vous pourriez observer : moins de modifications inutiles dans les diffs, moins de réécritures dues à la surcomplexité, des questions de clarification qui arrivent avant l’implémentation plutôt qu’après les erreurs, et des pull requests propres et minimales. Ce sont là des signaux sensés. Ce sont aussi exactement ce que vous écririez si vous n’aviez rien mesuré, et ils sont auto-déclarés par la personne qui applique le fichier. Lisez-les comme une liste de contrôle à laquelle confronter le fichier dans votre propre dépôt, et non comme la preuve qu’il l’a déjà satisfaite.

Ce que vous tapez réellement pour l'installer

Le README propose deux voies. La première, recommandée, s'exécute dans Claude Code : ajoutez le marketplace, puis installez le plugin, après quoi les directives sont présentes pour l'ensemble des projets plutôt que dépôt par dépôt. La seconde est propre à chaque projet : récupérez le fichier CLAUDE.md brut dans un nouveau dépôt, ou ajoutez-le à la suite d'un dépôt existant. Il existe également une règle de projet Cursor versionnée, de sorte que les mêmes directives s'appliquent lorsque le dossier est ouvert dans Cursor — un détail qui indique que le fichier a été écrit pour être portable entre les outils qui lisent un fichier d'instructions au niveau du projet, et non lié au chargeur d'un seul fournisseur.

Un point délicat, qu’il vaut la peine de signaler, car vous le rencontrerez si vous suivez le README à la lettre. La commande marketplace indique forrestchang/andrej-karpathy-skills, tandis que l’URL du dépôt en haut de la page est multica-ai/andrej-karpathy-skills. Les deux chaînes apparaissent dans le même README, consulté le 23 octobre 2026. Je vois bien l’incohérence et je ne peux pas vous dire pourquoi elle existe, donc le conseil honnête est d’essayer l’autre chemin si l’un échoue, et de considérer l’une des deux chaînes comme obsolète.

L'autre chose à remarquer sur la page d'accueil : le dépôt est maintenu par multica-ai, et la citation en bloc d'ouverture du README fait la promotion de Multica, « une plateforme open source pour exécuter et gérer des agents de codage avec des compétences réutilisables ». Il s'agit d'une divulgation légitime, et c'est aussi un indice sur la raison pour laquelle le packaging se présente comme il le fait. Un projet intéressé par les compétences réutilisables est susceptible de livrer ses propres recommandations sous une forme installable, ce qui est le cas du plugin.

L'utiliser sans en hériter les présupposés

La section Personnalisation est celle que la plupart des lecteurs sautent. Le fichier est conçu pour être fusionné avec des instructions propres au projet plutôt que pour les remplacer, et les exemples qu'il donne sont concrets : utiliser le mode strict de TypeScript, tous les points de terminaison d'API doivent avoir des tests, suivre les modèles de gestion des erreurs existants dans un fichier particulier. Ce n'est pas de la décoration. C'est la différence entre un règlement générique et un ensemble d'instructions qui sait où vit votre code.

Il existe une raison pratique de fusionner plutôt que d’empiler. Si vous collez le fichier tel quel et que votre projet a ses propres conventions, les deux ensembles d’instructions peuvent se contredire, et un modèle qui réconcilie une contradiction est précisément la confusion que le premier principe cherche à éliminer. Rédiger vos conventions dans le même fichier, dans le même ton, maintient la surface d’instructions suffisamment petite pour être auditée.

Et vous devriez l’auditer, en effet. Il s’agit d’un court document d’instructions comportementales qui s’appliquera à chaque requête dans le dépôt. La bonne question n’est pas de savoir si 222 612 personnes peuvent se tromper — cette formulation ne règle rien —, mais si chaque règle correspond à une défaillance que vous avez réellement constatée. Si vos diffs n’ont jamais contenu de réécritures de commentaires effectuées au passage, la section « Modifications chirurgicales » vous coûte du contexte pour rien. Supprimez-la. Le fichier est sous licence MIT et destiné à être modifié.

Un niveau plus bas, rien de tout cela ne change le modèle qui répond. Un fichier CLAUDE.md façonne la manière dont une requête est traitée une fois qu’elle atteint un modèle ; il ne dit rien du modèle qui la reçoit. Cette seconde décision revient à ce qui se trouve devant le modèle. Une façon de l’organiser consiste en un point de terminaison unique compatible OpenAI proposant plus de 200 modèles sous une seule clé, avec bascule automatique entre fournisseurs et prix catalogue des fournisseurs répercutés à 0 % de marge. Nous hébergeons des modèles ; nous ne créons pas Claude Code, et rien dans votre dépôt ne nous est visible.

La recherche continuera de dire « skills », parce que c’est le mot que les gens emploient pour désigner une chose que l’on installe afin qu’un agent se comporte différemment, et l’habillage autour de ce dépôt l’utilise aussi. L’artefact est un fichier : un document d’instructions permanentes, rédigé en réponse à trois griefs précis, avec quatre principes et une série de tests que vous pouvez appliquer à la main. Jugez-le sur ce point : ces griefs ressemblent-ils à votre dépôt ? C’est une meilleure question que le nombre d’étoiles, qui n’a jamais mesuré que le nombre de personnes ayant eu la même réaction que vous venez d’avoir.