claude-skills/engineering/karpathy-coder
Claude 6278f7302d
fix(skills): rewrite descriptions of 111 skills that never auto-triggered
A trigger sweep of all 389 skills (Sonnet, Claude Code 2.1.317, 2 realistic
prompts + 1 near miss each) found 112 skills that fired on neither prompt.
Their descriptions now lead with the job in the words a user types and name
the situations that should load the skill ("Use whenever the user ..."),
with script names dropped to stay within each old length (G12 unchanged or
smaller). reflect is left as is: its pilot rewrite measured worse.

Also: run_evals.py --trigger-only for sweeps, a trigger case for design-qa,
and plugin versions bumped for every changed plugin (G11).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L8KYFKBwgFwRBdcBaR6xCa
2026-11-03 10:41:50 +00:00
..
.claude-plugin fix(skills): rewrite descriptions of 111 skills that never auto-triggered 2026-11-03 10:41:50 +00:00
agents fix(agents): drop dead skills: values and ignored context: fork (from #939) 2026-10-21 06:59:27 +00:00
commands fix(commands): hide skill-wrapper commands from the model's skill listing 2026-10-30 17:14:41 +00:00
hooks feat(engineering): add karpathy-coder — active coding discipline enforcer 2026-04-12 13:29:55 +02:00
skills/karpathy-coder fix(skills): rewrite descriptions of 111 skills that never auto-triggered 2026-11-03 10:41:50 +00:00
README.md fix(karpathy-coder): pass 8-phase plugin audit + wire repo integration 2026-04-12 13:34:55 +02:00

karpathy-coder

Active coding discipline enforcer based on Andrej Karpathy's observations on LLM coding pitfalls.

Not just guidelines — ships Python tools that detect violations, a review agent, a slash command, and a pre-commit hook.

The 4 principles

# Principle What it prevents Tool that checks it
1 Think Before Coding Hidden assumptions, silent choices assumption_linter.py
2 Simplicity First Over-engineering, premature abstractions complexity_checker.py
3 Surgical Changes Diff noise, drive-by refactors diff_surgeon.py
4 Goal-Driven Execution Vague plans, missing verification goal_verifier.py

Quick start

# Install as Claude Code plugin
/plugin marketplace add alirezarezvani/claude-skills
/plugin install karpathy-coder@claude-code-skills

# Run before committing
/karpathy-check

# Or use individual tools from the shell
python scripts/complexity_checker.py src/ --threshold strict
python scripts/diff_surgeon.py --diff HEAD~1..HEAD
echo "I'll just export all user data" | python scripts/assumption_linter.py -
python scripts/goal_verifier.py plan.md

What's in the box

Piece Count Detail
SKILL.md 1 The 4 principles with context: fork for skill chaining
Python tools 4 complexity_checker, diff_surgeon, assumption_linter, goal_verifier — all stdlib-only
Sub-agent 1 karpathy-reviewer — runs all 4 principles against a diff
Slash command 1 /karpathy-check — one-command pre-commit review
Pre-commit hook 1 karpathy-gate.sh — non-blocking awareness gate
Reference docs 3 Full Karpathy context, 10+ anti-pattern examples, 4-level enforcement guide

The tools

complexity_checker.py (Principle #2)

Detects over-engineering: cyclomatic complexity, class density, nesting depth, function length, premature ABC/Protocol usage, import coupling.

python scripts/complexity_checker.py src/auth/ --threshold strict --json
# → score 72/100, 3 findings: nesting depth 6, function 'validate' 62 lines, 2 classes in 80 lines

Three threshold levels: strict (new code), medium (default), relaxed (legacy).

diff_surgeon.py (Principle #3)

Analyzes a git diff and flags lines that don't trace to the stated goal: comment-only changes, whitespace noise, style drift (quote swaps), drive-by refactors, docstring additions to unchanged functions.

python scripts/diff_surgeon.py                    # staged changes
python scripts/diff_surgeon.py --diff HEAD~3..HEAD # last 3 commits
# → Noise ratio: 23% (NOISY), 7 comment-only changes, 2 quote-style swaps

assumption_linter.py (Principle #1)

Reads a plan or proposal and flags hidden assumptions: "just" (hides complexity), "obviously" (unstated assumption), "should work" (hopeful, not verified), vague action verbs, unscoped user references, missing format specifications.

echo "I'll just add a function to export all user data" | python scripts/assumption_linter.py -
# → 3 findings: assumption-just, missing-format, scope-absolute

goal_verifier.py (Principle #4)

Scores each step of a plan for verification quality (0-3 per step). Flags vague criteria ("should work"), checks for final end-to-end verification, and recommends concrete checks.

python scripts/goal_verifier.py implementation-plan.md --json
# → 6 steps, 8/18 (44%), WEAK — 3 steps have no verification

Enforcement levels

  1. Passive — install plugin, principles load as context (~60% compliance)
  2. Active review — run /karpathy-check before commits (~85%)
  3. Pre-commit hook — wire karpathy-gate.sh via Husky (~95%)
  4. CI gate — add tools to GitHub Actions PR checks (~99%)

See references/enforcement-patterns.md for setup instructions at each level.

Cross-tool compatibility

The tools are pure Python stdlib. The principles work in any AGENTS.md-aware CLI (Codex, Cursor, Antigravity, OpenCode, Gemini CLI).

Attribution

Derived from Andrej Karpathy's X post on LLM coding pitfalls. The principles are Karpathy's observations; the tooling, enforcement patterns, and anti-pattern gallery are original.

License

MIT.