Content
85%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 dense, actionable execution contract with excellent sequencing, explicit validation gates, and a concrete output template — near-ideal for token efficiency and actionability. The structural weakness is reference hygiene: it depends on ~12 external files that are absent from the skill bundle while ignoring the reference files that are bundled.
Suggestions
Move the shared contract content (spec-plan-runtime-boundary, stage-arc-boundary, execution-slice, subagent-call contracts) into files under this skill's own references/ directory and link them one level deep, so the skill is self-contained.
Link or delete the bundle-local files: references/contract.yaml, references/evals.yaml, and references/task-profile.json exist in the bundle but are never mentioned in SKILL.md, while every path in the References section points to files outside the bundle that do not resolve.
Merge the duplicated mutation-authority rules from Procedure step 8 and Execution Boundaries into a single section to reclaim tokens.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and telegraphic, explaining nothing Claude already knows; every section adds operational value. Not 5 because there is minor duplication — the no-stage/no-commit/no-push rule appears in both Procedure step 8 and Execution Boundaries, and the lens/boundary-field lists repeat across Procedure, Stage Arc Boundary, and References. | 4 / 5 |
Actionability | Copy-paste-ready commands are given throughout: 'git status --short', 'rg -n "validation|rollback|scope|files_allowed"', 'python3 -m py_compile', './bin/ask skills audit <skill-path> --level strict --json --robot', plus a complete YAML output template and two concrete worked examples. Not 4 because the guidance is fully executable with only justified parameter placeholders, not gaps. | 5 / 5 |
Workflow Clarity | An 8-step procedure with pre-edit state checks, explicit pass/fail/blocked validation recording, and a fix-once-then-hand-off feedback loop ('If validation fails, fix once inside scope and re-run the same command. If it still fails, stop and hand off'). Not 4 because validation checkpoints are explicit and error recovery is fully specified, including blocked-exit paths. | 5 / 5 |
Progressive Disclosure | The References section is well-signaled with topical labels, but every path traverses outside the skill directory ('../../references/spec-plan-runtime-boundary-contract.md', '../../../../Infrastructure/references/...') and none of the referenced files exist in this bundle; meanwhile the bundle's actual reference files (contract.yaml, evals.yaml, task-profile.json) are never linked from the body. Not 4 because navigation is unreliable within the shipped bundle; not 2 because the body itself is well-sectioned and the references are clearly labeled rather than buried. | 3 / 5 |
Total | 17 / 20 Passed |