andrej-karpathy-skills: The markdown patch that teaches Claude Code to behave like a senior engineer
A tiny Claude plugin turns Karpathy’s anti-overengineering rules into a practical workflow for minimal diffs, test-driven execution, and fewer AI self-inflicted wounds.
- This repo packages a philosophy about LLM failure modes as an installable behavior layer for Claude Code.
- Its real innovation is distribution, because prompt guidance becomes a reusable dependency instead of a paste-in note.
- The four rules push the model toward smaller diffs, fewer assumptions, and testable goals rather than cleverness.
- The project suggests that better agentic coding will come from governance of behavior, not just bigger models.
The weird part is the whole point. This repository is mostly markdown, but it behaves like infrastructure. Instead of asking you to remember Karpathy’s advice, it loads that advice into Claude Code as a living constraint set.
That matters because AI coding failures are usually not dramatic. They are mundane: wrong assumptions, sprawling abstractions, and helpful edits that break unrelated code. This repo treats those as workflow bugs, not personality quirks.
The strange power of a few markdown files
At a glance, forrestchang/andrej-karpathy-skills looks too small to matter. Then you realize the point is not size. It is that a handful of files can change how an agent thinks, chooses, and edits.
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 present tradeoffs, don't push back when they should.
That is the project’s core diagnosis. Claude Code is capable, but without guardrails it can turn confidence into churn. This repo tries to reduce churn by making restraint part of the installation.
What the repository actually ships
The structure is simple and deliberate. The root CLAUDE.md gives project-level instructions. The skill file, skills/karpathy-guidelines/SKILL.md, packages the same philosophy for Claude Code’s skill system. EXAMPLES.md gives the model contrast cases. .claude-plugin/marketplace.json turns the whole thing into something you can install instead of copy by hand.
The four constraints that change the output
The repo’s philosophy collapses into four rules. First, think before coding. Second, keep it simple. Third, make surgical changes. Fourth, work toward a testable goal. None of these are groundbreaking in isolation. The difference is that they are written as operational constraints for a machine that otherwise wants to move fast and explain itself later.
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.
That last point is the subtle one. The repo does not just ask for obedience. It redirects the agent toward outcomes that can be checked. That is a better fit for coding than vague instructions, because code either passes or it does not.
The most useful rule may be the simplest: do not improve adjacent code. That sounds almost rude until you have watched an assistant refactor half a directory to solve a one-line bug.
Why “don’t improve adjacent code” matters most
This repo understands something many prompt files miss. In professional codebases, the biggest cost of AI assistance is often not incorrect logic. It is collateral damage. A clean diff is often more valuable than a clever one.
That makes the project less like a style guide and more like a treaty. It tells the model where not to roam. It asks for targeted movement, not exploratory renovation.
Examples as a negative dataset
EXAMPLES.md does more than demonstrate the right answer. It names the wrong reflexes: over-abstracting, creating needless indirection, and turning a small problem into an architecture exercise. That is useful because LLMs often learn boundaries better from contrasts than from abstract warnings.
| Pattern | Manual prompt snippets | andrej-karpathy-skills | Generic assistants |
|---|---|---|---|
| Setup effort | Low, but repeated every session | Low after install | Low to medium |
| Reusability | Weak, copied by hand | Strong, installed as a skill | Strong, but generic |
| Behavioral specificity | Varies by author | High, opinionated and narrow | Medium, tool-defined |
| Diff discipline | Depends on user memory | Explicitly enforced | Inconsistent |
| Test-loop orientation | Optional | Central | Often present, but not the headline |
| Distribution model | Paste and hope | Plugin or repo file | Closed product defaults |
The point of the examples is not to show off best practices. It is to pin down the failure shape. Once the model sees what not to do, the rules stop being abstract and start acting like a fence.
Why the plugin packaging matters
The packaging is the story. A prompt in a README is advice. A prompt inside a plugin manifest is a dependency. That shift changes how people trust it, share it, and keep it in sync with a workflow.
That is also why this repo feels bigger than it is. It points to a future where behavioral boundaries are versioned artifacts, not one-off reminders. You do not just invoke a model. You install the norms that shape it.
How it compares to other ways of steering AI coding
The contrast is not really about winner and loser. It is about control surface. Copilot, Cursor, and raw Claude instructions all help, but they live at different levels of specificity. This repo is narrow on purpose, and that narrowness is the advantage.
| Approach | What it optimizes | Strength | Weakness |
|---|---|---|---|
| Generic prompt files | Ad hoc guidance | Fast to try | Easy to drift |
| Raw CLAUDE.md | Project-level instruction | Simple and local | Harder to distribute cleanly |
| andrej-karpathy-skills | Behavioral constraint | Opinionated, installable, repeatable | Works best for teams who want this exact philosophy |
| Broader coding assistants | General productivity | Integrated experience | Less explicit about code discipline |
If you want a philosophy, this repo gives you one. If you want a product, it gives you an install path. That combination explains why a few markdown files can attract outsized attention.
What this says about agentic coding
The real lesson is not that prompts matter. Everyone already knows that. The lesson is that the next layer of AI tooling may be governance: constraints, defaults, and distribution mechanisms that shape model behavior before the first line of code is written.
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.
That is why this repository feels like an early signal, not a gimmick. It packages judgment. And in agentic coding, packaged judgment may become as important as model quality.
