Content
75%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured discipline skill: concrete rules with self-tests per principle, executable tooling, clear reference-based disclosure, and sensible 'when to relax' scoping. The consistent weaknesses are moderate — no example script invocations, no explicit end-to-end usage workflow, and a hook reference pointing at a file missing from the bundle.
Suggestions
Add one example invocation per script with real arguments (e.g. 'python scripts/diff_surgeon.py --goal "fix auth bug" main.py') so the tooling is copy-paste ready rather than requiring --help discovery.
Include a short numbered usage sequence — apply principles while coding → run /karpathy-check → fix flagged violations → re-run until clean — to make the end-to-end workflow explicit.
Fix or remove the reference to hooks/karpathy-gate.sh since no hooks/ directory exists in the bundle, or ship the hook file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes Claude's competence — bullets, tables, and per-principle tests with no explanation of known concepts. Minor trimmable material exists: ~10 lines of borrowed Karpathy quotes and the tangential cross-tool compatibility table, keeping it just below the 'every token earns its place' level. | 4 / 5 |
Actionability | Concrete, executable guidance throughout: 'If you write 200 lines and it could be 50, rewrite it', the Instead-of/Transform-to table, a plan template, named scripts with detection scope, the /karpathy-check command, and a pre-commit hook. The gap is that scripts are only reachable via '--help' with no example invocations showing real arguments, so it falls short of fully copy-paste ready. | 4 / 5 |
Workflow Clarity | The plan template embeds verify checkpoints ('1. [Step] → verify: [check]') and Principle 4 defines the loop-until-verified pattern with a test-first transform table; the hook is explicitly non-blocking so no destructive/batch validation cap applies. No explicit end-to-end usage sequence (apply principles → run /karpathy-check → fix → re-run) keeps it below 5. | 4 / 5 |
Progressive Disclosure | The SKILL.md is a lean ~120-line overview with well-signaled, one-level-deep references: all three references/*.md files and all four scripts/*.py files referenced in the body exist and carry one-line descriptions. The dangling reference to hooks/karpathy-gate.sh, which does not exist in the bundle, is the notable organization gap that keeps it from 5. | 4 / 5 |
Total | 16 / 20 Passed |