Content
65%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-structured, highly actionable body built on concrete, copy-paste-ready bash snippets for a real multi-step process. Its main weaknesses are a step sequence that contradicts its own execution order (discovery/supersedes must precede the save), duplicated variable-resolution snippets, and unverifiable external file references with no progressive disclosure into bundle files.
Suggestions
Reorder the workflow so discovery and supersedes resolution (currently Steps 2-3) come before the save step (Step 1), or note explicitly that Step 1's $SUPERSEDES is set by the Step 3 block.
Fix keyword discovery to actually match individual keywords (e.g. grep -liE 'auth|refactor' built from the keyword list) and add a post-write verification (e.g. test -f "$FILEPATH") checkpoint.
Define SLUG/DESIGNS_DIR/BRANCH once and drop the four repeated resolution blocks, moving the design document template into a reference file and clarifying whether the skills/blocks/*.md paths exist in the deployment environment.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean — no explanations of concepts Claude already knows, and every section carries operational content — matching 'Efficient; minor instances of over-explanation that could be trimmed'. It is not a 5 because the SLUG/BRANCH/DATETIME resolution snippets are repeated across Filename Format, Step 1, Step 2, Step 3, and Step 4, and the immutability rule is stated three times (Step 1, Integration Notes, Immutability Rule). | 4 / 5 |
Actionability | Guidance is almost fully executable: concrete bash blocks for slug derivation, filename construction, writing the doc via heredoc, grep-based discovery, revision-chain walking, and cap enforcement, plus a concrete filename example. Not a 5 due to minor gaps: Step 1's heredoc references ${SUPERSEDES} before Step 3 shows how to set it, and 'grep -li "$KEYWORDS"' matches the keywords as one contiguous phrase rather than individual keyword matching as the prose claims. | 4 / 5 |
Workflow Clarity | Steps are clearly headed (Save, Discover, Link, Cross-Session Discovery) but the numbered order is incoherent with the actual workflow: Step 1's save heredoc consumes $SUPERSEDES, which is only populated by Step 3's discovery logic, so discovery and linking must precede saving. Fits 'sequence present but checkpoints missing or implicit' — the Step 2 user-confirmation is the only explicit checkpoint, and there is no post-write verification. Not a 4 because the mis-ordering is more than a minor gap. | 3 / 5 |
Progressive Disclosure | The skill is a single ~270-line file with no bundle (no references/, scripts/, or assets/ exist), yet the body points to 'skills/blocks/domain-modeling.md' and 'skills/blocks/codex-host-adapter.md', which are not part of this bundle — references present but not resolvable. Structure is decent (clear section headers), but the 45-line document template and the Integration Notes lists are inlined content that could live in separate files, matching 'Some structure but could be better organized'. | 3 / 5 |
Total | 14 / 20 Passed |