Karpathy Skills on GitHub: Four Principles for Better AI Coding
Updated 2026-10-28 · West Mao
How can you ask a coding assistant to make fewer assumptions, avoid unrelated edits, and verify its work? Here are the four principles and practical ways to apply them in Claude Code, Codex, Cursor, and DeepSeek workflows.
What is Karpathy Skills?
The project organizes coding guidance around a CLAUDE.md file; the current repository also contains a Claude Code plugin, a skill file, and a Cursor project rule. The repository describes its guidance as inspired by Karpathy’s observations. That does not mean Karpathy created or officially maintains the repository. Its old address redirects to multica-ai/andrej-karpathy-skills.
These files are text instructions for a coding assistant. They can shape its workflow, but they do not replace tests, code review, permission controls, or a project’s business rules.
What do the four principles do?
| Principle | What to do | Example |
|---|---|---|
| Think before coding | State assumptions, surface ambiguity and tradeoffs, and clarify consequential uncertainty. | Confirm the trigger and expected outcome before fixing a payment issue. |
| Simplicity first | Build what is needed now; avoid speculative abstractions and configuration. | Do not build a general rules engine for a single form validation. |
| Surgical changes | Edit what the task requires, follow local conventions, and clean up unused code introduced by your changes. | Fix a button state without refactoring unrelated pages. |
| Goal-driven execution | Define observable success criteria, verify appropriately, and report limitations. | Reproduce a bug, fix it, run relevant checks, and confirm the original problem is gone. |
The guidelines favor caution and can add discussion time. Use judgment for trivial tasks; changes involving payments, data, or permissions may need stricter checks based on project requirements.
How do you use the guidelines with coding tools?
Claude Code: project instructions or plugin
Read the upstream CLAUDE.md first. For an existing project, merge relevant guidance into its current instructions and check for conflicts. Do not overwrite an existing file. The repository also offers a plugin; consult its README for current installation commands.
Codex: project instructions in AGENTS.md
Codex uses AGENTS.md for project guidance. Adapt the four principles to the existing file while retaining business constraints, test commands, and more specific project rules. Do not assume a Claude plugin installs directly in Codex or that both tools load instructions identically.
Cursor: project rules
Cursor supports .mdc rules under .cursor/rules and also supports AGENTS.md. The upstream repository includes a Cursor rule; review it and adjust its scope for your project. Check existing files before adding it.
DeepSeek workflows
If your coding tool uses a DeepSeek model, first check which project-instruction format the tool supports, then add the relevant principles there. The tool loads the rules into context; using DeepSeek alone does not mean a particular file is automatically loaded.
Review imported instructions and record the repository version or commit. Check conflicts with team rules and the current task using the instruction precedence of your tool.
What does this look like in a task?
This example prompt illustrates a form-validation task. It is an editorial example, not a reported hands-on test.
Fix the registration form: show a clear message when email is empty or invalid.
Inspect existing validation and state key assumptions; ask if ambiguity affects behavior.
Follow existing project conventions and change only files needed for this task.
Acceptance: empty and invalid emails are rejected; the existing valid-email flow still works.
Run relevant checks and report results and anything you could not verify.- Understand: find the existing validation and error display; establish what counts as valid input.
- Keep scope small: reuse existing logic where appropriate instead of introducing a general framework.
- Review the diff: check that edits are relevant and unrelated comments or behavior did not change.
- Verify: check empty, invalid, and valid inputs; run suitable tests and report any checks not performed.
How can you compare results across AI tools?
Claude Code, Codex, and Cursor differ in instruction entry points and execution environments. The rules alone do not show which tool performs best. Try a small controlled comparison:
- Use the same starting code, request, and acceptance criteria; record tool and model versions.
- For each tool, compare existing project instructions with those same instructions plus the four principles. Repeat runs and prevent earlier results from influencing later ones.
- Record acceptance results, unrelated edits, human interventions, time, and cost. Save diffs and test output.
- Review failure causes and interpret results against task complexity and sample size. A few trials provide only preliminary evidence.
How can you check whether the instructions are being used?
Ask the assistant to summarize relevant project conventions, then give it a small task with clear acceptance criteria. Look for relevant assumptions, a focused diff, and an accurate report of checks performed. If these are missing, check file location, working directory, loading rules, and conflicts. An assistant saying it read a file does not prove it followed every instruction.
Frequently asked questions
Is this an official skill published by Karpathy?
The repository describes itself as inspired by his observations. Do not equate the project maintainers with Karpathy.
Do I have to install the plugin?
No. Claude Code can use project instructions, and other tools can adopt the principles through their supported rules mechanisms. Consult each tool’s documentation for loading and precedence.
Will it make DeepSeek or another model produce correct code every time?
No. Results depend on the model, tool, context, and task. Tests and human review remain necessary.
Should I replace an existing instruction file?
Usually, review and merge applicable guidance instead. Overwriting can remove important business, permission, and verification requirements.