CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

medical-scribe-dictation

Convert physician verbal dictation into structured SOAP notes. Trigger.

Quality

62%

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/medical-scribe-dictation/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

53%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 skill has a genuinely strong core: executable CLI/Python usage examples, a complete parameter table, a concrete SOAP output template, and a clean references/ bundle that is correctly discovered and described. However, that core is buried under generic template scaffolding — dangling 'See above' pointers, an out-of-domain 'When to Use' bullet, stale lifecycle dates, and a broken requirements.txt reference — which costs tokens and obscures the actual workflow. The result is a mid-range score driven down by conciseness and generic, rather than task-specific, workflow sequencing.

Suggestions

Delete the template filler: the dangling 'See `## X` above' lines, the duplicated audit commands, and the Risk Assessment / Security Checklist / Evaluation Criteria / Lifecycle Status / Response Template sections — none are specific to this skill and the stale 2026-03-06 review date is time-sensitive noise.

Fix broken references: remove `pip install -r requirements.txt` (no requirements.txt exists in the bundle — list the dependencies directly instead), replace the bogus `cd "20260318/..."` path, and drop the duplicated `--help` command.

Rewrite the Workflow section to reflect the actual pipeline (transcription → segmentation → terminology normalization → SOAP assembly → quality validation) with an explicit checkpoint on the generated note, instead of the generic objective/assumptions wrapper steps, and remove the academic-writing bullet from 'When to Use'.

DimensionReasoningScore

Conciseness

The body is padded with several unnecessary template sections: dangling self-references ("See `## Features` above for related details.", "See `## Usage` above", "See `## Workflow` above"), a duplicated command list (`--help` appears twice), and generic governance boilerplate (Risk Assessment, Security Checklist, Evaluation Criteria, Lifecycle Status with a stale 'Next Review Date: 2026-03-06', Output Requirements, Response Template) that teaches nothing task-specific. This matches 'Noticeably verbose; several unnecessary explanations or padded sections'; it is not 1 because the core sections (Usage, Parameters, SOAP structure) are dense and free of explaining concepts Claude already knows, and not 3 because the volume of pure template filler is substantial, not minor.

2 / 5

Actionability

Concrete, mostly copy-paste-ready guidance abounds: `python scripts/main.py --input "..." --output-format soap`, the audio invocation, a Python API example, a full parameter table, and a `py_compile` quick check. This fits 'Mostly executable guidance; concrete code or commands with minor gaps'. Not 5 because of real gaps: `pip install -r requirements.txt` references a requirements.txt that does not exist in the bundle, and the example `cd "20260318/scientific-skills/Academic Writing/medical-scribe-dictation"` is a bogus path; not 3 because the code shown is executable rather than pseudocode.

4 / 5

Workflow Clarity

A sequence exists (Workflow's five steps plus a py_compile quick check and an error-handling fallback path), but the steps are generic wrapper language ('Confirm the user objective...', 'Return a structured result that separates assumptions...') rather than the actual pipeline, which only appears as component descriptions under Technical Architecture. This matches 'Steps listed but validation gaps; sequence present but checkpoints missing or implicit' — beyond py_compile there is no checkpoint tied to actual processing (e.g., verifying the SOAP output against the quality validator). Not 4 because the checkpoints that do exist are thin and disconnected from the real task flow; not 2 because a coherent sequence with fallback handling is present.

3 / 5

Progressive Disclosure

Scored against the actual bundle: references/ holds exactly the four files listed in the References section (soap-templates.md, medical-abbreviations.json, terminology-sources.md, example-cases.md), each with a one-line description, and scripts/main.py is consistently referenced — all one level deep and clearly signaled, matching 'Good structure; most content is appropriately placed; references mostly clear'. Not 5 because the SKILL.md overview itself is cluttered (out-of-order sections, the 'When to Use' bullet about academic writing that belongs to a different template, and inlined boilerplate that should simply be deleted rather than split out), which weakens navigation.

4 / 5

Total

13

/

20

Passed

Description

53%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 communicates a clear, niche 'what' in one concrete sentence but completely lacks the 'when': the literal text 'Trigger.' is a template artifact where an explicit 'Use when...' clause should be. Keywords are domain-appropriate yet miss common synonyms like 'transcribe', 'clinical notes', or 'medical scribe'. Overall it is serviceable but under-specified for reliable triggering.

Suggestions

Replace the dangling 'Trigger.' with an explicit trigger clause, e.g. 'Use when a physician or clinician dictates a note, or when the user mentions dictation, transcription to SOAP notes, or clinical note formatting.'

Briefly enumerate the key capabilities (terminology/abbreviation normalization, drug-name verification, quality checks) to raise specificity from one action to several.

Add natural user phrasings such as 'medical transcription', 'clinical notes', and 'scribe' to improve trigger-term coverage.

DimensionReasoningScore

Specificity

The description states one concrete action — "Convert physician verbal dictation into structured SOAP notes" — which names the domain clearly but stops there. It omits advertised capabilities from the body such as terminology normalization, drug-name verification, and clinical quality checks, matching the anchor 'Names domain and 1-2 concrete actions, but not comprehensive'. It is not score 2 because the single action is specific and domain-anchored rather than generic; not score 4 because coverage of the skill's actions is not 'several', just one.

3 / 5

Completeness

The 'what' is clear (convert dictation into structured SOAP notes) but the 'when' is entirely missing — the trailing "Trigger." is a dangling artifact, not an explicit trigger clause, so per the guideline a missing 'Use when...' clause caps completeness at 3. Not 4 because there is no usable 'when' guidance at all, even weakly implied; not 2 because the 'what' is concrete, not vague.

3 / 5

Trigger Term Quality

Relevant domain keywords are present ("physician", "dictation", "SOAP notes") and a clinician would plausibly say them, but common variations are missing: "medical transcription", "clinical notes", "transcribe", "audio dictation", "scribe". This fits 'Some relevant keywords but missing common variations or synonyms'; it falls short of 4's 'good keyword coverage' because the most likely user phrasings outside of 'SOAP' are absent, and exceeds 2 because the terms given are domain-natural rather than generic.

3 / 5

Distinctiveness Conflict Risk

The physician-dictation-to-SOAP-notes niche is narrow and largely distinct from general document or writing skills, fitting 'Mostly distinct; minor overlap risk with closely related skills' (e.g., a generic medical-transcription or note-formatting skill). Not 5 because the broken "Trigger." fragment means it lacks the clear, distinct trigger phrases the 5 anchor requires, and the body's 'When to Use' even suggests academic-writing usage, adding slight overlap risk.

4 / 5

Total

13

/

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/medical-scribe-dictation/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.