Content
63%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 presents a well-structured, security-conscious 8-phase workflow with clear sequencing, confirmation gates, verification phases, and executable commands for the critical path. Its weaknesses are duplication — the When-to-Use section repeats the frontmatter, and Best Practices/Constraints are inlined despite existing as bundle files — and a bundle organization problem where 5 of 9 reference files are unreachable from SKILL.md and two files overlap in purpose.
Suggestions
Trim the "When to Use" section and trigger-phrase list (they duplicate the frontmatter description verbatim), and reduce Best Practices and Constraints to one-line pointers to references/best-practices.md and references/constraints-warnings.md.
Reference all bundle files from SKILL.md — especially add links to references/test-commands.md (Phase 5) and references/commit-examples.md (Phases 7–8) in the References section so they are discoverable.
Merge references/phase-workflows.md and references/phases-detailed.md (both are detailed Phase 1–8 walkthroughs) into a single file, or clearly differentiate their roles and reference both.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Per-line it is efficient (bullets, tables, commands, no explanation of how git or GitHub works), but there is real duplication: the "When to Use" section ("resolve", "implement", "work on", or "fix"... "Trigger phrases:") repeats the frontmatter description verbatim, and the 8-item Best Practices and 7-item Constraints sections inline summarized content that also exists as bundle files (best-practices.md, constraints-warnings.md). Not 4: the duplication with the frontmatter and bundle files is more than minor trimming — roughly 30 lines could be cut or reduced to pointers. | 3 / 5 |
Actionability | Phase 1 has executable bash ("gh issue view \"$ISSUE_REF\" --json title,body,labels,assignees,state,repositoryUrl"), Example 1 is a copy-paste-ready command sequence (branch, commit with "Closes #42", push, "gh pr create"), and the Quick Reference table gives a key command per phase. Not 5: Phases 2–8 are one-line summaries ("Analyze user's description... assess completeness, clarify ambiguities") that defer all executable detail to references/phases-detailed.md, and the Phase 1 snippet relies on "$1" without stating the script-argument context, so the body alone is not fully executable. | 4 / 5 |
Workflow Clarity | The 8 phases are clearly numbered and sequenced, with explicit checkpoints: confirmation gates at Phase 2 and Phase 4 ("mandatory user confirmation gates at Phase 2 (requirements) and Phase 4 (implementation start)"), a hard ordering constraint ("Phases 1–3 must complete before Phase 4"), and verification phases (Phase 5 "Run full test suite, linters, static analysis", Phase 6 review with severity triage). Not 5: there is no explicit test-fail feedback loop (fix → re-run) stated in the body — Phase 5 says "produce test report" and Phase 6 "address critical/major issues" but re-validation after fixes is only implicit. | 4 / 5 |
Progressive Disclosure | The four referenced files (prerequisites.md, security-protocol.md, phases-detailed.md, examples.md) all exist, are clearly signaled inline and in a dedicated References section, and are one level deep. However, scoring against the actual bundle: 5 of 9 reference files (best-practices.md, commit-examples.md, constraints-warnings.md, phase-workflows.md, test-commands.md) are never referenced from the body — including test-commands.md which the Phase 5 description would naturally point to — and phase-workflows.md duplicates the purpose of phases-detailed.md (both are detailed Phase 1–8 walkthroughs). Not 4: orphaning over half the bundle plus a redundant file pair is more than a minor organization gap. | 3 / 5 |
Total | 14 / 20 Passed |