Content
38%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 body has a strong, well-organized domain core (the six Core Capabilities with tables and examples) and accurate CLI documentation, but it is undermined by API examples that do not match the bundled script, ~110 lines of duplicated generic boilerplate, and total failure to link the three existing reference files. The description-quality gap between the skill's promises (HL7/CSV output, NER method APIs) and the actual script is the most actionable defect.
Suggestions
Fix the Python examples to match the bundled script: import from scripts.main (or create scripts/soap_generator.py), use the real methods (generate, generate_from_audio, extract_entities, classify_section, detect_negation), and remove or implement the claimed hl7/text/CSV export formats.
Consolidate the duplicated generic sections ('Output Requirements' / 'Response Template' / 'Output Contract', 'Error Handling' / 'Failure Handling') into one of each, and delete or SOAP-specificize the 'Required Inputs' table that currently lists unrelated artifacts like PMID/PDF/DOCX.
Link the existing bundle references in the body (e.g., 'See references/medical_terminology.md for abbreviation expansion and references/sample_soap_notes.md for output examples') and move the inlined parameter/entity/export-format detail tables into those reference files to shorten SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Beyond the useful domain sections, roughly a quarter of the body is generic, duplicated template boilerplate: three overlapping output-structure sections ('Output Requirements', 'Response Template', 'Output Contract'), two overlapping failure sections ('Error Handling' and 'Failure Handling'), 'Quick Check' and 'Audit-Ready Commands' both repeating 'python -m py_compile scripts/main.py', and a 'Required Inputs' table listing irrelevant artifacts ('PMID, PDF, CSV, DOCX') from an unrelated research-skill template. | 2 / 5 |
Actionability | The CLI guidance is accurate and copy-paste ready (flags match main.py's argparse, and the audit command is fully concrete), but the Python examples fail against the actual bundle: 'from scripts.soap_generator import' targets a module that does not exist (the class lives in scripts/main.py), 'generate_from_transcript', 'extract_medical_entities', 'classify_soap_sections', 'extract_temporal_info', 'analyze_certainty', and 'generate_soap_document' are not the real method names, 'specialty'/'verbose' parameters are absent from generate(), and the 'hl7'/'text'/'CSV' export formats are unsupported by the script (only markdown and json). | 3 / 5 |
Workflow Clarity | A 5-step workflow and explicit validation commands exist (py_compile, --help, a full audit invocation), but the workflow steps are generic template language ('Confirm the user objective... Validate that the request matches the documented scope') rather than the actual SOAP pipeline (preprocess, NER, classify, generate, review), which is only implied by the Core Capabilities ordering — checkpoints are present yet not tied to the concrete generation sequence. | 3 / 5 |
Progressive Disclosure | The bundle ships references/clinical_guidelines.md, references/medical_terminology.md, and references/sample_soap_notes.md, but the body never mentions any of them, leaving them undiscoverable. Meanwhile parameter tables, entity-type tables, and export-format details that belong in reference files are fully inlined across a 419-line body. | 2 / 5 |
Total | 10 / 20 Passed |