karpathy-skill-creator

name

karpathy-skill-creator

description

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:

1. Outcome — What does this skill produce, given what input? (Concrete, not vague.)
2. Failure modes — What are the 3 most likely ways this goes wrong?
3. Success criterion — One verifiable sentence: what does a passing test look like?
4. 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:

1. Metadata (name + description) — always in context
2. SKILL.md body — in context when triggered
3. 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.

---

The Core Loop

Think (assumptions, success criterion)
  → Draft (minimum viable, explain the why)
    → Test (assertions first, parallel runs)
      → Review (user evaluates qualitative + benchmark)
        → Improve (surgical, changelog entry)
          → Repeat

Stop when:

• User says they're happy
• All feedback fields are empty
• Iterations stop moving the benchmark

For description optimization and packaging: follow skill-creator.