andrej-karpathy-skills

The Karpathy Skills GitHub repository might be the highest-leverage download on this entire list: a single CLAUDE.md file — no dependencies, no build step, nothing new to learn — that changes how Claude Code behaves in your project. Distilled from Andrej Karpathy’s widely shared observations about how large language models actually fail at coding, it has collected more than 225,000 stars and 22,000 forks. The Karpathy Skills GitHub project, published by multica-ai, is not a framework or a tool. It is a short set of behavioural instructions, in plain language, that tells the agent to stop making the mistakes experienced engineers keep reviewing out of its pull requests. The official home of the project is the multica-ai/andrej-karpathy-skills repository on GitHub, where you can browse the source code, releases and issue tracker.

What it is

CLAUDE.md is the file Claude Code reads automatically when a session starts in a project directory; it acts as persistent standing instructions for the agent in that codebase. This repository’s file answers a blunt diagnosis. Karpathy’s observations: models make wrong assumptions on your behalf and run with them without checking; they do not manage their own confusion or surface trade-offs; they do not push back when a request has a simpler shape; and they overcomplicate — building a thousand-line construction where a hundred lines would do, quietly editing code and comments they do not fully understand along the way. The file converts that diagnosis into behaviour: instructions phrased as how to act, not as theory about what good code looks like.

Key features

The whole product is four principles, each aimed at a named failure mode:

• Surface assumptions first — before coding, state interpretations and trade-offs explicitly, and push back when the request points the wrong way.
• Manage confusion — when something is ambiguous, stop and ask rather than silently picking a meaning and building on it.
• Simplicity over spectacle — prefer the smallest construction that solves the actual problem; no speculative abstractions or bonus architecture.
• Surgical changes — touch only what the task requires; leave unrelated code, comments and formatting exactly as they were.
• Zero-install format — one readable file is the entire product, and threaded through all four principles is a fifth habit: verify the work against the request before declaring it done.

Who it is for

Any team using Claude Code — the principles transfer to any agent that reads standing instruction files — that has reviewed agent pull requests and found them too long, too broad, or confidently aimed at the wrong interpretation of the ticket. Solo developers benefit too: the file acts as the senior reviewer looking over the agent’s shoulder between your own reviews. It will not help teams whose problem is model capability rather than model behaviour — if the agent cannot do the task at all, instructions about how to behave while doing it are not the bottleneck.

Getting started

Copy the CLAUDE.md from the Karpathy Skills GitHub repository into your project root — that is the entire installation, and it takes effect from the agent’s next session. Read it first, though: the file is short, and you should delete or soften any principle that fights your team’s established conventions before the agent starts enforcing someone else’s. Then judge it empirically — take the next few real tasks and count diff size, unrelated-file touches and assumption-driven rework against your recent baseline. Most teams feel the difference within the first review cycle.

Our take

We keep coming back to the economics of this: the most popular behaviour fix in agent tooling is a text file. It works because the failure modes it targets are real and daily — assumption, sprawl and quiet collateral edits cost more review time than syntax errors ever did. The limitations are the flip side of its simplicity: it is one file of general advice, tuned by nobody for your codebase, and principles can collide under pressure (surgical versus thorough is a daily tension). Treat it as the base layer you then customise, not the finished article. We walked through all four principles in our MTD blog analysis — read our full deep-dive — including where the guide gets in the way. Start with the Karpathy Skills GitHub file; then write your own.