Content
56%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 highly actionable and well-sequenced, with concrete commands, templates, and a clear detection table for the guide's core moments. Its weaknesses are length-driven: heavy duplication of read-only disclaimers and inlining of cross-skill conventions that should live in the referenced project-conventions bundle, making an ~870-line monolith for a navigation skill.
Suggestions
Move the sections that bind all phase-skills (User Interaction Protocol, Concurrent-agent coordination, Dialog handoffs, Signal layer) into the referenced /project-conventions or a references/ bundle file, leaving one-line pointers — this would cut several hundred lines and fix the monolith.
State the read-only boundary ('the guide recommends; the user invokes; the guide does not call other skills, auto-fix, tag, or write METRICS') once in the opening section and delete the four repeated restatements throughout.
Replace the garbled two-column ASCII workflow diagram (comments colliding mid-line) with a simple phase table or list, or move the detailed per-phase input/output mapping into a reference file since the entry-point detection table already covers the routing decision.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | At ~870 lines for a self-described 'read-only orientation layer', the body is noticeably verbose: the non-invocation disclaimer ('the guide does not call other skills / does not auto-fix') is repeated in at least four sections, and whole sections (User Interaction Protocol, Concurrent-agent coordination, Dialog handoffs, Signal layer) restate conventions that bind 'all phase-skills' and belong in the referenced /project-conventions files. It is not a 1 because the content is project-specific workflow knowledge Claude would not already know, not explanations of basic concepts; it is below a 3 because the padded and duplicated sections are several, not incidental. | 2 / 5 |
Actionability | Most operations are concrete and executable: a copy-paste git branch-creation block, exact flow.py invocations (create-issue, tag-phase, status --item <ID>, promote-to-epic --rename-branch), the mkdir/touch initialization commands, the entry-point detection table, and report templates with literal output formats. It falls short of 5 because some steps remain descriptive rather than executable — e.g. 'Update BACKLOG row: Status -> Ready' without the row's binding format, and 'reads git state' with no concrete command; it is above 3 because the gaps are minor against broad command coverage. | 4 / 5 |
Workflow Clarity | Each guide moment is a numbered, clearly sequenced procedure (branch creation, post-RE promotion with a user-driven AskUserQuestion gate before batch writes, handoff-state audit over five named surfaces, three-step entry-point detection, four-step Closing Handoff), with the feature-complete audit providing explicit verification ('Verdict: feature-complete | missing tags: <list>') and the branch-exists guard preventing destructive overwrite. It is not a 5 because some checkpoints are implicit rather than explicit validate-then-proceed steps (e.g. no post-check after promote-to-epic, tag verification reported but not re-run); not a 3 because validation is largely present. | 4 / 5 |
Progressive Disclosure | Section headers are clear and navigation is possible, but the skill is a monolithic single file with no bundle (no references/, scripts/, or assets/ exist), and substantial content that clearly belongs in separate shared files is inlined (User Interaction Protocol, Concurrent-agent coordination, Dialog handoffs, Signal layer, Traceability Chain). Cross-references to other skills' files (graph-invariants.md, team-workflow.md, templates) appear as bare inline code paths rather than clearly signaled links. This matches the 3 anchor 'Some structure but could be better organized; references present but not clearly signaled; content that should be separate is inline'; it is above 2 only because the in-file structure is genuinely good. | 3 / 5 |
Total | 13 / 20 Passed |