Content
82%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-engineered, token-efficient router with concrete, bundle-verified commands and strong write-safety gating (confirmation, marker confinement, idempotency). The main gaps are unattributed CLI modes, three orphaned bundle files invisible to navigation, and the absence of an explicit post-write verification loop.
Suggestions
Attribute the --dry-run, refresh, and --remove modes to scripts/upsert_section.py (detect_stack.py only supports --root and --max-depth), so the reader knows which invocation implements each mode.
Reference references/repository-workflow.md and references/apply-plan.md / scripts/apply_guidelines.py from the workflow — or remove them from the bundle — since roughly 10KB of guidance, including evidence-gathering instructions marked 'Read this during every setup or refresh', is currently unreachable from SKILL.md.
Add an explicit post-write verification step (e.g., re-run upsert_section.py --dry-run and confirm exit 0 and intact markers/links) to close the feedback loop for these batch writes.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is a lean operational router — a dense routing table plus a 7-step workflow — with no explanation of concepts Claude already knows and every line actionable ('Run python3 scripts/detect_stack.py --root .'); not 4 because no section could be trimmed without losing operational content. | 5 / 5 |
Actionability | Commands are concrete and verified against the bundle ('python3 scripts/detect_stack.py --root .', 'scripts/upsert_section.py --file <path> --content-file <ref> --hash --substitute pm=<pm>', the exact marker pair) with a manual fallback for missing python3. Not 5: step 3's '--dry-run', refresh, and '--remove' modes are not attributed to any script — they exist only on upsert_section.py, not detect_stack.py — and the source of the '<pm>' substitution value is unstated. | 4 / 5 |
Workflow Clarity | Clear 7-step sequence with safety checkpoints: git-status inspection ('Never overwrite uncommitted user changes'), a confirmation gate ('Never write before confirmation'), marker confinement ('Never alter text outside the markers'), and idempotency ('Re-running on unchanged code is byte-identical'). Not 5: no explicit post-write validate-and-retry feedback loop for these multi-file batch writes, though dry-run support and hash reporting partially cover verification — enough to stay above the cap-at-3 case. | 4 / 5 |
Progressive Disclosure | The routing table signals one-level-deep references clearly, and every referenced path (14 reference files, both scripts, both assets) verified to exist on disk. Not 5: three bundle files — references/apply-plan.md, references/repository-workflow.md, and scripts/apply_guidelines.py — are never referenced from the body; repository-workflow.md even self-describes as 'Read this during every setup or refresh' yet is unreachable via SKILL.md navigation. | 4 / 5 |
Total | 17 / 20 Passed |