Content
52%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 core execution contract is a strong, well-gated multi-step workflow with concrete commands and validation, but it is buried in a heavily duplicated, monolithic body that includes a contradicting legacy workflow section. The skill would score substantially higher by deleting the legacy half and moving banners, templates, and examples into actual bundle files. Its weakest dimensions are conciseness and progressive disclosure.
Suggestions
Delete the duplicated legacy section ("# Discover Workflow - Discovery Phase" through "Example Usage"), which repeats Steps 1-2 verbatim and instructs a direct orchestrate.sh call the contract prohibits — this alone removes ~300 lines
Move the banner templates, Dev/Knowledge presentation templates, security-framing details, and example transcripts into reference files (e.g. references/presentation.md, references/security-framing.md) so SKILL.md stays a lean overview, and ensure cited files like skill-security-framing.md actually exist in the bundle
Define or resolve undefined placeholders (${PROMPT}, ${codex_status}, ${INTENSITY}) at the point of first use so snippets are copy-paste executable
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 840-line body duplicates content heavily: context-detection and banner instructions appear twice (the EXECUTION CONTRACT's Steps 1-2 and again verbatim under "# Discover Workflow - Discovery Phase"), the contract steps are re-summarized a third time in "Implementation Instructions", the Dev/Knowledge banner templates are near-identical pairs, plus ASCII art and generic TaskCreate boilerplate. This matches anchor 2 ("Noticeably verbose; several unnecessary explanations or padded sections") rather than 1, since the padding is duplication, not explanations of concepts Claude already knows. | 2 / 5 |
Actionability | Guidance is mostly executable: exact script paths (orchestrate.sh probe-single, build-fleet.sh, state-manager.sh), a complete Agent prompt template, an intensity-to-fleet-size table, and per-step error handling. Not 5: the legacy "How It Works" section instructs a direct "orchestrate.sh discover" call that the contract explicitly prohibits, and placeholders like ${PROMPT} and ${codex_status} are never defined, leaving minor gaps and one contradiction. | 4 / 5 |
Workflow Clarity | The execution contract lays out a clearly sequenced, blocking Step 1-7 flow with explicit validation checkpoints (research-verify gate, synthesis-file existence checks), a minimum-2-results threshold, graceful degradation rules, and per-step error handling with feedback loops. Not 5: the appended legacy section presents a second, conflicting workflow (single orchestrate.sh call, background_task examples) that contradicts the contract and muddies which sequence governs; validation itself is thorough, so 3 would undervalue it. | 4 / 5 |
Progressive Disclosure | This is an 840-line monolithic SKILL.md with no references/, scripts/, or assets/ bundle; banner templates, presentation templates, security-framing details, example transcripts, and state-update code that clearly belong in separate files are all inlined. The two files it does cite ("skills/blocks/codex-host-adapter.md" and "skill-security-framing.md") are dangling — not present in the bundle. Matches anchor 2 ("content that clearly belongs in separate files is inlined; or references are buried") — not 3, since hundreds of lines of separable material are inlined and the one signaled reference is unverifiable. | 2 / 5 |
Total | 12 / 20 Passed |