andrej-karpathy-skills: a CLAUDE.md that makes Claude Code ask before it edits

The failure mode this file is aimed at

The README quotes Andrej Karpathy on three specific behaviours: models that pick an interpretation silently and run with it, models that build a 1000-line construction where 100 lines would do, and models that edit comments and code they do not understand as a side effect of an unrelated task. The project's answer is not a tool. It is a prompt file. The intended reader is someone running Claude Code against a codebase they care about, who has watched a diff grow orthogonal changes and wants the agent to stop and ask instead. The repository is small by design: CLAUDE.md, a Cursor rule under .cursor/rules/, a plugin manifest under .claude-plugin/, and a skills directory.

Four principles, and what each one actually constrains

The file is a table of four rules, each mapped to one of the complaints above. Think Before Coding says state assumptions explicitly, present multiple interpretations when ambiguity exists, push back when a simpler approach exists, and stop when confused. Simplicity First bans features beyond what was asked, abstractions for single-use code, unrequested configurability, and error handling for impossible scenarios; its stated test is whether a senior engineer would call the result overcomplicated. Surgical Changes is the most concrete: do not improve adjacent code, do not refactor what is not broken, match existing style even if you would do it differently, and if you spot unrelated dead code, mention it rather than delete it. The rule draws a line between orphans your own change created, which you remove, and pre-existing dead code, which you leave alone. Goal-Driven Execution converts imperatives into verifiable goals, with a table of transformations such as turning "Fix the bug" into "Write a test that reproduces it, then make it pass," and asks for a short numbered plan with a verify step per item on multi-step work.

Installing it as a plugin or as a per-project CLAUDE.md

The README gives two install paths. The recommended one is a Claude Code plugin, run from inside Claude Code. First add the marketplace, then install the plugin.

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

The README states this makes the skill available across all your projects. Note that the marketplace path in the command is forrestchang/andrej-karpathy-skills, not the multica-ai path in the repository URL, so copy the command as written.

The second path writes the file into a project. For a new project, fetch it directly.

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

For an existing project, the README appends rather than overwrites, adding a blank line first so the new content does not run into whatever was already there.

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Because the file is meant to be merged with project-specific instructions, the README shows the shape of an added section: a Project-Specific Guidelines heading followed by rules such as TypeScript strict mode, tests on every API endpoint, and following the existing error handling patterns in src/utils/errors.ts. After either install path, the visible effect is behavioural, not structural: fewer unrelated lines in diffs, clarifying questions before implementation rather than after, and smaller pull requests. The README lists exactly those as the signs it is working.

The Cursor rule and the plugin layout

The repository ships a committed Cursor project rule at .cursor/rules/karpathy-guidelines.mdc, so the same guidelines apply when the project is opened in Cursor, and CURSOR.md covers setup and how to carry the rule into other projects. That is a second delivery channel for the same text rather than a second product. The .claude-plugin/ directory holds the manifest that makes the marketplace install work, and skills/ holds the packaged skill content. Anyone evaluating the repository should read CLAUDE.md first, since the plugin and the Cursor rule are wrappers around it. If the wording of the four principles does not match how you want your agent to behave, no amount of install plumbing changes that.

Where it costs you time instead of saving it

The README carries its own tradeoff note: these guidelines bias toward caution over speed, and for trivial tasks such as simple typo fixes and obvious one-liners the reader is told to use judgment, because not every change needs the full rigor. That is the honest limitation. A file that tells the agent to stop and ask when confused will, on an ambiguous but low-stakes request, produce a question where you wanted a commit. The four principles also have no enforcement mechanism. Nothing in the repository checks that the agent followed them; the README's own success indicators are things you observe in diffs and pull requests after the fact. And the file is advisory text, so it competes with whatever else is in your CLAUDE.md. If your project instructions already push hard in another direction, for example toward broad refactors, the two sets of instructions will conflict and the agent has to choose. There is no documented precedence rule for that case.

How it differs from a general agent skill collection

The closest comparison in the search data is andrej-karpathy-skills vs superpowers, and the difference is scope rather than quality. A general skill collection packages many capabilities that an agent can invoke: workflows, tool integrations, reusable procedures. This project packages one thing, a short set of behavioural constraints, and its entire content is a markdown file you can read in a few minutes. The practical consequence is that you can audit it completely before installing, which you cannot do with a large skill bundle, and that it will not add any new capability to your agent. It only changes how the agent behaves on work it was already going to do. If you want your coding agent to be able to do more things, this is the wrong repository. If you want it to do fewer unrequested things, the four principles are aimed directly at that.

Licence, maintenance signals and what to check first

The README states the licence is MIT, which permits use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a permissive licence and places no copyleft obligation on your project, but the repository does not include a separate LICENSE file in its top-level entries, so the licence statement lives in the README. If your organisation requires a standalone licence file for approval, that is a gap to resolve before adoption. On maintenance, no last push date is given anywhere in the repository listing, so there is no basis for describing the project as actively maintained; treat the current CLAUDE.md as the version you are adopting and re-read it if you pull a newer one, since the curl commands fetch from main and will silently give you whatever is there at the time. The upgrade cost is low in one direction and non-zero in the other: replacing the file is trivial, but any project-specific sections you appended to your CLAUDE.md will be sitting below the fetched content, and re-running the append command without cleaning up first will duplicate the guidelines. Verify three things before you commit: that you agree with the four principles as written, that your existing CLAUDE.md does not contradict them, and that the plugin install path resolves against forrestchang/andrej-karpathy-skills rather than the multica-ai repository name.

Editorial conclusion

Adopt it if you run Claude Code on a real codebase and your diffs keep picking up unrelated edits, or if you want the same rules available in Cursor through the committed .cursor/rules/karpathy-guidelines.mdc. Skip it for typo fixes and one-liners; the README itself says not every change needs the full rigor. Before relying on it, open CLAUDE.md in your editor and confirm you accept the four principles as written, because the file is the whole product and there is nothing else enforcing them.

Frequently asked questions

Official sources

1. Official README
2. Project repository