Karpathy Skills review: a single 186k-star CLAUDE.md that names how AI breaks when it codes

After reviewing superpowers, I kept scanning Claude Code repos and hit another one with a comparable star count: andrej-karpathy-skills, over 186,000 stars. But when I opened it, it was nearly the opposite of superpowers in every way. Superpowers is a dozen-plus skills with gates and machinery. This one is a single CLAUDE.md file, under seventy lines.

What can one file do to earn a couple hundred thousand stars? The answer is that it does not try to teach everything. It picks only the failure habits AI repeats when it writes code, and turns them into short rules the model follows. The source of those rules is a post by Andrej Karpathy on X about where models go wrong when they help you code.

This post goes in order: what it is and who made it, then the 4 principles it teaches, then how it differs from superpowers and which to pick, and finally whether you should install it and how to use it in your own work.

Part 1What karpathy skills is, and who made it

First, provenance, stated plainly: this repo is not from Andrej Karpathy himself. It was made by a third party (multica-ai, by Jiayuan Zhang) who took what Karpathy posted on X and arranged it into guidelines. The repo says so directly, calls itself Karpathy-Inspired, and links the source post so you can read it yourself. It uses an MIT license. This matters, because when you see a famous name on a repo you should be able to tell whether it is the person's own work or someone arranging their words. This is the latter, and it says so clearly.

The problem Karpathy described is the one many people hit with AI when it helps write code. He wrote, roughly, that models like to make assumptions on your behalf and run with them without checking, do not ask when things are unclear, like to overcomplicate code and bloat abstractions past what the task needs, and sometimes change or remove code they do not fully understand. This repo answers those habits with rules.

Part 2The 4 principles it teaches

The whole file boils down to 4 principles, each fixing one of the failures Karpathy named.

1. Think before coding have the AI surface the assumptions it is using, and ask when unclear, instead of silently picking a path and running with it. Stopping to ask when uncertain counts as doing it right, not as failing to finish.
2. Simplicity first write only the code the problem in front of you needs, do not build for a future that has not arrived. If a hundred lines will do, do not write a thousand.
3. Surgical changes touch only the lines that trace back to the request, do not refactor unrelated code along the way. There is a precise rule: clean up the orphans you just created yourself, but for code that was already dead, flag it, do not delete it on your own.
4. Goal-driven execution turn a vague task into a goal with a test that verifies it, then let the model iterate toward that goal, because a model's strength is looping and refining rather than understanding deeply in one pass.

What is neat is that the 4 connect into one chain. Most trouble starts from an unclarified assumption, then a silent guess, then overcomplicated code, then a drive-by refactor, ending in a vague goal that forces a rewrite. Each principle cuts one segment of that chain.

Its charm is not completeness but brevity. The whole file reads in a couple of minutes, and every line points at a real thing AI gets wrong, again and again.

Part 3How it differs from superpowers, and which to pick

If you read the superpowers review first, you will see these two repos solve the same problem, getting good practice into an AI, at completely different scales.

• karpathy skills one small file, principles to follow, suited to when a person supervises each turn, AI writes, human watches, in rounds. The principles keep each round from drifting.
• superpowers a dozen-plus skills with enforcement gates and machinery that injects them into the session, suited to when you let the AI run long on its own without watching each turn, which needs tighter rails.

They also differ in how they enforce. Superpowers does not trust a rule stated plainly to bind the AI, so it names the excuses the model would use to skip a rule, right in the instruction. karpathy skills lays out principles and trusts the judgment of the model and the human watching over it. Neither is better in the abstract, they answer different situations. Work where a human is present throughout, short principles are enough. Work you leave running, you need rails that are hard to step past.

Part 4Should you install it, and how to use it

Should you try karpathy skills?

It is worth a try, especially if you do not yet have a CLAUDE.md of your own, because it is very light, just a text file with nothing hidden. You can install it several ways: as a plugin, by copying the CLAUDE.md straight into your project, or by appending it to an existing one. The content is open under MIT, so you can read the whole file and take only the parts that fit your work.

The idea you can use right now

Even without installing the repo, its most distilled principle is this: stopping to ask when something is unclear has to count as doing it right, not as failing to finish. Most AI failures start exactly there, with the model guessing on your behalf and running on. If you write into your own rules file that it should ask first when unclear, you have already cut half the problem.

For my part, I took some of these principles and mixed them into the rules file and skills I already use, rather than adopting the whole file, because some of it overlapped with rules I already had. How I wired it into my own stack is a detail I am leaving out of this post, but the principle above you can use right away.

The one rule to remember

If you remember one thing from this post, let it be this: good practice does not have to arrive as a big kit. A repo with 186,000 stars is a single file that points at where AI goes wrong and writes a few short rules to guard against it. The size of a tool does not tell you how much it helps. What tells you is whether it names a real problem accurately.

This post is one layer in the 7-layer architecture of a production AI agent.