Karpathy Guidelines (andrej-karpathy-skills)

What It Does

This repo distills four coding-discipline principles from a single Andrej Karpathy tweet (x.com/karpathy/status/2015883857489522876) about where LLMs go wrong when writing code, and ships them as a behavioral guardrail you paste into any agentic coding tool. The four principles are: Think Before Coding (surface assumptions, do not guess silently), Simplicity First (minimum code, no speculative abstractions), Surgical Changes (touch only what the task requires), and Goal-Driven Execution (turn vague tasks into verifiable success criteria with test-first loops). The same 65-line ruleset is delivered three ways: a root CLAUDE.md for per-project Claude Code use, a skills/karpathy-guidelines/SKILL.md in the agentskills.io format, and a .cursor/rules/karpathy-guidelines.mdc with alwaysApply:true for Cursor. A 522-line EXAMPLES.md provides concrete before-and-after code for each principle. The target user is any developer whose coding agent overcomplicates output, makes silent assumptions, or makes drive-by edits.

The Good

The four principles are specific, falsifiable, and traceable to a real source. Each principle names the exact anti-pattern it targets and offers a concrete test. "Surgical Changes" gives the rule "every changed line should trace directly to the user's request." "Simplicity First" gives "would a senior engineer say this is overcomplicated? If yes, simplify." These are checkable, not vibes. The README quotes the three Karpathy passages the principles derive from, so a reader can verify the lineage rather than trust a paraphrase.

The three delivery formats are byte-identical in the principles section. CLAUDE.md, SKILL.md, and the Cursor rule contain the same four sections word-for-word (verified programmatically, 4 of 4 match). This matters because drift between formats is the silent failure mode of multi-target rule files. The CURSOR.md doc explicitly tells contributors to keep all three in sync when editing.

The 522-line EXAMPLES.md is the real payload. Each principle gets two worked examples showing a wrong LLM output and a corrected one, with the problems enumerated line by line. The over-abstraction example (a 30-line strategy-pattern discount calculator reduced to a one-line function) and the drive-by-refactoring diff (where the agent reformats quotes and adds type hints while fixing an unrelated bug) are the kind of concrete artifact that makes a prompt contract land. The closing anti-pattern table and the "good code solves today's problem simply, not tomorrow's prematurely" line are quotable.

Install is one command and verified working across hosts. skills.sh recognizes the repo and lands the SKILL.md correctly. I verified npx skills add multica-ai/andrej-karpathy-skills --agent claude-code -y writes to ./.claude/skills/karpathy-guidelines/ and --agent hermes-agent -y writes to ./.hermes/skills/karpathy-guidelines/ (plus a skills-lock.json). The Claude Code plugin path (marketplace.json plus plugin.json) is also valid JSON and present, though the README's documented plugin commands still reference the old owner path.

The Bad

No LICENSE file in the repo despite claiming MIT in three places. The README says "MIT", the SKILL.md frontmatter says license: MIT, and plugin.json says license: MIT. But there is no LICENSE, LICENSE.md, or LICENSE.txt file anywhere in the tree, and the GitHub API returns 404 for the license endpoint (license: null). For a 201K-star repo with 20,702 forks, this is a real legal gap: forks and downstream reuse have no machine-readable license grant. The claim is also unverifiable without the file.

The README install instructions are stale after a repo transfer. The repo moved from forrestchang/andrej-karpathy-skills to multica-ai/andrej-karpathy-skills, but the README still references forrestchang in 3 places (the plugin marketplace add command, and both curl install commands). GitHub redirects the old path so the commands still work, but they are stale. Open issue #189 is a community PR to fix exactly this. The marketplace.json owner field also still says forrestchang.

No Hermes or OpenClaw install doc in the README. The README documents only the Claude Code plugin and a CLAUDE.md curl, plus the Cursor rule. It never mentions Hermes Agent or OpenClaw, even though skills.sh supports both (hermes-agent and openclaw are in the valid agent list and I verified the Hermes install lands correctly). A reader who finds this repo via a Hermes context would not know the skill is installable for their host without trying skills.sh themselves.

No releases, no tags, no CHANGELOG, and the repo has not been pushed in nearly four months. 28 commits, 8 contributors, last push 2026-04-20 (as of the 2026-08-12 test). The plugin version is frozen at 1.0.0 with no semver history to pin or diff. For a skill whose value is entirely in prompt wording, the absence of any version trail means a user cannot tell whether the guidelines have been refined since they last read them.

Issue #191 raises a legitimate applicability concern. A community member filed "per Guideline #2, Claude 5 models should skip this file," arguing that newer frontier models may already internalize the simplicity discipline and could be slowed by the always-on caution bias. The README itself acknowledges the tradeoff ("these guidelines bias toward caution over speed"), but the alwaysApply:true Cursor setting means the ruleset is on for every task including trivial ones, with no model-conditional gating. This is an open question, not a defect, but it is worth flagging for anyone wiring this in globally.

Smoke Test Results

All testing on macOS (host), aarch64. The repo was cloned from GitHub (9 files, 1,134 lines, 28 commits). Because this is a doc-only prompt contract with no executable code, the smoke test is structural validation plus install verification rather than a runtime test.

Run A -- Structural validation (fresh clone)

$ python3 /tmp/karpathy_test.py
SKILL.md frontmatter: name=karpathy-guidelines, description (219 chars), license=MIT
plugin.json: valid JSON, name=andrej-karpathy-skills, version=1.0.0, skills=["./skills/karpathy-guidelines"]
marketplace.json: valid JSON, name=karpathy-skills, 1 plugin
Local links: 13 total, 0 broken
All 4 principles present in CLAUDE.md, SKILL.md, .cursor rule
CLAUDE.md principles match SKILL.md: 4/4
CLAUDE.md principles match cursor rule: 4/4
Karpathy tweet ref present: x.com/karpathy/status/2015883857489522876
LICENSE file present: False

[FAIL] LICENSE file present in repo
22 of 23 checks passed

Pass rate: 22 of 23. The single failure is the missing LICENSE FILE. Everything else (frontmatter, manifests, cross-references, content consistency across the three delivery formats, Karpathy source attribution) passes.

Run B -- with-deps (skills.sh install verification)

$ cd /tmp/karpathy-install-test && npx skills@latest add multica-ai/andrej-karpathy-skills --agent claude-code -y
◇ Source: https://github.com/multica-ai/andrej-karpathy-skills.git
◇ Repository cloned
◇ Found 1 skill
● Skill: karpathy-guidelines
◇ Installation complete
✓ karpathy-guidelines (copied) -> ./.claude/skills/karpathy-guidelines

$ cd /tmp/karpathy-hermes-test && npx skills@latest add multica-ai/andrej-karpathy-skills --agent hermes-agent -y
◇ Found 1 skill
✓ karpathy-guidelines (copied) -> ./.hermes/skills/karpathy-guidelines
+ skills-lock.json written

Pass rate: 2 of 2. skills.sh install verified working for both Claude Code and Hermes Agent. The SKILL.md lands with intact frontmatter (name, description, license). This is the canonical install verdict.

Run C -- Functional verification (content integrity)

$ diff <(sed -n '/## 1. Think Before Coding/,/## 4. Goal-Driven Execution/p' CLAUDE.md) \
 <(sed -n '/## 1. Think Before Coding/,/## 4. Goal-Driven Execution/p' skills/karpathy-guidelines/SKILL.md)
(no output = identical)

$ python3 -c "import json; json.load(open('.claude-plugin/plugin.json')); json.load(open('.claude-plugin/marketplace.json')); print('both valid')"
both valid

$ curl -sIL https://x.com/karpathy/status/2015883857489522876 | head -1
HTTP/2 200

Functional pass rate: 3 of 3. The principles section is byte-identical between CLAUDE.md and SKILL.md, both plugin manifests parse as valid JSON, and the cited Karpathy tweet resolves (HTTP 200). I could not run a model-in-the-loop behavioral test (whether an agent actually changes behavior with the ruleset loaded), so the functional verdict stays partial rather than yes.

What the runs tell you

The skill installs cleanly and its internal consistency is airtight: the three delivery formats agree, the manifests validate, the links resolve, and the source attribution is real. The only structural defect is the missing LICENSE file. The one thing no smoke test can settle is whether loading these four principles actually changes a given model's output, which is the entire point of the skill. That depends on the model and the task, and issue #191 is evidence the community is already debating it.

Setup Walkthrough

1. Fastest path (skills.sh, any host): run npx skills@latest add multica-ai/andrej-karpathy-skills --agent claude-code -y (or replace claude-code with hermes-agent, cursor, codex, or any of the 70-plus agents skills.sh supports). This copies the SKILL.md into the right host directory and writes a skills-lock.json.
2. Claude Code plugin path: inside Claude Code, run /plugin marketplace add multica-ai/andrej-karpathy-skills then /plugin install andrej-karpathy-skills@karpathy-skills. Note the README still documents the old forrestchang/... path, which redirects but is stale.
3. Per-project root file (simplest): curl -o CLAUDE.md https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md. To append to an existing CLAUDE.md, use curl ... >> CLAUDE.md.
4. Cursor: the committed .cursor/rules/karpathy-guidelines.mdc with alwaysApply: true is picked up automatically when you open the repo in Cursor. For other Cursor projects, copy that file into the project's .cursor/rules/ directory.

Gotcha: the README's curl and plugin commands point at forrestchang/andrej-karpathy-skills. They still work via GitHub redirect, but if you want the canonical path, swap forrestchang for multica-ai.

Alternatives

1. 0xwilliamortiz/andrej-karpathy-skills -- a second, smaller "karpathy-skills" repo (161 stars) that distills behavioral guardrails from Karpathy's field notes rather than the single tweet. Different source material, narrower scope. Prefer if you want the field-notes framing over the tweet framing.
2. obra/superpowers -- the #1 most-starred agent-skill repo overall (268K stars), a large multi-skill framework that includes writing-plans and other discipline skills. Far broader than this single ruleset. Prefer if you want a full skill library rather than one guardrail.
3. A hand-written CLAUDE.md -- the four principles are short enough that an experienced developer could write an equivalent ruleset tailored to their stack and team conventions in 15 minutes. Prefer if you want project-specific rules rather than a general-purpose guardrail.