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 operational content (commands, parameter table, input/output structures, API example) is accurate and executable, but the document is padded with duplicated wrapper sections and generic template boilerplate, scatters its workflow across redundant sections, and includes broken references to a missing test-data script and undefined parameters. It functions but wastes context and misleads on a few paths.
Suggestions
Remove the duplicated wrapper sections ("Key Features", "Implementation Details", the Quick Check/Audit-Ready Commands duplication, and the generic Risk/Security/Lifecycle/Evaluation boilerplate), keeping one dependency list and one description.
Fix broken references: either ship scripts/generate_test_data.py or drop the Quick Start test-data path, and remove the --hires/--downsample notes for parameters main.py does not define.
Consolidate the workflow into one sequenced section with explicit validation checkpoints (py_compile check → run with validated inputs → verify expected output files exist → fallback path on failure), and move API usage and audit details into separate reference files.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~415-line body is noticeably padded: wrapper sections ("Key Features", "Dependencies", "Example Usage", "Implementation Details") that only point to other sections, "Quick Check" and "Audit-Ready Commands" repeating identical commands, two separate dependency listings, and generic template boilerplate (Risk Assessment, Security Checklist, Evaluation Criteria, Lifecycle Status) that applies to any skill rather than this one. Not score 1 because the core Usage/Parameters/Examples sections are skill-specific and free of educational filler. | 2 / 5 |
Actionability | Provides copy-paste-ready commands, a parameter table that matches the actual argparse definitions in scripts/main.py (verified: platform, data-dir, gene/genes, mode, cluster-file, output, dpi, cmap, spot-size, alpha, min-count, crop), input/output file structures, and a working Python API example. Falls short of 5 because the Quick Start references a nonexistent scripts/generate_test_data.py, the Notes cite undefined --hires/--downsample parameters, and the Example Usage cd path is a non-portable internal directory. | 4 / 5 |
Workflow Clarity | A reasonable sequence exists (confirm inputs → validate scope → py_compile check → run main.py → review output → fallback on failure), but it is scattered across five overlapping sections (Quick Check, Audit-Ready Commands, Example run plan, Workflow, Error Handling) with output verification left implicit and steps phrased abstractly ("Return a structured result that separates assumptions, deliverables, risks..."). Not score 4 because the duplication and abstraction blur the actual operational checkpoints. | 3 / 5 |
Progressive Disclosure | Section structure exists and the script references that do exist (scripts/__init__.py, scripts/main.py) are real and clearly signaled, but everything is inlined in one long file — generic audit/security/lifecycle boilerplate and API details that belong in separate reference files — and the generate_test_data.py reference is broken (the file is absent from the bundle). Not score 2 because headers make the document navigable and script paths are surfaced rather than buried. | 3 / 5 |
Total | 12 / 20 Passed |