Content
86%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 an exemplary deterministic router: dense routing table, precise commands, and an explicit guardrailed workflow. The only gaps are undefined placeholder details (pm substitution, hash generation) and the absence of an explicit post-write verification step.
Suggestions
Define the 'pm' substitution placeholder in the body or note that its value is emitted by detect_stack.py output, so the upsert_section.py invocation is fully self-contained.
Add an explicit post-write verification step to the workflow (e.g., re-read the upserted file to confirm content outside the markers is byte-identical before reporting success).
Briefly state how the marker hash is derived (or that upsert_section.py computes it), so 'Report: ... hash status' in step 7 is verifiable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is a lean routing table plus a 7-step workflow with zero padding and no explanation of concepts Claude already knows; every line (stack names, signature files, target outputs, commands) carries instruction. Matches the 'lean and efficient; every token earns its place' anchor. | 5 / 5 |
Actionability | Concrete executable commands are given ("python3 scripts/detect_stack.py --root .", "scripts/upsert_section.py --file <path> --content-file <ref> --hash --substitute pm=<pm>", exact marker format), plus a manual fallback. Not 5: the source of the "pm" substitution value and how the marker hash is produced are not defined in the body; not 3: the commands are real and executable, not pseudocode, with only minor gaps. | 4 / 5 |
Workflow Clarity | A clearly sequenced 7-step workflow with real checkpoints: "Never write before confirmation", confirmation step with dry-run/remove modes, "Never alter text outside the markers", and a determinism claim ("Re-running on unchanged code is byte-identical"). Not 5: no explicit post-write verification step (e.g., re-reading the upserted file to confirm content outside markers is intact) or error-recovery loop; not 3: checkpoints are explicit, not implicit. | 4 / 5 |
Progressive Disclosure | SKILL.md is a pure router: a routing table maps each detected stack to its exact reference file and load condition, and all 14 references/ files plus 2 scripts and 2 assets exist and are one level deep (reference files do not point to further reference files). Per-stack detail, baseline text, and the AGENTS.md section template are all correctly split out of the overview. | 5 / 5 |
Total | 18 / 20 Passed |