Andrej Karpathy Skills: The CLAUDE.md Ruleset for AI Coding Agents

What are the Andrej Karpathy skills?

The "Andrej Karpathy skills" is the popular name for a project whose README is titled Karpathy-Inspired Claude Code Guidelines: a single CLAUDE.md file designed to improve Claude Code's behavior, derived from observations Andrej Karpathy published about how LLM coding agents go wrong in practice. The project has struck a nerve — the repository has collected more than 227,000 GitHub stars, a sign of how many developers recognize the failure modes it describes.

Karpathy's post (linked from the project README) names three recurring problems:

"The models make wrong assumptions on your behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."

"They really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code... implement a bloated construction over 1000 lines when 100 would do."

"They still sometimes change/remove comments and code they don't sufficiently understand as side effects, even if orthogonal to the task."

One thing to be clear about: the project itself is community-built. Karpathy did not ship it — the README's author (who also works on Multica, an open-source platform for running and managing coding agents with reusable skills) distilled Karpathy's public observations into a ruleset you can adopt in your own workflow. It is MIT-licensed.

Positioning note for this directory's audience: this is a Claude Code plugin / CLAUDE.md file, not a native DeepSeek Harness (dsh) plugin. It still belongs on your reading list, because the four principles it encodes apply to any LLM coding agent — dsh included.

What rules does it encode?

One file, four principles, each mapped directly to one of the failure modes above.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

• State assumptions explicitly — if uncertain, ask rather than guess
• Present multiple interpretations — don't pick silently when ambiguity exists
• Push back when warranted — if a simpler approach exists, say so
• Stop when confused — name what's unclear and ask for clarification

2. Simplicity First

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 wasn't requested
• No error handling for impossible scenarios
• If 200 lines could be 50, rewrite it

The README's test: would a senior engineer say this is overcomplicated? If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

• Don't "improve" adjacent code, comments, or formatting
• Don't refactor things that aren't broken
• Match existing style, even if you'd do it differently
• If you notice unrelated dead code, mention it — don't delete it
• Remove imports, variables, or functions only when your changes made them unused

The test: every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified. Imperative tasks become verifiable goals: "add validation" becomes "write tests for invalid inputs, then make them pass"; "fix the bug" becomes "write a test that reproduces it, then make it pass"; "refactor X" becomes "ensure tests pass before and after". For multi-step work, the README suggests a plan shaped like:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

The key insight the README attributes to Karpathy: "LLMs are exceptionally good at looping until they meet specific goals... Don't tell it what to do, give it success criteria and watch it go." Strong success criteria let the model loop independently; weak ones ("make it work") require constant clarification.

The README also lists the signals that the guidelines are working: fewer unnecessary changes in diffs, fewer rewrites caused by overcomplication, clarifying questions arriving before implementation instead of after mistakes, and clean minimal PRs with no drive-by refactoring.

How to install

Option A: Claude Code plugin (recommended). From within Claude Code, first add the marketplace:

/plugin marketplace add forrestchang/andrej-karpathy-skills

Then install the plugin:

/plugin install andrej-karpathy-skills@karpathy-skills

This installs the guidelines as a Claude Code plugin, making the skill available across all your projects. Note the install source: the README's commands point at the forrestchang/andrej-karpathy-skills repository.

Option B: CLAUDE.md, per project. For a new project:

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

For an existing project, append to the file you already have:

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

The guidelines are designed to be merged with project-specific instructions, so appending to an existing CLAUDE.md is a supported path — add your own project rules underneath, such as "use TypeScript strict mode" or "all API endpoints must have tests". Cursor users get a committed project rule (.cursor/rules/karpathy-guidelines.mdc); the repository's CURSOR.md covers setup.

Do I need Claude Code?

The project is built for Claude Code: Option A installs as a Claude Code plugin, and Option B targets CLAUDE.md, Claude Code's project-instructions file. If that is your daily driver, install and move on.

If you use a different harness, the honest answer is: you don't need Claude Code to benefit, but you won't get the packaged experience. The payload is a plain markdown ruleset, so any agent that reads a project instructions file can apply the same text — paste the four principles into your own agent's instructions file and you have captured most of the value. A Cursor rule ships in the repository for the same reason.

Keep the README's tradeoff note in mind regardless of harness: these guidelines bias toward caution over speed. For trivial tasks — typo fixes, obvious one-liners — use judgment rather than the full rigor. The goal is reducing costly mistakes on non-trivial work, not slowing down simple tasks.

FAQ

Are the Andrej Karpathy skills an official Karpathy product? No. The repository distills observations Karpathy published publicly into a ruleset; it is a community project and MIT-licensed. Karpathy's posts are quoted in the README, but he did not build or endorse the package.

Should I install the plugin or use the CLAUDE.md approach? The README recommends the plugin: it applies across all your projects. The CLAUDE.md approach is per-project and mixes with your existing project rules — pick it when you want the guidelines scoped to one codebase.

Is this a DeepSeek Harness plugin? Not natively. It ships as a Claude Code plugin / CLAUDE.md file, not as a dsh plugin. The principles, however, are harness-agnostic — dsh users can adopt the same four rules in their own agent instructions.

Will it slow down simple tasks? That concern is addressed in the README itself: the guidelines bias caution over speed, and for trivial changes you should use judgment instead of applying the full process.

Does it work with Cursor? Yes — the repository includes a committed Cursor project rule at .cursor/rules/karpathy-guidelines.mdc, with setup explained in its CURSOR.md.

Related DeepSeek Harness plugins

The Karpathy ruleset is discipline you add through instructions; a lot of what it enforces can also come from harness tooling:

• Agents, Automation & Workflows — loops, sentinels, and multi-agent orchestration plugins that pair well with goal-driven execution.
• Plugin Tooling — plugin managers, templates, and verifiers for keeping your dsh setup lean and surgical.
• What is DeepSeek Harness? — new to dsh? Start here, then browse the directory.