multica-ai /
andrej-karpathy-skills
A CLAUDE.md file that tells Claude Code to ask first, keep code small, edit narrowly
- 222.6k stars
- 6.2k stars since 3 Oct
- Updated 6 months ago
- Beginner friendly
- Agent skills & plugins
AI coding assistants often guess at what you meant and keep going. They also write far more code than the job needs, and sometimes change or delete code they don't understand. Andrej Karpathy described these habits in a post, and this repo turns his complaints into instructions for Claude Code.
The project is mostly one text file. Claude Code reads CLAUDE.md at the start of a session and treats it as standing instructions. The file holds four principles: think before coding, simplicity first, surgical changes, and goal-driven execution. The last one means turning a vague task into something checkable, such as writing a failing test and then making it pass.
The alternative is writing your own CLAUDE.md from scratch. This gives you a ready-made starting point that you can merge with project-specific rules. The README says the rules lean toward caution over speed, so for trivial edits you should use your own judgment. It also includes a Cursor rule file for the same guidelines.
What it does
Think Before Coding
Tells the model to state its assumptions, offer more than one interpretation when a request is ambiguous, and stop to ask when confused.
Simplicity First
Asks for the minimum code that solves the problem. No unrequested features, no abstractions for single-use code, no speculative configurability.
Surgical Changes
Limits edits to what the request needs and matches existing style. It mentions unrelated dead code instead of deleting it, and cleans up only what the model's own changes orphaned.
Goal-Driven Execution
Rewrites tasks as verifiable goals, for example writing a test that reproduces a bug and then making it pass, and asks for a short plan with a check at each step.
Two ways to install
Install it as a Claude Code plugin for all projects, or download or append the CLAUDE.md file to a single project. A Cursor rule file is included too.
What you could build
- Add it to a new project's CLAUDE.md so Claude Code asks clarifying questions before it writes code.
- Append it to an existing CLAUDE.md to cut drive-by refactors and keep pull requests small.
- Install it as a plugin to apply the same habits across all your Claude Code projects.
- Use it as a template and add your own project rules, such as strict TypeScript or required tests for endpoints.
- Study it as an example of turning a known list of model failure modes into written instructions.
Get started
In Claude Code, add the marketplace and install the plugin to use it everywhere. Or download CLAUDE.md into a project folder, or append it to the one you already have.
/plugin marketplace add forrestchang/andrej-karpathy-skills/plugin install andrej-karpathy-skills@karpathy-skillscurl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.mdCommands are copied from the project's README. Read it on GitHub for the full setup.
Anything better than andrej-karpathy-skills?
Strongest pick for its narrow job: a tiny, widely adopted CLAUDE.md that curbs bloated, guess-driven diffs. Nothing here does the same thing; look elsewhere only for reply style or a broader skill library.
-
i-have-adhdUse alongside
Use alongside it if agent replies are long and chatty; this shapes reply format (action first, numbered steps) while Karpathy's rules shape the code changes.
Trade-off: It only changes how the agent talks, not code quality, and adds another instruction file to your context.
-
skillsUse alongside
Pick it to tidy and tune your CLAUDE.md, including this one, and to get PR outline and code-explanation skills on top of the behavioral rules.
Trade-off: Smaller and more intermediate; it's a set of separate tools, not a ready-made behavior rulebook.
-
skillsUse alongside
Pick it to learn how to write your own skills or add ready-made document and development skills next to these behavior rules.
Trade-off: Example skills for specific tasks, not a rule set that fixes sloppy or oversized diffs.
More in Agent skills & plugins
superpowers
A set of skills that makes coding agents plan, test and review before they write code
mattpocock/skills
Small, editable agent skills for planning, testing and reviewing code with AI
ECC
Agents, skills, hooks and memory that add an engineering workflow to coding agents
anthropics/skills
Anthropic's example Agent Skills: folders of instructions Claude loads per task
ponytail
A skill that makes AI coding agents write the least code that works
gstack
Slash-command skills that give Claude Code roles like reviewer, QA and release engineer
addyosmani/agent-skills
A pack of 25 Markdown skills that guide AI coding agents from spec to ship
taste-skill
Agent skills that steer AI coding tools toward better layout, type and motion
archify
Agent skill that turns a description or a codebase into an interactive HTML diagram
impeccable
A design skill for AI coding agents that steers them away from generic frontend looks