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 skill has a solid executable core — working Python and CLI examples, a complete parameter table, and documented input/output formats — but it is wrapped in substantial auto-generated boilerplate (circular cross-references, duplicated commands, generic policy sections) that inflates token cost and fragments the workflow. The references/ bundle is present but never actually linked from the body. Trimming the boilerplate, fixing the malformed audit command, and linking runtime_checklist.md explicitly would move most dimensions up a level.
Suggestions
Delete the boilerplate sections and circular cross-references (Key Features' restatement of the description, "See `## X` above" lines, Output Requirements / Response Template / Output Contract / Validation and Safety Rules) and keep one consolidated workflow; the `python -m py_compile` check needs to appear once, not three times.
Fix the Audit-Ready command to pass real input (e.g., `python scripts/main.py --input data/deseq2_results.csv --top-n 10`); the current narrative-string argument comes from an unrelated template and would fail against the CSV-expecting script.
Link the actual reference file explicitly (e.g., "Pre-execution checklist: see [runtime_checklist.md](references/runtime_checklist.md)") and move the Parameters table and Algorithm details into a reference file to slim SKILL.md to an overview.
Reconcile the Python API examples (`from volcano_plot_labeler import label_volcano_plot`) with the packaged entry point `scripts/main.py`, or document where the importable module lives.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is heavily padded: broken boilerplate cross-references ("See `## Features` above for related details.", "See `## Workflow` above", "See `## Prerequisites` above"), a Key Features section that restates the frontmatter description verbatim ("Scope-focused workflow aligned to: Analyze data with `volcano-plot-labeler`..."), the same `python -m py_compile scripts/main.py` command repeated in three sections, and generic policy sections (Output Requirements, Response Template, Output Contract, Validation and Safety Rules) that tell Claude things it already knows. This matches 'Noticeably verbose; several unnecessary explanations or padded sections'. Not 1 because the core technical sections (Usage, Parameters, Algorithm, Input Format) are genuinely informative and not concept-explanation filler. | 2 / 5 |
Actionability | Mostly executable: complete Python examples with all keyword arguments ("fig = label_volcano_plot(df, log2fc_col='log2FoldChange', ... top_n=10)"), a concrete CLI invocation with flags ("python scripts/main.py --input data/deseq2_results.csv --top-n 10"), a Parameters table with defaults, and expected input columns. This matches 'Mostly executable guidance; concrete code or commands with minor gaps'. Not 5 because the Audit-Ready command passes a clinical narrative string ("--input 'Audit validation sample with explicit symptoms, history, assessment, and next-step plan.'") to a script that expects a CSV of differential expression results — it would fail — and the `from volcano_plot_labeler import ...` examples are never reconciled with the actual packaging (`scripts/main.py`). Not 3 because the bulk of the guidance is copy-paste ready. | 4 / 5 |
Workflow Clarity | Steps exist and a validation checkpoint is present ("Quick Check ... python -m py_compile scripts/main.py", plus a documented fallback: "If execution fails or inputs are incomplete, switch to the fallback path"), but the actual sequence is fragmented across five overlapping sections (Workflow, Example Usage run plan, Implementation Details, Quick Check, Audit-Ready Commands) joined by circular "See ... above" references, so the effective sequence is implicit and a reader must merge the fragments. This fits 'Steps listed but ... sequence present but checkpoints missing or implicit'. Not 4 because the fragmentation and the broken cross-references leave no single coherent ordered procedure; not 2 because a runnable plan with validation and error recovery does exist. | 3 / 5 |
Progressive Disclosure | A references/ bundle exists (runtime_checklist.md) but the body never names or links it — only generic pointers like "Reference material available in `references/`" and "references/ contains supporting rules, prompts, or checklists", so the reference is present but not clearly signaled. Meanwhile ~320 lines are inlined in SKILL.md, including material (Parameters table, Algorithm details, Risk/Security/Evaluation boilerplate) that could live in separate files. This matches anchor 3, 'references present but not clearly signaled; content that should be separate is inline'. Not 4 because the reference is unnamed and the inline bulk is large; not 2 because the document is well-sectioned rather than an unstructured wall. | 3 / 5 |
Total | 12 / 20 Passed |