Karpathy-inspired Claude Code guidelines: andrej-karpathy-skills explained (2026)

andrej-karpathy-skills is one of the most visible Claude Code community packages that answers a blunt question: how do you stop an AI coding agent from confidently doing the wrong thing? Maintainer forrestchang distilled Andrej Karpathy’s observations on LLM failure modes into a single CLAUDE.md—and wrapped it as a Claude Code plugin so the same guardrails can follow you across projects. The repository has attracted on the order of 30k+ GitHub stars and thousands of forks (exact counts change daily), which is a useful signal that teams want shared agent etiquette, not ad-hoc prompts.

This article is a field guide: what problem it solves, the four principles, how to install it, and how it fits next to agent skills and registries like explainx.ai.

TL;DR

The README also points readers who want a managed agents platform to Multica (open source).

The problem Karpathy named

The README quotes three recurring failure modes—paraphrased here with the same intent as the upstream post:

1. Silent assumptions — Models “make wrong assumptions on your behalf” instead of surfacing uncertainty, tradeoffs, or inconsistencies.
2. Overengineering — A tendency toward bloated APIs, unnecessary abstraction, and large diffs when a smaller change would do.
3. Collateral edits — Touching comments or code that was not part of the task, sometimes removing context the model did not fully understand.

Those bullets are not academic gripes; they show up as bad PRs, reverted commits, and lost trust in agent-assisted workflows. Packaging a counter-policy in CLAUDE.md makes the expectations durable and diffable like any other repo convention.

The four principles (and what each fixes)

The project organizes the remedy into four principles. This table mirrors the README’s mapping:

1. Think Before Coding

Intent: force explicit reasoning before keystrokes—state assumptions, spell out multiple interpretations when the prompt is ambiguous, push back when a simpler path exists, and stop to ask when something is unclear rather than guessing.

2. Simplicity First

Intent: minimum code that solves the request—no extra features, no abstraction for a one-off, no configuration surface nobody asked for, and no elaborate error handling for scenarios that will not occur. The README’s blunt test: Would a senior engineer call this overcomplicated?

3. Surgical Changes

Intent: touch only what the task requires; match local style; do not “clean up” unrelated code or comments; if you spot dead code outside scope, mention it instead of deleting it. Exception: remove orphans your change created (unused imports, dead helpers).

4. Goal-Driven Execution

Intent: replace fuzzy asks with checkable outcomes—for example, “add validation” becomes “write failing tests for invalid inputs, then make them pass.” The README cites Karpathy directly: models are strong at looping until a specific goal is met, so weak criteria (“make it work”) waste cycles.

For multi-step work, the template is simple: each step names a verify hook (command, test, or observable check).

Install paths (plugin vs per-project file)

Option A — Claude Code plugin (recommended in the README)

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

That path treats the guidelines like a cross-project capability inside Claude Code’s plugin model.

Option B — CLAUDE.md only

New project:

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

Existing CLAUDE.md (append):

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

After merging, add a project-specific section (TypeScript strictness, test commands, error-handling patterns) so global etiquette and local law do not fight each other—the README explicitly encourages that pattern.

A before/after example: Surgical Changes in practice

Reading the four principles in the abstract is easy to nod along to; seeing what they change in an actual diff is what makes teams adopt the CLAUDE.md. Take a common real-world prompt: "add input validation to the signup form handler."

Without the guidelines, an agent chasing "helpfulness" often produces something like this:

// Before: 12-line handler
export async function handleSignup(req: Request) {
  const { email, password } = await req.json();
  const user = await db.user.create({ data: { email, password } });
  return Response.json(user);
}

// After (unguided): 80+ lines, new abstractions, unrelated refactors
interface ValidationRule<T> { validate: (v: T) => boolean; message: string; }
class ValidationChain<T> { /* ...generic rule engine... */ }
class SignupValidator extends ValidationChain<SignupPayload> { /* ... */ }
export async function handleSignup(req: Request) {
  // renamed unrelated helper `db` to `database` "for clarity"
  // added a full password-strength scoring system nobody asked for
  // touched three other handlers to match the new naming
}

That is exactly the failure mode Karpathy described: silent assumptions ("they probably want a reusable validation framework"), overengineering (a generic ValidationChain<T> for one form), and collateral edits (renaming db across files). Nothing in the original prompt asked for any of it.

With Think Before Coding, Simplicity First, and Surgical Changes applied, the same prompt produces:

// After (guided): 6 new lines, scoped to the actual request
export async function handleSignup(req: Request) {
  const { email, password } = await req.json();
  if (!email?.includes('@')) {
    return Response.json({ error: 'Invalid email' }, { status: 400 });
  }
  if (!password || password.length < 8) {
    return Response.json({ error: 'Password must be at least 8 characters' }, { status: 400 });
  }
  const user = await db.user.create({ data: { email, password } });
  return Response.json(user);
}

The diff is reviewable in seconds, touches only the function in scope, and a reviewer can confirm correctness without re-learning a new abstraction. If the team genuinely needs a shared validation library later, that is a separate, explicitly-scoped task — not something an agent should infer from "add validation."

How andrej-karpathy-skills compares to other guideline systems

CLAUDE.md is not the only place teams encode agent behavior expectations. It is worth knowing how it sits next to the other common mechanisms:

The practical takeaway: CLAUDE.md-style guidance (with or without the Karpathy package) is a read, not enforced layer. It shapes the model's behavior the way a style guide shapes a new hire's first PRs—it does not replace CI. Teams that get the most value pair it with actual gates: a linter for formatting, tests for correctness, and CLAUDE.md for the softer judgment calls a linter cannot express, like "don't refactor code outside the ticket's scope."

Compared to a hand-written project CLAUDE.md with no upstream package, andrej-karpathy-skills' advantage is that the four principles are already battle-tested language other teams have converged on—so you are not drafting behavioral policy from scratch, and updates to the upstream repo (new edge cases the maintainer has hardened against) flow to you with a git pull or plugin update instead of a rewrite.

Common objections teams raise before adopting it

• "Won't this make the agent slower/more annoying to work with?" Yes, for trivial tasks—asking Think Before Coding to justify itself before fixing a typo is friction with no payoff. Most teams scope it: apply the full guidelines to anything touching more than a couple of files, and skip ceremony for one-liners.
• "We already have a style guide—why layer another file on top?" A style guide answers how code should look; these principles answer how the agent should decide what to change at all. They are complementary, not redundant—see the comparison table above.
• "What stops the model from ignoring the file under time pressure?" Nothing guarantees compliance—CLAUDE.md is context, not code. That is exactly why the README's four observable signals (smaller diffs, less churn, more clarifying questions, cleaner PRs) matter: they give you something to actually measure instead of trusting the policy blindly.

How you know it is working

The README lists four practical signals:

• Smaller diffs aligned with the actual request
• Less churn from overbuilt first drafts
• Clarifying questions before the wrong implementation lands
• Cleaner PRs without cosmetic or “while we are here” edits

Those line up with what engineering managers usually measure: rework rate, review noise, and time-to-merge.

How this pairs with explainx.ai skills

CLAUDE.md is an excellent repo-wide temperament layer. Agent skills (see what are agent skills?) are often domain playbooks: MCP integration, SEO/GEO content, PDF tooling, and hundreds of other specialties in the skills registry.

A pragmatic stack:

1. Root policy — Karpathy-style principles in CLAUDE.md (or the plugin equivalent).
2. Domain packages — Install only the skills you need from the registry so progressive disclosure stays lean.
3. Publishing discipline — If you ship public pages or listings, stack seo-geo-style guidance so human readers and citation-style AI surfaces get clear structure.

Rolling it out on an existing team

Dropping a new CLAUDE.md into a repo with an established workflow works better as a short rollout than a single commit everyone is expected to absorb silently:

1. Pilot on one repo or one squad first. Install the plugin or curl the file into a single active repository for a week before mandating it org-wide. You want real diffs to point to, not a theoretical policy.
2. Merge, don't overwrite, existing conventions. If the repo already has build commands, test invocations, or style notes in CLAUDE.md, append the Karpathy principles below them rather than replacing the file—see Option B above for the exact append command.
3. Tell reviewers what changed. The visible effect is smaller diffs and more clarifying questions from the agent mid-task. Reviewers who do not know that shift happened may misread a clarifying question as the model being unusually unsure of itself, when it is actually the policy working as designed.
4. Revisit after two weeks. Check whether the four signals (smaller diffs, less churn, more clarifying questions, cleaner PRs) actually showed up. If they did not, the file may be too generic for your stack—add the project-specific section the README recommends (test commands, TypeScript strictness, error-handling patterns) so the global etiquette has local teeth.

Tradeoffs (from the upstream README)

The guidelines bias toward caution over speed. For a one-line typo, full ceremony is wasted; for refactors touching money paths, auth, or data integrity, the same bias prevents expensive mistakes. Treat the file as a default stance, not a religion.

Bottom line

andrej-karpathy-skills turns a widely cited Karpathy critique into actionable agent policy: think first, keep changes small and purposeful, and define success in tests and checks so the model’s strength—iterating—works for you instead of against you.

Primary repo: forrestchang/andrej-karpathy-skills on GitHub · Source thread: Karpathy on X

Next reads on explainx.ai: What is CLAUDE.md? → · Agent skills: complete guide → · MCP explained → · Browse ranked skills →

Concepts and install commands summarized here follow the upstream README and CLAUDE.md as of 2026; star and fork counts on GitHub change over time. Verify plugin and CLI syntax against your current Claude Code release notes.