CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

automated-soap-note-generator

Generate structured SOAP notes from clinical narratives, transcripts, or existing notes; use when the user needs de-identified clinical documentation organized into Subjective, Objective, Assessment, and Plan sections, with clear assumptions and review points.

Quality

69%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./scientific-skills/Academic Writing/automated-soap-note-generator/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

38%Weight 40%Scale 1-5

Reviews 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.

DimensionReasoningScore

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

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is strong: it concisely states a concrete capability, includes an explicit 'use when' clause with natural trigger phrases, and occupies a distinct clinical-documentation niche. The only weakness is minor missing synonym coverage (e.g., 'progress note', 'chart note') and a slightly padded closing phrase ('with clear assumptions and review points').

DimensionReasoningScore

Specificity

Names the domain and several concrete actions with input variants ('Generate structured SOAP notes from clinical narratives, transcripts, or existing notes... organized into Subjective, Objective, Assessment, and Plan sections'). It is essentially one generation action with input variants rather than multiple distinct capabilities, so it stops short of comprehensive coverage.

4 / 5

Completeness

Explicitly answers both: 'what' ('Generate structured SOAP notes from clinical narratives, transcripts, or existing notes') and 'when' ('use when the user needs de-identified clinical documentation organized into Subjective, Objective, Assessment, and Plan sections') with concrete trigger phrasing, matching the top anchor.

5 / 5

Trigger Term Quality

Includes natural user phrases like 'SOAP notes', 'clinical narratives', 'transcripts', 'clinical documentation', and the spelled-out section names. Common synonyms such as 'progress note', 'chart note', or 'clinical note' are missing, keeping it just below comprehensive coverage.

4 / 5

Distinctiveness Conflict Risk

'SOAP notes' and clinical documentation form a clear niche with distinct triggers that would not naturally fire for unrelated skills, so conflict risk is minimal.

5 / 5

Total

18

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

aipoch/medical-research-skills

Path

scientific-skills/Academic Writing/automated-soap-note-generator/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.