Content
46%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 skill has a workable core (a three-step conversion workflow with a real, well-placed reference file), but the body is buried under roughly 75% generic boilerplate that is unrelated to the actual task. The most impactful fix is deleting the template sections and replacing them with a concrete example flowchart and an operational validation step.
Suggestions
conciseness: Delete the template boilerplate sections (Key Features, Dependencies, Example Usage, Recommended Workflow, Output Contract, Failure Handling, Quick Validation) and the duplicated Description section — they repeat the frontmatter description or state generic rules Claude already knows, and the Dependencies section even claims a Python 3.10+ requirement for a script that doesn't exist.
actionability: Add a short worked example — a sample research-text excerpt and the expected Mermaid flowchart TD output — so the 'professional, concise scientific terminology' and node-wording expectations are concrete rather than delegated entirely to the reference.
workflow_clarity: Make the Validation step operational, e.g. 'render the generated Mermaid in a checker (mermaid.live or mmdc) before returning it' or at minimum an explicit self-check list of common syntax pitfalls, instead of the current non-actionable 'Ensure the code is syntactically correct' plus 'No local script validation step is required.'
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is heavily padded: the description is repeated nearly verbatim three times ("Key Features", the "Description" section, frontmatter echo), and generic template sections ("Recommended Workflow", "Failure Handling", "Output Contract", "Validation and Safety Rules") add no task-specific information. A spurious "Dependencies" section lists "Python 3.10+" despite "No packaged executable script was detected", and the "Example Usage" block contains fabricated directory filler ("Skill directory: 20260316/scientific-skills/..."). Only ~30 of ~120 lines carry real signal. | 2 / 5 |
Actionability | The Instructions section gives some concrete guidance — a specific component list ("Background, Scientific Question, Objectives, Research Content, and Methodology"), an exact graph type ("flowchart TD"), and an output-only constraint — but key details are missing: there is no example input/output pair showing what a good roadmap flowchart looks like, and the substantive extraction rules are delegated to references/prompt_guidelines.md. | 3 / 5 |
Workflow Clarity | A clear three-step sequence is present (Analyze the Input → Generate Mermaid Code → Validation), but the validation checkpoint is non-operational: "Ensure the code is syntactically correct and renderable" gives no mechanism, and the "Quick Validation" section states "No local script validation step is required for this skill." The checkpoints are therefore implicit rather than executable. | 3 / 5 |
Progressive Disclosure | The bundle structure is sound: SKILL.md acts as an overview with a clearly signaled, one-level-deep reference ("[Prompt Guidelines](references/prompt_guidelines.md)", which exists and contains the detailed rules). Minor gaps: the component list and output constraint are duplicated between SKILL.md and the reference, and boilerplate sections dilute the overview. | 4 / 5 |
Total | 12 / 20 Passed |