Content
71%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 highly actionable, well-sequenced procedural skill with concrete commands, templates, and strong safety constraints (append-only, byte-for-byte unchanged when converged). Its main weaknesses are the near-verbatim duplication of the extension-hooks protocol and the absence of any progressive disclosure into reference files.
Suggestions
Extract the extension-hooks protocol (parsing rules, enabled/condition handling, optional vs. mandatory output blocks) into a single shared section or a references/hooks.md file and point both the pre-execution check and Step 9 at it, removing ~70 lines of duplication.
Move the hook output templates and the findings-table example into a reference file so SKILL.md stays a lean overview with one-level-deep references.
Add a post-append verification step (e.g. re-read tasks.md to confirm the new phase section and zero-padded IDs are correctly formatted) to close the workflow's only validation gap.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Most of the body is necessary procedural detail rather than explanation of known concepts, but the extension-hooks protocol is repeated nearly verbatim in 'Pre-Execution Checks' and 'Step 9' (~70 of ~275 lines), plus duplicated boilerplate blocks for optional/mandatory hook output. Not a 2 because the verbosity is redundancy of needed instructions, not padding or basic-concept explanation, and it could be tightened rather than rewritten. | 3 / 5 |
Actionability | The guidance is fully executable for an instruction-only skill: an exact script invocation ('.specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks'), a concrete ID scheme ('T{M+1:03d}'), a copy-paste checklist line format ('- [ ] T042 <imperative description> per <source-ref> (<gap-type>)'), exact findings-table schema, and exact output text for the converged branch. Specific examples cover the common cases. | 5 / 5 |
Workflow Clarity | Nine numbered steps are clearly sequenced with explicit checkpoints: prerequisite script validation with JSON parsing, STOP-with-actionable-message on missing artifacts, an in-session findings summary required before any write, and a converged branch that guarantees tasks.md stays byte-for-byte unchanged. Not a 5 because there is no post-append verification step (e.g. re-reading tasks.md to confirm the appended section) and 'keyword search for the concepts' in Step 3 leaves the search method implicit. | 4 / 5 |
Progressive Disclosure | Sections are well-organized with clear headers, but the skill is a ~275-line monolith with no bundle files or references at all; the duplicated extension-hooks protocol and detailed hook output templates clearly belong in a one-level-deep reference file. Not a 4 because content that should be separate is fully inlined and there are no signaled references to offset that. | 3 / 5 |
Total | 15 / 20 Passed |