Mastering Karpathy-Style AI Coding with andrej-karpathy-skills: A Complete Guide

What it is

Behavior constraints : translate Karpathy’s "model bad habits" into concrete rules stored in CLAUDE.md or an equivalent file.

Integration paths : a Claude Code plugin, a CLAUDE.md file at the project root, or Cursor project rules (optionally a Cursor Skill SKILL.md).

Positive/negative examples : the repository’s EXAMPLES.md shows the four principles in action.

The skill’s sole goal is to define how the code should be changed – fewer guesses, less bloat, and changes must be runnable and testable.

Four principles

Think before coding – the model asks clarifying questions before editing.

Simplicity first – prefer a hundred lines over a thousand; implement only what the requirement states.

Precise edits – modify only lines directly related to the current task; stray imports are removed, and existing messy code is only noted, not deleted.

Goal‑driven execution – avoid vague "optimize this" commands; instead, write a failing test, fix until it passes, then run the full regression suite.

LLMs excel at “loop until a clear success criterion is met” – you must tell them what “done” looks like.

Embedding the skill into your workflow

Path A – Claude Code plugin (recommended)

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

Note: the main repository is multica-ai/andrej-karpathy-skills ; the marketplace may list forrestchang/… . Use the actual plugin prompt you see locally.

Path B – Place CLAUDE.md at the repository root

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

Existing project – append instead of overwriting:

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

Then add any project‑specific guidelines, e.g.:

## Project‑specific guidelines

- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the error‑handling pattern in src/utils/errors.ts

Path C – Cursor .mdc rules

Use the .cursor/rules/karpathy-guidelines.mdc file in the skill repository (contains alwaysApply: true). To reuse in another project, copy the .mdc file into the other project’s .cursor/rules/ and merge or set priority. For a personal setup, symlink skills/karpathy-guidelines/SKILL.md to ~/.cursor/skills/.

Common pitfall: Cursor does not read .claude-plugin/ or CLAUDE.md by default; enable the rules via Cursor’s Settings → Rules.

After installation – what next?

The rules are already active; no special activation phrase is needed. The real work is changing how you talk to the model: replace “help me fix this” with a concrete contract that includes scope, acceptance criteria, and a step‑by‑step plan.

Quick self‑check (≈30 s)

Claude Code plugin – open a new session and ask “Does the root contain CLAUDE.md or the Karpathy constraints? Summarize the precise‑edit principle.” If the answer mentions “only modify related lines”, the rule is active.

Project CLAUDE.md – open the file and verify the four‑principle section is present.

Cursor – open Settings → Rules and confirm karpathy-guidelines appears; then ask the same self‑check question.

Prompt example for Claude Code

Bad prompt: Fix the user validation. Good “contract” prompt:

Task: Fix the “empty string email” crash in validate_user.py.

Scope: Only modify lines that read or strip the email field. Do not change unrelated functions, formatting, or add new dependencies.

Do not: Refactor unrelated code, add new username checks.

Acceptance:
1. Add a minimal pytest case where email="" and email="   " raise ValueError("Email required") and the test passes.
2. Run <code>pytest tests/test_validate_user.py -q</code> locally and ensure it passes.
3. After the change, <code>git diff</code> should only contain modifications to the email handling lines.

Please list your assumptions and the approximate line numbers you plan to edit; I will reply “OK” before you apply the patch.

Prompt example for Cursor

Contract prompt:

@validate_user.py

Task: Same as above (empty‑email crash). Test command: pytest tests/test_validate_user.py -q.

Please obey the Karpathy rules: first give assumptions and a minimal diff plan, I will confirm before you apply the patch.

Case study 1 – Precise edit for a bug

Background: a fictional validate_user function crashes when email is an empty string or whitespace, raising a KeyError.

Vague request

User validation has an issue, can you take a look?

The model may rewrite the whole function, add type hints, reformat code, and even improve unrelated validation, producing a 30‑line diff when only two lines need change.

Structured contract

Step 1: Send the contract from the previous section.

Step 2: Model replies with a plan, e.g.:

[Think before coding]
Current exception: email empty string still goes through “@” check and crashes.
Clarify: only handle empty string and whitespace, keep existing valid‑email logic.

[Precise edit plan]
Edit 2‑4 lines in <code>validate_user</code> to fetch email via <code>user_data.get('email','')</code>, strip, and check for emptiness.
Do not change: username branch, comment style, other ifs.

[Acceptance]
Run the provided pytest; it must pass.

Reply “OK” and I will confirm before you patch.

After approval, run the tests and git diff to verify the diff is limited to the email handling lines.

Case study 2 – Turning a vague requirement into a concrete contract

Background: a manager says “add a user‑export feature”.

Naïve request

Add an export‑users feature.

The model may generate a blanket export_users() that dumps the whole table to a local JSON file, ignoring privacy and performance.

Contract‑first approach

Prompt:

Requirement: Export user data.

Please do not write code yet. List the questions that must be clarified and give 2‑3 implementation paths with complexity and risk assessments.

At least clarify:
1) Scope: full export vs filtered results? Should data be anonymized?
2) Delivery: async background job with download link, synchronous API response, or admin‑page download?
3) Field whitelist: who defines it?

For each path, provide scenario, rough cost, and main risk.

After I choose, write the minimal implementation (keep it simple, no factory pattern unless explicitly requested).

If the skill is active, the model will first ask those clarification questions before producing code.

Case study 3 – Large feature broken into goal‑driven steps

Background: “add rate limiting to an API”.

Impulsive request

Add rate limiting to the API using Redis, be professional.

The model may propose a full Redis‑based solution with config center, monitoring, etc., violating the “simplicity first” principle.

Goal‑driven stepwise plan

Prompt:

Task: Add rate limiting to the API.

Principles: Karpathy skill – simplicity first, goal‑driven, each step independently verifiable.

Proceed in three steps, not moving to the next step until the previous one is verified:

1) Implement an in‑memory fixed‑window limiter for POST /search (10 requests/minute). Return 429 on the 11th request. Provide a curl loop example where the 11th call returns 429.
2) Extract the limiter into middleware and apply to /search and /users. Verify with pytest that both routes return 429 when limit exceeded.
3) Only if I later request “shared across instances”, replace the in‑memory store with Redis. Do not implement step 3 now.

Do not introduce new monitoring stacks or modify unrelated routes.

The model will produce small, testable increments instead of a monolithic change.

Three contract templates

Template A – Bug fix / small change

[Scope] Only change: ___
[Prohibit] Do not reformat, touch unrelated functions, or add undeclared dependencies
[Acceptance] Test command: ___ ; diff should be minimal
[Process] First give assumptions and line‑level plan, I will reply “OK” before you edit

Template B – Ambiguous requirement

[Stage] Clarify first, no code
[Output] List ambiguities + 2‑3 solution comparisons + recommended default
[Constraint] Simplicity first: choose the smallest implementation path

Template C – Large multi‑step task

[Split] Break into N steps, each ending with “Verification: ___”
[Rule] Do not start next step before previous verification passes
[Prohibit] Do not introduce all future extensions at once

How to know the skill is actually helping

Diffs become shorter and more accurate – changed lines directly match the request.

Fewer “write‑everything then redo” loops.

Most mistakes appear before code is written, not after a PR is merged.

PRs look like human submissions – no massive reformatting or hidden framework additions.

If diffs are still huge, the likely cause is a missing clear success criterion or conflicting AI rules.

Don’t overuse the skill

For trivial typos or single‑line edits, don’t force a full “assumptions + five‑step verification” contract.

High‑risk areas (auth, payments, concurrency, data migration) benefit from the full four‑principle rigor.

Resources

Main repository: https://github.com/multica-ai/andrej-karpathy-skills

Chinese README: https://github.com/multica-ai/andrej-karpathy-skills/blob/main/README.zh.md

Cursor usage guide: https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CURSOR.md

Positive/negative examples: https://github.com/multica-ai/andrej-karpathy-skills/blob/main/EXAMPLES.md

Original CLAUDE.md: https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md

License: MIT