The Karpathy CLAUDE.md, Explained: One File Behind a Skills Search

On Google Trends, worldwide, over the past seven days and read on 23 October 2026, "karpathy skills" appears as a rising query under the "claude skills" seed. Anyone who follows that search lands in the same place: github.com/multica-ai/andrej-karpathy-skills, a repository that showed 222,612 stars on GitHub, read 23 October 2026. Its description does not contain the word skill at all. It reads: "A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls."

The gap between the query and the object is not a small technicality. A skill and a CLAUDE.md file are different mechanisms that do different work, and almost every claim people make about this repository either depends on knowing which one it is or quietly assumes the wrong one. The guidance inside is a single file. The repository around that file also carries a plugin manifest and a folder under skills, which is probably where the word in the search bar comes from. Separating the packaging from the payload is the first useful move here.

The numbers, all from GitHub and read on 23 October 2026: 222,612 stars, 22,321 forks, created 27 January 2026, last pushed 20 April 2026, MIT licence. That last pair is the interesting one. The repository has not received a push in roughly six months, and the star count kept climbing anyway.

The file does the work; the packaging explains the search term

Open the repository and the file listing makes the mismatch easy to see. There is CLAUDE.md at the root, and beside it CURSOR.md, EXAMPLES.md, a .cursor/rules folder holding the same guidelines as a Cursor project rule, a .claude-plugin folder, and a skills/karpathy-guidelines directory. The README's recommended install route is the plugin marketplace, and it describes the result as making "the skill available across all your projects".

So the search term is not wrong so much as imprecise. There is a skills folder. There is a plugin. What there is not, is a set of separate skills each doing a different job, which is the shape people usually mean by a skill pack: a folder holding a SKILL.md and whatever support files that capability needs, invoked for one task. Here the entire guidance is a single document of standing instructions, and the plugin exists to deliver that document into a project.

Whether that distinction matters to you depends on what you wanted from the search. If you were looking for a toolbox, this is not one. If you wanted a short rulebook that changes how a coding agent behaves across a project, that is exactly what it is, and it is worth understanding why someone would write it as a file rather than as skills.

The complaints it was written against

The README's stated source is a post by Andrej Karpathy on X, which the README quotes for three complaints about how models write code. They are worth reading in full, because the four principles map onto them almost one to one.

The first: models "make wrong assumptions on your behalf and just run along with them without checking," and "don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should." Note what is being described. This is not a complaint about wrong answers. It is a complaint about fluent wrong answers delivered without hesitation, where the uncertainty that should have produced a question instead produced confident code.

The second: they "really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code… implement a bloated construction over 1000 lines when 100 would do." That one is familiar to anyone who has asked for a feature and received a framework.

The third is subtler and, for anyone reviewing diffs, the most expensive: they "still sometimes change/remove comments and code they don't sufficiently understand as side effects, even if orthogonal to the task." An orthogonal edit to one comment is small on its own. Multiplied across a codebase, it is how a review queue fills with changes nobody asked for, and how a comment explaining a workaround disappears before anyone learns why the workaround existed.

Four principles, and the test each one leaves behind

The file encodes four principles. Each comes with a short set of rules, and two of them spell out a one-line test you can apply to a diff without installing anything. The rules are where the character of the file shows.

Think Before Coding

The heading's instruction is "Don't assume. Don't hide confusion. Surface tradeoffs." Under it: state assumptions explicitly and ask rather than guess; present multiple interpretations when the request is ambiguous; push back when a simpler approach exists; stop when confused, name what is unclear, and ask for clarification. This is aimed squarely at the first complaint. The mechanism is not "be more careful" — it is converting silent choices into visible ones, so that a reviewer can disagree before code exists rather than after.

Simplicity First

The rule is minimum code that solves the problem, with nothing speculative: no features beyond what was asked, no abstractions for single-use code, no flexibility or configurability nobody requested, no error handling for impossible scenarios, and "if 200 lines could be 50, rewrite it". The test is a single question — would a senior engineer say this is overcomplicated? — which is a judgement call, and openly so.

Surgical Changes

Here the file splits the instruction in two, which is the most useful thing in it. When editing existing code: don't improve adjacent code, comments or formatting; don't refactor what isn't broken; match the existing style even if you would do it differently; mention unrelated dead code rather than deleting it. When your own changes create orphans: remove the imports, variables and functions your changes made unused, but leave pre-existing dead code alone unless asked. The test is that every changed line traces directly to the request.

Goal-Driven Execution

Define success criteria and loop until verified. The README shows the transformation as pairs. Instead of "add validation", write tests for invalid inputs and then make them pass. Instead of "fix the bug", write a test that reproduces it and then make it pass. Instead of "refactor X", ensure tests pass before and after. For multi-step work it asks for a short plan in which each step names its own verification. The README quotes Karpathy again here: "LLMs are exceptionally good at looping until they meet specific goals… Don't tell it what to do, give it success criteria and watch it go."

A file, a skill and a plugin are three different things

It is worth being precise about the machinery, because the practical behaviour differs. CLAUDE.md is a project instruction file: text that Claude Code reads as standing context for a repository, present whether or not anyone asked for it this turn. A skill is a folder with a SKILL.md that describes when the capability should be used, loaded when a task calls for it and not before. A plugin is a distribution package, installed through a marketplace, that can carry skills, commands and other components. The distinctions are about when instructions enter the context and who decides, not about quality.

A CLAUDE.md is, in that sense, the bluntest of the three. It is always on in that project, it applies to every task in it, and it occupies context on every turn whether the work is a one-line typo fix or a migration. The file's own README acknowledges the cost in a section called Tradeoff Note: the guidelines bias toward caution over speed, and for trivial tasks — simple typo fixes, obvious one-liners — you should use judgment. It says the goal is reducing costly mistakes on non-trivial work, not slowing down simple ones.

That is a fair account of what a standing instruction file can do. It cannot add a capability the model does not have. It can only make the model's existing behaviour more or less likely. Which is why the file is written as constraints — don't do this, ask before that — rather than as encouragement to be better.

What 222,612 stars measure

They measure attention. That is not a dismissal and it is not nothing: a repository created in January 2026 and last pushed in April reached 222,612 stars and 22,321 forks by 23 October 2026, on GitHub, read that day, which means it was shared widely and forked by people who wanted a copy of their own. A star count is a reasonable proxy for how many people found something worth bookmarking.

It is not a proxy for effect, and the repository does not pretend otherwise. What is not published anywhere in it: any benchmark comparing outcomes with and without the file, any methodology for measuring whether it works, and any comparison against a control. There is no before-and-after on a real codebase, no reviewer study, no incident rate. A file like this is a hypothesis about model behaviour, elegantly stated, and nobody has run the trial.

What the README offers instead is a section called How to Know It's Working, which lists four things you might observe: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, clarifying questions arriving before implementation rather than after mistakes, and clean minimal pull requests. Those are sensible signals. They are also exactly what you would write if you had not measured anything, and they are self-reported by whoever is applying the file. Read them as a checklist to hold the file to in your own repository, not as evidence that it already passed.

What you actually type to install it

The README gives two paths. The recommended one runs inside Claude Code: add the marketplace, then install the plugin, after which the guidelines are present across projects rather than per repository. The second is per-project: fetch the raw CLAUDE.md into a new repository, or append it to an existing one. There is also a committed Cursor project rule, so the same guidelines apply when the folder is opened in Cursor — a detail that tells you the file was written to be portable across tools that read a project-level instruction file, not tied to one vendor's loader.

One rough edge, worth flagging because you will hit it if you follow the README exactly. The marketplace command names forrestchang/andrej-karpathy-skills, while the repository URL at the top of the page is multica-ai/andrej-karpathy-skills. Both strings appear in the same README, read on 23 October 2026. I can see the mismatch and cannot tell you why it exists, so the honest advice is to try the other path if one fails, and to treat one of the two strings as stale.

The other thing to notice on the front page: the repository is maintained by multica-ai, and the README's opening blockquote advertises Multica, "an open-source platform for running and managing coding agents with reusable skills." That is a legitimate disclosure, and it is also a clue to why the packaging looks the way it does. A project interested in reusable skills is likely to ship its own guidance as something installable, which is what the plugin is.

Using it without inheriting its assumptions

The Customization section is the part most readers skip. The file is designed to be merged with project-specific instructions rather than to replace them, and the examples it gives are concrete: use TypeScript strict mode, all API endpoints must have tests, follow the existing error handling patterns in a particular file. That is not decoration. It is the difference between a generic rulebook and an instruction set that knows where your code lives.

There is a practical reason to merge rather than stack. If you paste the file in as-is and your project has its own conventions, the two sets of instructions can disagree, and a model reconciling a disagreement is precisely the confusion the first principle is trying to eliminate. Writing your conventions into the same file, in the same voice, keeps the instruction surface small enough to audit.

And audit it you should. This is a short document of behavioural instruction that will apply to every request in the repository. The right question is not whether 222,612 people can be wrong — that framing settles nothing — but whether each rule matches a failure you have actually seen. If your diffs have never contained drive-by comment rewrites, the Surgical Changes section costs you context for nothing. Delete it. The file is MIT-licensed and meant to be edited.

One layer down, none of this changes which model answers. A CLAUDE.md file shapes how a request is handled once it reaches a model; it says nothing about the model that receives it. That second decision belongs to whatever sits in front of the model. One way to arrange it is a single OpenAI-compatible endpoint carrying more than 200 models under one key, with automatic failover across providers and provider list prices passed through at 0% markup. We host models; we do not make Claude Code, and nothing in your repository is visible to us.

The search will keep saying skills, because that is the word people have for a thing you install to make an agent behave differently, and the packaging around this repository uses it too. The artefact is a file: one document of standing instructions, written against three specific complaints, with four principles and a set of tests you can apply by hand. Judge it on whether those complaints sound like your repository. That is a better question than the star count, which only ever measured how many people had the same reaction you just did.