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.
The body is a tightly written, opinionated decision procedure with concrete commands, file paths, validation gates, and clear mode separation — it trusts Claude's competence and adds only domain-specific doctrine. Its main weaknesses are unspecified verification steps, a few pointers that name owners without paths, and one overloaded repair paragraph.
Suggestions
Specify how to run "Benchmark's pre-acceptance probe" and "the verification run" (command or recipe path), since both are treated as hard gates.
Give paths for the named-but-unlocated owners ("verify's command recipes", "the pstack block's Agent files rule") so the instructions are self-contained.
Move the teaching-sweep matching mechanics (word splitting, case rules, Chinese twins, hit grouping) into a reference file and keep only the command and decision rules inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with repo-specific directives and explains nothing Claude already knows; every section carries decision weight. Minor trimmable redundancy remains — the "harsh honest feedback" instruction appears in both the hard-cut gate and Output sections, and the teaching-sweep paragraph compresses too much mechanics into one block. Not 5 because of that repetition and overloading; not 3 because there is no unnecessary explanation. | 4 / 5 |
Actionability | Concrete, executable guidance is present throughout: the exact command `node tooling/scripts/teaching-sweep.mjs <API name>`, exact owner file paths, the five-step hard-cut gate, and an enumerated output contract. As an instruction-only skill code absence is not penalized, but several pointers lack paths or commands ("Benchmark's pre-acceptance probe", "verify's command recipes", "the pstack block's Agent files rule"), keeping it below the fully-executable anchor. | 4 / 5 |
Workflow Clarity | The two-pass decision sequence (ideal target then reality check), numbered repair steps with explicit validation (step 1 stop-and-route conditions, step 5 forward-testing without seeding), and error-recovery handling for failed generators form a clear sequence with most checkpoints present. Not 5 because "the verification run" and the pre-acceptance probe for design/review are named as gates but never specified as commands or steps. | 4 / 5 |
Progressive Disclosure | Doctrine is deliberately delegated one level deep to clearly signaled paths (`VISION.md`, `docs/vision/common.md`, `.agents/playbooks/references/architecture.md#audit`) with the explicit instruction to cite rather than restate, and no bundle files exist to add depth. Minor gaps: the teaching-sweep matching mechanics and the hard-cut gate are inlined at a level of detail that could live in a reference, and the referenced files are repo paths outside the skill bundle. | 4 / 5 |
Total | 16 / 20 Passed |