Content
50%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 Usage and CLI sections are accurate and executable against the bundled script, but they are buried in a large amount of generic, non-specific boilerplate (When to Use, Key Features, Implementation Details, Output Contract, Failure Handling) that adds no information. Peripheral validation guidance is also broken — the --help command and its expected output do not match the script, and one example references a nonexistent path.
Suggestions
Delete the generic template sections (When to Use, Key Features, Dependencies, Example Usage, Implementation Details, When Not to Use, Required Inputs, Recommended Workflow, Output Contract, Validation and Safety Rules, Failure Handling, Quick Validation) — roughly 60% of the body — and keep only the Usage, CLI Usage, and Requirements sections.
Fix the broken Quick Validation guidance: replace `python scripts/chea_client.py --help` with the script's actual no-arg usage output, and remove the fabricated "Result file: chea_api_result.md" expected-output block, since the script prints JSON to stdout.
Remove the bogus `cd "20260316/scientific-skills/Evidence Insight/chea-api"` line and the self-referential "See `## Usage` above" pointer; move the real Usage content to the top so the executable examples come before any supporting text.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The majority of the body is generic template padding — "Use this skill when the request matches its documented task boundary", "Structured execution path designed to keep outputs consistent and reviewable", plus the boilerplate Output Contract / Failure Handling / Validation and Safety sections that state nothing skill-specific. Not 1 because it never lectures on concepts Claude already knows and the Usage/CLI code sections themselves are lean; not 3 because the padding is pervasive, not incidental. | 2 / 5 |
Actionability | The Usage and CLI examples (enrich with a gene list, get_dataset_metadata, get_attribute_info("CREB1"), and the enrich/metadata/attribute subcommands) are copy-paste ready and match the actual script. Not 5 because peripheral commands are broken: the script has no --help flag (it only prints usage with no args), the "Example Usage" block cd's into a bogus hardcoded path ("20260316/scientific-skills/Evidence Insight/chea-api"), "See ## Usage above" is a self-referential pointer, and the "Expected output format" for --help is fabricated (the script prints JSON, not "Result file: chea_api_result.md"). | 4 / 5 |
Workflow Clarity | "Recommended Workflow" and the "Example run plan" list coherent sequences, but validation checkpoints are either generic ("Run a final validation pass for completeness, consistency, and safety") or broken (the Quick Validation --help command fails with "Unknown command"). Not 4 because the one explicit checkpoint command does not execute; not 2 because the primary workflows themselves are single, unambiguous commands. | 3 / 5 |
Progressive Disclosure | Section headers are clear and the single bundled script reference (scripts/chea_client.py) is real and one level deep, but there is no references/ split and roughly 60% of the body is inline boilerplate (Key Features, Implementation Details, Required Inputs, etc.) that buries the genuinely useful Usage and CLI sections. Not 4 because content that should be cut or split is inlined and the useful material is interleaved with filler. | 3 / 5 |
Total | 12 / 20 Passed |