Karpathy Guidelines
Keep your coding agent from overbuilding, silent assumptions, and drive-by refactors by applying Karpathy-style behavioral rules during implementation and review.
Overview
Karpathy Guidelines is a journey-wide agent skill that steers coding agents toward explicit assumptions, minimal diffs, and verifiable success criteria—usable whenever a solo builder needs to curb overcomplication before
Install
npx skills add https://github.com/multica-ai/andrej-karpathy-skills --skill karpathy-guidelinesWhat is this skill?
- Four behavioral pillars: think before coding, simplicity first, surgical changes, and verifiable success criteria
- Forces explicit assumptions, visible tradeoffs, and pushback instead of silent interpretation
- Anti-YAGNI rules: no speculative features, abstractions, or error handling beyond the ask
- Surgical edit discipline: touch only required lines and leave unrelated code alone
- Biases toward caution over speed; author notes judgment still applies on trivial tasks
- Four numbered behavioral guideline sections in SKILL.md
Adoption & trust: 3.4k installs on skills.sh; 171k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent keeps adding unrequested abstractions, hiding uncertainty, and expanding diffs beyond the task you actually asked for.
Who is it for?
Solo builders who rely on agents for non-trivial features, refactors, or reviews and want a lightweight ritual against scope creep and silent guesses.
Skip if: One-line typo fixes or tasks where you already have an approved spec and only need execution with no judgment calls—though the author still allows judgment on trivial work.
When should I use this skill?
Writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
What do I get? / Deliverables
The agent states assumptions, proposes simpler approaches when relevant, limits edits to the requested surface area, and agrees on checkable success criteria before you merge.
- Code changes scoped to the request
- Explicit assumptions and success criteria stated in the session
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Before building a new UI flow, the agent lists assumptions about routing and states a simpler component structure instead of adding unused configurability.
While reviewing an agent PR, the skill limits edits to the files in scope and refuses drive-by reformatting of neighbors.
On a throwaway prototype, the agent pushes back on speculative error paths that the spike does not need yet.
For a hotfix, the agent rewrites an oversized patch down to the minimum lines that fix the reported bug.
How it compares
Use as standing agent conduct rules instead of hoping the model’s default “helpfulness” stays minimal on its own.
Common Questions / FAQ
Who is karpathy-guidelines for?
Indie and solo developers using AI coding agents who want Karpathy-inspired guardrails during implementation, code review, and refactors without installing a separate linter product.
When should I use karpathy-guidelines?
During Build when writing new backend or frontend code, during Ship when reviewing a large agent diff, during Operate when making a surgical production fix, and anytime the agent might overbuild or assume requirements you never stated.
Is karpathy-guidelines safe to install?
It is prose-only behavioral guidance with no shell or network hooks; review the Security Audits panel on this Prism page before enabling any third-party skill in your agent.
SKILL.md
READMESKILL.md - Karpathy Guidelines
# Karpathy Guidelines Behavioral guidelines to reduce common LLM coding mistakes, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls. **Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. ## 1. Think Before Coding **Don't assume. Don't hide confusion. Surface tradeoffs.** Before implementing: - State your assumptions explicitly. If uncertain, ask. - If multiple interpretations exist, present them - don't pick silently. - If a simpler approach exists, say so. Push back when warranted. - If something is unclear, stop. Name what's confusing. Ask. ## 2. Simplicity First **Minimum code that solves the problem. Nothing speculative.** - No features beyond what was asked. - No abstractions for single-use code. - No "flexibility" or "configurability" that wasn't requested. - No error handling for impossible scenarios. - If you write 200 lines and it could be 50, rewrite it. Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. ## 3. Surgical Changes **Touch only what you must. Clean up only your own mess.** When editing existing code: - Don't "improve" adjacent code, comments, or formatting. - Don't refactor things that aren't broken. - Match existing style, even if you'd do it differently. - If you notice unrelated dead code, mention it - don't delete it. When your changes create orphans: - Remove imports/variables/functions that YOUR changes made unused. - Don't remove pre-existing dead code unless asked. The test: Every changed line should trace directly to the user's request. ## 4. Goal-Driven Execution **Define success criteria. Loop until verified.** Transform tasks into verifiable goals: - "Add validation" → "Write tests for invalid inputs, then make them pass" - "Fix the bug" → "Write a test that reproduces it, then make it pass" - "Refactor X" → "Ensure tests pass before and after" For multi-step tasks, state a brief plan: ``` 1. [Step] → verify: [check] 2. [Step] → verify: [check] 3. [Step] → verify: [check] ``` Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.