Content
70%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 content is a strong procedural skill: an unambiguous numbered workflow with concrete commands, explicit validation, error recovery, and careful safeguards around the constitution overwrite. Its two real weaknesses are the near-verbatim duplication of the extension-hook protocol across pre- and post-execution sections (hurting both conciseness and organization) and the absence of any bundle files to offload that shared protocol. Tightening the duplicated blocks into a single section or a references/hooks.md file would address both at once.
Suggestions
Factor the duplicated pre/post extension-hook protocol into a single shared section (or a references/hooks.md file) parameterized by the hook key (before_constitution vs after_constitution) — this removes ~30 lines of verbatim repetition and improves both conciseness and progressive disclosure.
Trim the verbose hook-error sentence ('do not skip silently: tell the user that ... and that no hooks were checked, including any mandatory (optional: false) hooks registered there, then continue normally') to one crisp instruction since it currently appears twice.
Include one short example of a resolved constitution skeleton (headings plus one placeholder-filled principle) so step 3's drafting guidance is fully copy-paste concrete.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense procedural content with no explanations of concepts Claude already knows, but the entire ~30-line extension-hook protocol appears twice nearly verbatim (Pre-Execution and Post-Execution Checks), and long sentences such as the 'do not skip silently: tell the user that .specify/extensions.yml could not be read...' instruction repeat word-for-word. Mostly efficient but could be tightened by factoring the duplicated hook protocol into one section, fitting the anchor for some unnecessary explanation; not score 2 because the padding is one concentrated duplication pattern rather than several scattered padded sections. | 3 / 5 |
Actionability | Concrete, executable guidance throughout: 'Run .specify/scripts/bash/resolve-template.sh constitution-template --json' and parse TEMPLATE_CONTENT, placeholder token form '[ALL_CAPS_IDENTIFIER]', 'TODO(<FIELD_NAME>): explanation', explicit MAJOR/MINOR/PATCH bump rules, ISO date format, and exact hook output blocks. Minor gaps: no example of the resolved template structure and the hook invocation mechanism is described abstractly ('the invocation may differ from the literal {command} id'), so it fits 'mostly executable guidance with minor gaps' rather than the fully copy-paste-ready anchor. | 4 / 5 |
Workflow Clarity | A clear 7-step numbered sequence with an explicit validation checklist (step 5: no unexplained bracket tokens, version line matches report, ISO dates), error recovery ('If it fails, stop and report the resolution error; do not continue'), clarification loops ('If it is unclear whether an instruction is constitution content, ask for clarification before making changes'), and safeguards around the destructive overwrite (preserve still-applicable values, Sync Impact Report). Matches the anchor for clear sequence with explicit validation steps, feedback loops for error recovery, and checklists. | 5 / 5 |
Progressive Disclosure | No bundle files exist, so all content is inlined in a ~170-line body — well over the under-50-line exception for single-file skills. Section structure is clear (Scope Guard, Pre/Post-Execution Checks, numbered Outline), but the duplicated pre/post hook protocol (~60 lines combined) is content that clearly belongs in a shared reference file. Fits 'some structure but could be better organized; content that should be separate is inline'; not score 4 because the duplication is a real organization gap, not a minor one. | 3 / 5 |
Total | 15 / 20 Passed |