claude-skills/engineering/karpathy-coder
Alireza Rezvani ebbf6b0872
Some checks failed
Sync Codex Skills Symlinks / sync (push) Has been cancelled
fix: v2.14.0 audit P0/P1 fixes (plugin updates, Codex, mirrors, script paths, two script bugs) (#1048)
* fix(plugins): bump all plugins to 2.14.1 and gate unbumped changes

Claude Code caches plugins by version. 70 of 104 plugins changed between
v2.12.0 and v2.14.0 without a bump, so claude plugin update reported
"already at the latest version" and existing installs never received the
v2.13/v2.14 fixes. Every plugin moves to 2.14.1 so stale caches refresh once.

check_plugin_versions.py (G11, blocking in ci-quality-gate) fails when a
plugin's payload, including symlinked vendor files, changes without a higher
version, and when marketplace.json and plugin.json disagree.
bump_plugin_versions.py sets both together.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(codex): stop installing all skills by default

With the full library (~380 skills) Codex drops every skill description from
its prompt budget, so it cannot pick skills. codex-install.sh now asks for
--category (comma-separated), --skill or an explicit --all, lists categories
when run without arguments, and warns when more than ~100 skills are
installed. The Windows installer and install docs follow.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(gemini): link whole skill folders and drop duplicate mirror entries

Each .gemini/skills entry held only a SKILL.md symlink, so the relative
scripts/ and references/ a skill points to were missing. Entries are now
directory symlinks (Gemini CLI 0.65 discovers them). Dual-published copies
with identical SKILL.md are listed once, commands and agents that share a
skill's name are skipped, fixtures under assets/ and vendor/ re-exports are
excluded, discovery is sorted so reruns are stable, and stale generated
entries are pruned. gemini skills list: 20 conflicts -> 1 (handoff, fixed
next). GEMINI.md documents folder trust and fixes a dead example path.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(handoff): rename the productivity skill to session-handoff

engineering/handoff and productivity/handoff both shipped a skill named
handoff. Claude Code namespaces them, but Codex, Gemini CLI, Vibe and Hermes
key skills by name and silently kept one. The productivity skill is now
session-handoff (handoff-productivity:session-handoff); its folder, plugin
manifest, hook script paths, command paths, mirrors, harness manifest and
docs page follow. /cs-handoff, /cs-handoff-setup and ~/.config/handoff are
unchanged; the plugin README carries a migration note.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(convert): include plugins whose SKILL.md is at the plugin root

convert.sh searched at -mindepth 4, which skipped boost-asio-pro, deepread,
hivemind, loop-library, minimalist, strict-api and swedish-mentor for every
converted tool (opencode, Cursor, Windsurf, Kilo, Augment, Aider,
Antigravity). It now searches from depth 2 and skips assets/ fixtures.
opencode conversion: 375 -> 382 skills.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(codex): keep skill-tester's sample fixture from loading as a skill

Codex scans installed skill folders recursively and picked up
skill-tester/assets/sample-skill/SKILL.md as 'sample-text-processor'.
The installer renames SKILL.md files under assets/ in the installed copy.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(plugins): address scripts via ${CLAUDE_PLUGIN_ROOT} in commands and agents

343 script invocations in 90 command/agent files across 36 plugins used
repo-relative or ../ paths. Plugin commands and agents run from the user's
project, so those paths only resolved inside a clone of this repo; in the
v2.14.0 evals the agent fell back to find / to locate scripts. Every one now
uses ${CLAUDE_PLUGIN_ROOT}/. Two cross-plugin calls (write-a-skill ->
karpathy-coder, c-level-agents cpo -> product-manager-toolkit) go through
vendor/ symlinks, per the repo's install-cache lesson.

check_paths.py (G1) now fails a plugin command or agent that invokes a
script without ${CLAUDE_PLUGIN_ROOT}; on the v2.14.0 tree it reports 279.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(month-end-close): treat opening-balance rows as balances and pair transpositions

On a bank and GL export that each begin with an 'Opening balance' row, the
matcher returned RECONCILED_WITH_ITEMS and told the user to book a 25,000.00
journal entry for the opening balance, and it reported a 7,980/7,890
transposition as two unrelated items. Opening rows are now balances: a
difference between them is reported as carried in from the prior period
(R5, blocks sign-off, never booked). Same-date digit transpositions pair into
one correcting entry. The GL file's 'memo' column is read as description.
The v2.14.0 eval fixture now proves 1,405.00 = 150 opening + 90
transposition + 1,200 outstanding check - 35 bank fee. Bundled copy synced.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(coding-agent-rollout): flag connection-URL passwords and production MCP servers

On a committed .claude/settings.json holding
env.DATABASE_URL=postgresql://admin:<password>@prod-db... and
enabledMcpjsonServers: ["postgres-prod"], the linter flagged neither: the
env check only matched token formats and KEY/TOKEN/SECRET names. S11 now
catches a password embedded in any connection URL (BLOCKER in shared files),
and new S13 warns when a shared file pre-approves an MCP server whose name
marks it as production. Bundled copy synced; --sample output unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* docs: changelog and lessons for the v2.14.0 audit fixes

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-10-22 09:50:05 +02:00
..
.claude-plugin fix: v2.14.0 audit P0/P1 fixes (plugin updates, Codex, mirrors, script paths, two script bugs) (#1048) 2026-10-22 09:50:05 +02:00
agents fix(agents): drop dead skills: values and ignored context: fork (from #939) 2026-10-21 06:59:27 +00:00
commands fix: phantom-path sweep — 888 unresolvable references to zero 2026-06-10 14:33:00 +00:00
hooks feat(engineering): add karpathy-coder — active coding discipline enforcer 2026-04-12 13:29:55 +02:00
skills/karpathy-coder fix(frontmatter): nest descriptive SKILL.md keys under metadata for Codex (#1027) 2026-10-21 06:56:10 +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.