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 well-structured, action-dense skill body with concrete commands, a complete bundle schema, and a clearly sequenced workflow. The main defects are navigation and completeness of the bundle: two referenced files are missing, two documented flags are absent from the CLI synopsis, and the workflow lacks an explicit validation checkpoint on the generated survey.
Suggestions
Fix the dangling references: either add templates/research_bundle.template.json and the provider-configuration reference at the linked path, or remove the links and inline the minimal needed detail — as written, both navigation points dead-end.
Add --bibliography-size N and --section-count N to the build-survey.js CLI synopsis so the documented Inputs table matches the executable commands.
Add an explicit validation checkpoint in Step 4 before upserting: verify every [^src-bib-<slug>] citation in the generated survey resolves to a bibliography key and all 6-10 sections are present; if not, tighten sections[].guidance and rerun.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and table-driven — Inputs table, JSON bundle schema, single-command CLI blocks, output tree — with no explanation of concepts Claude already knows. It misses 5 mainly because the 'Diff vs dair-academy version' comparison table is provenance commentary rather than instruction, adding tokens that do not earn their place during execution. | 4 / 5 |
Actionability | Mostly executable guidance: the full bundle JSON schema with required keys, the MCP call with concrete args, and copy-paste 'node $SKILL_ROOT/scripts/build-survey.js --bundle ... --wiki ... [--provider ...] [--model ...]' commands. Gaps keep it below 5: '--bibliography-size' and '--section-count' appear in the Inputs table but never in the CLI synopsis, and two referenced files ('templates/research_bundle.template.json', '../../references/provider-configuration.md') do not exist in the bundle. | 4 / 5 |
Workflow Clarity | Steps 1-4 are clearly sequenced (read anchor → build bundle → run generator → iterate) with hard rules as constraints and an explicit rerun feedback loop ('If prose is thin: tighten sections[].guidance and rerun'). Not 5 because there is no validation checkpoint on the generated output — nothing instructs checking that citations resolve to bibliography keys or that all sections were produced before upserting. | 4 / 5 |
Progressive Disclosure | The body itself is well sectioned with clear headers, but scored against the actual bundle: the only bundle file is scripts/build-survey.js, while 'templates/research_bundle.template.json' and the link '[provider configuration](../../references/provider-configuration.md)' are dangling — those referenced paths do not exist, so navigation to the promised detail fails. This matches the 'some structure but references not properly backed' level rather than 4, where references would resolve and be well signaled. | 3 / 5 |
Total | 15 / 20 Passed |