Use when creating a new Claude skill or improving an existing one. Applies Karpathy's four principles — think before drafting, simplicity first, surgical changes, goal-driven execution — as a governing discipline over the standard skill-creation workflow. Use this instead of skill-creator when you want skills that are lean, purposeful, properly architected around a concrete outcome, and self-improving over time.
Use when creating a new Claude skill or improving an existing one. Applies Karpathy's four principles — think before drafting, simplicity first, surgical changes, goal-driven execution — as a governing discipline over the standard skill-creation workflow. Use this instead of skill-creator when you want skills that are lean, purposeful, properly architected around a concrete outcome, and self-improving over time.
Karpathy Skill Creator
Creates Claude skills governed by Andrej Karpathy's four principles of disciplined AI execution, layered over the standard skill-creator workflow.
The Four Governing Principles
Apply these at every phase — not just once upfront:
Principle
In skill creation
Think before drafting
Surface assumptions, name trade-offs, define verifiable success before writing a single line of SKILL.md
Simplicity first
Minimum viable structure. No bundled files unless tests prove they're needed. Explain the why instead of adding more rules.
Surgical changes
During improvement, change only what feedback specifically named. Don't touch working parts.
Goal-driven execution
Write assertions before running test cases. "Done" must be defined before work starts.
Phase 1 — Think Before Drafting
Before any writing, answer these explicitly:
Outcome — What does this skill produce, given what input? (Concrete, not vague.)
Failure modes — What are the 3 most likely ways this goes wrong?
Success criterion — One verifiable sentence: what does a passing test look like?
Scope boundary — What is this skill explicitly NOT doing?
If you cannot answer #3, stop. Do not draft the skill yet. Clarify with the user first.
Then run the standard intake interview:
When should this skill trigger? (phrasing, context, symptoms)
What is the expected output format?
What tools, connectors, or data sources does it need? (check Claude connectors first, then Zapier/MCP for gaps)
What does it need to remember across sessions?
What does "early signal" or "good output" mean to this specific user?
Every skill should be bespoke. A skill built for your YouTube strategy should not look like someone else's, because your audience, positioning, and standards differ.
Phase 2 — Simplicity First: Write SKILL.md
Write the minimum viable skill. Start with the obvious structure; expand only when tests reveal gaps.
Lean checklist before saving:
Under 200 lines for most skills (300 max before restructuring into references/)
No bundled resources unless 2+ test cases independently created the same helper
Every instruction explains the why, not just the what
No all-caps MUSTs — if you feel the urge, reframe as an explanation of consequences
No features added "because they seem useful" — only what the stated outcome requires
Structure:
skill-name/
├── SKILL.md ← lean, purposeful, explains why
├── CHANGELOG.md ← one line per change + which failure it fixed
└── scripts/ ← only if test cases prove it's needed
references/ ← only for heavy reference material (>100 lines)
Use progressive disclosure:
Metadata (name + description) — always in context
SKILL.md body — in context when triggered
Bundled resources — loaded on demand only
For the full writing guide (output formats, examples pattern, writing style, domain organization): follow skill-creator.
Phase 3 — Goal-Driven Testing: Assertions Before Runs
Write assertions for each test case before spawning any runs. This is Karpathy's goal-driven execution applied to skill validation: define verifiable success first, then observe.
For each test prompt, draft assertions before launch:
{"id":1,"prompt":"User's realistic task prompt","assertions":[{"text":"Output contains a top-3 signal list"},{"text":"Each signal includes an actionability note"},{"text":"Output does not include generic AI news summaries"}]}
Then spawn with-skill and without-skill runs in the same turn — never sequential.
For all eval mechanics (workspace structure, grading, benchmark aggregation, generate_review.py, viewer): follow skill-creator.
Phase 4 — Surgical Improvement
Read feedback. List each specific failure verbatim. Change only those — nothing else.
Before editing SKILL.md, write:
Failures this iteration addressed:
1. [exact failure from feedback]
2. [exact failure from feedback]
Changes I'm making:
1. [change] → fixes failure #1
2. [change] → fixes failure #2
If a change isn't tied to a listed failure, remove it.
Self-check questions:
Would a simpler explanation fix this instead of a new rule?
Am I changing working sections out of habit or discomfort?
Is this change reducing complexity or adding it?
After each iteration, add one line to CHANGELOG.md:
2026-04-28: Reduced output to 3 signals max (eval-1: user said too many ideas)
2026-04-28: Added source-quality filter (eval-2: secondary sources surfaced as primary)
This changelog is the skill's long-term memory — it encodes what "good" means for this user and prevents regression.
The Super Skill Checklist
For skills beyond simple one-step utilities, verify all four levels before shipping:
Level
Question
Check
Creation
Is the skill architected around a concrete, verifiable outcome — not a generic description?
[ ]
Data
Does the skill have the tools, connectors, and data sources it needs to do real work?
[ ]
Memory
Does it know what to store across sessions (strategy context, feedback history, user preferences)?
[ ]
Self-improvement
Is there an explicit feedback → changelog → skill-update loop in place?
[ ]
A skill missing any level is not a super skill — it's a markdown file.
