Content
81%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-organized orchestrator skill body: fully executable commands, a clearly sequenced workflow with an explicit analyze validation gate and fix-before-proceed feedback loop, and project-specific conventions. Its main weakness is conciseness — the frontmatter-duplicating Description section, the oversized constitution-principle-6 bullet, and inlined detail that belongs in separate reference files.
Suggestions
Cut the '## Description' section (it restates the frontmatter) and split constitution principle 6's docs-quality CI gate details — 'links, coverage, the DocBundleLoader registry, and locale layout/nav_order... blocking CI gate (docs-quality.yml)' — into a short summary here with the full gate rules in a reference file such as references/constitution.md.
Move time-sensitive content out of the main body or into a clearly labeled section: replace the pinned 'Current constitution (v1.4.2)' version reference with a pointer to the live '.specify/memory/constitution.md', and fold the legacy 'NNN-<slug>' numbering note into the Existing Specs section as an explicit legacy note.
Trim the Related Skills and Extension Hooks sections to one-line pointers (skill name + one trigger phrase) so the body stays a lean command index rather than accumulating detail inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient — command tables, a compact workflow diagram, and terse conventions — but includes content that could be tightened or offloaded: a '## Description' section that largely restates the frontmatter, an oversized single bullet for constitution principle 6 (inlining the full docs-quality CI gate details), and time-sensitive version pinning ('Current constitution (v1.4.2)') that the guidelines penalize outside a deprecated/versions section. This matches the anchor 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than the 4 anchor, which requires only minor trimming. | 3 / 5 |
Actionability | Guidance is fully executable for an orchestrator skill: copy-paste-ready invocations ('/speckit.specify "Feature description here"', '/speckit.workflow speckit "Describe the feature"'), a complete command table with purposes, exact file paths ('specs/<YYYYMMDD-HHMMSS>-feature-name/', '.specify/memory/constitution.md'), concrete naming examples ('20260511-211823-compose-screenshot-testing', 'SST-T001'), and a specific config toggle ('auto_execute_hooks: true' in '.specify/extensions.yml'). This matches the 5 anchor: commands cover the common cases with specific examples. | 5 / 5 |
Workflow Clarity | The end-to-end sequence is numbered 1–6 with each step's output, an explicit validation checkpoint ('/speckit.analyze' with 'Fix any CRITICAL/HIGH findings before proceeding'), and a feedback loop (analyze → fix → proceed); the automated variant documents its review gates. This matches the 5 anchor ('clear sequence with explicit validation steps; feedback loops for error recovery'); the git commit/branch operations are covered by the analyze gate, so the destructive/batch cap does not apply. | 5 / 5 |
Progressive Disclosure | The body is well-sectioned (commands, workflow, file structure, constitution, conventions, tips) and functions as an overview that delegates execution detail to the slash commands rather than inlining it. It is not a 5 because there are no one-level-deep reference files at all: detail-heavy blocks — the seven constitution principles (especially the docs-gate bullet) and the Meshtastic conventions — are inlined in SKILL.md where separate reference files would keep the overview leaner; structure is good but not optimally split. | 4 / 5 |
Total | 17 / 20 Passed |