Karpathy Skills: One File That Makes Your AI Coding Agent Write Better Code

This is one file: a CLAUDE.md that improves Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls. Drop it into a project and the agent working in that project picks up a set of working rules. Nothing to build, nothing to configure, no service to sign up for. It had 229,304 stars when we checked on November 4, 2026, which makes it one of the most starred repositories on GitHub.

Get one thing straight first, because the name invites confusion: Andrej Karpathy did not make this. The repository is by multica-ai, and it is built from a post in which Karpathy described what frustrates him about AI coding. The file turns his observations into instructions an agent can follow. Credit the observations to Karpathy, and the file itself to the people who wrote it.

Why does a single text file get 229,000 stars? Because the problem it addresses is the one every developer hits within a week of using a coding agent: the agent does something plausible, fast, and slightly wrong, and you only discover it in review. These guidelines attack that failure mode directly instead of adding another tool on top of it.

Karpathy's post names three ways coding agents go wrong, and the file is organized as the answer to all three.

First, the models make wrong assumptions on your behalf and just run along with them without checking. They do not manage their confusion, do not seek clarifications, do not surface inconsistencies, do not present tradeoffs, and do not push back when they should. You ask for something slightly ambiguous and get a confident implementation of the wrong interpretation.

Second, they overcomplicate code and APIs, bloat abstractions, and do not clean up dead code. The README's version of this complaint is vivid: the agent implements a bloated construction over 1,000 lines when 100 would do. Third, they still sometimes change or remove comments and code they do not sufficiently understand as side effects, even when those lines are orthogonal to the task. A fix to one function quietly edits three others.

The file answers the three complaints with four principles, each stated as a rule the agent must follow.

Think Before Coding means do not assume, do not hide confusion, and surface tradeoffs. State assumptions explicitly, present multiple interpretations when ambiguity exists, push back when a simpler approach exists, and stop and ask when confused instead of guessing.

Simplicity First means the minimum code that solves the problem, nothing speculative. No features beyond what was asked, no abstractions for single-use code, no flexibility or configurability that was not requested, no error handling for impossible scenarios. The test the file gives is a good one: would a senior engineer say this is overcomplicated? If yes, simplify.

Surgical Changes means touch only what you must, and clean up only your own mess. Do not improve adjacent code, comments or formatting, do not refactor things that are not broken, and match existing style even if you would do it differently. If your changes orphan imports or variables, remove those. Do not remove pre-existing dead code unless asked. The test: every changed line should trace directly to the user's request.

Goal-Driven Execution means define success criteria and loop until verified. Turn "add validation" into "write tests for invalid inputs, then make them pass", and "fix the bug" into "write a test that reproduces it, then make it pass". Karpathy's own line behind this rule is that LLMs are exceptionally good at looping until they meet specific goals, so do not tell the agent what to do, give it success criteria and watch it go.

For a single project, the file itself is the install. Add the repository's CLAUDE.md to your project root and Claude Code picks it up as project instructions. For an existing project, append it to your current CLAUDE.md instead of replacing the project-specific guidance you already have. The guidelines are designed to merge with project-specific instructions, and the README shows how to add a project-specific section on top, for example TypeScript strict mode or API test requirements. If you merge it into a long existing CLAUDE.md, paste the result into a Markdown converter to check that the headings still render as separate sections instead of running together.

There is also a Claude Code plugin route documented in the README, which makes the skill available across all your projects rather than one at a time, and a committed Cursor project rule, so the same guidelines apply when you open the project in Cursor. If you use both Claude Code and Cursor, the Cursor setup is worth doing: the same four rules then govern the agent whichever editor you are in.

You will know it is working when diffs get smaller and cleaner: fewer unnecessary changes, fewer rewrites due to overcomplication, clarifying questions before implementation instead of after mistakes, and minimal pull requests with no drive-by refactoring. That is the outcome the file is optimizing for, and it is measurable in your very next review. The simplest test is to give the agent the same task with and without the file, then compare the two results in a text diff.

The guidelines bias toward caution over speed, and the README says so openly. For trivial tasks, simple typo fixes and obvious one-liners, use judgment: not every change needs the full rigor. Applying all four rules to a one-line fix is the kind of over-engineering the second rule is trying to kill.

The second watch-out is the name. Because the repository is called andrej-karpathy-skills and the star count is enormous, it is easy to repeat the claim that Karpathy built it. He did not. Saying so in a post or a video is the kind of small inaccuracy that undermines an otherwise good recommendation, so keep the attribution exactly as the repository states it: derived from Karpathy's observations.

Finally, remember what this is and is not. It is a text file of instructions, not a model, not a plugin with behavior of its own, and not a guarantee. An agent can still ignore instructions, and the rules work best when you also review the diff. What the file buys you is a much better default: an agent that asks before assuming, writes less code, touches only what you asked for, and proves its work with tests.