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 five-step workflow is genuinely well designed — named prompts with exact inputs, a draft/no-draft branch, length constraints, and a clear assembly order — and the bundle structure uses references appropriately. However, about half the document is generic template filler, and the executable/verification claims (the --help output, the validation summary format) do not match the actual script, which undermines both conciseness and actionability.
Suggestions
Delete or collapse the template sections (When to Use, Key Features, Dependencies, Implementation Details, Required Inputs, Output Contract, Validation and Safety Rules, Failure Handling) down to the few lines that carry skill-specific information.
Fix the verification path to match reality: either give scripts/flow.py a real CLI (--help, argument parsing) or replace the fabricated 'expected output format' with what the script actually produces, and use a path relative to the skill root instead of '20260316/scientific-skills/...'.
Add a genuine post-generation checkpoint, e.g. verify the Q&A body is ~2000 words and follows the 'Question: ...? / Expert Name: ...' format before final assembly.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Roughly half the body is templated boilerplate that adds no skill-specific information: 'Use this skill when the request matches its documented task boundary', the Key Features section repeating the frontmatter description verbatim, 'See ## Workflow above for related details', and generic Required Inputs / Output Contract / Validation and Safety Rules / Failure Handling sections that could apply to any skill. This matches 'noticeably verbose; several unnecessary explanations or padded sections'; the one specific thing (the five-step workflow) is efficient, so it is not a 1. | 2 / 5 |
Actionability | The workflow steps are concrete — each names a specific prompt in references/prompts.md (verified to exist) with exact inputs and constraints ('approximately 2000 words', '150-word introduction') — but executable claims are broken: the Example Usage hard-codes an environment-specific path ('cd "20260316/scientific-skills/..."'), and scripts/flow.py has no CLI, so 'python scripts/flow.py --help' will not produce the claimed 'Result file / Validation summary / Assumptions' output. This is 'some concrete guidance but incomplete / missing key details'; not a 2 because the core generative steps are fully specified. | 3 / 5 |
Workflow Clarity | Steps 1-5 are clearly sequenced with per-step inputs, an explicit branch ('Path A (With Draft)' vs 'Path B (No Draft)' based on text1), word-count constraints, and a numbered final assembly structure. Not a 5: validation checkpoints are weak — the Quick Validation section's expected output does not match what flow.py actually does, and there is no check that the 2000-word/Q&A-format constraints were met; not a 3 because the sequence itself is coherent and a pre-run verification step is at least attempted. | 4 / 5 |
Progressive Disclosure | The detailed prompts are correctly split into references/prompts.md (one level deep, real file) and each workflow step signals exactly which named prompt to use ('the Expert Introduction Prompt in references/prompts.md'), with scripts/flow.py for text assembly. Not a 5: the SKILL.md overview is cluttered by the boilerplate sections and contains the awkward self-reference 'See ## Workflow above for related details'; not a 3 because references are clearly signaled and appropriately placed. | 4 / 5 |
Total | 13 / 20 Passed |