medical-scribe-dictation

Convert physician verbal dictation into structured SOAP notes. Trigger.

Quality

31%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./scientific-skills/Academic Writing/medical-scribe-dictation/SKILL.md

Quality

Discovery

40%

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 identifies a clear, distinctive niche (converting physician dictation to SOAP notes) but is undermined by an incomplete and broken 'when' clause — the word 'Trigger.' adds no value. It also lacks breadth in both specific capabilities and natural trigger terms that users might employ.

Suggestions

Replace the broken 'Trigger.' fragment with an explicit 'Use when...' clause, e.g., 'Use when the user provides physician dictation, voice transcription, or asks for help writing SOAP notes or clinical documentation.'

Add natural trigger terms users would say, such as 'medical notes', 'clinical documentation', 'progress notes', 'transcription', 'HPI', 'assessment and plan'.

List more specific actions beyond 'convert', e.g., 'Parses chief complaint, history of present illness, exam findings, assessment, and plan from raw dictation into structured SOAP format.'

Dimension	Reasoning	Score
Specificity	Names the domain (physician dictation, SOAP notes) and one action (convert), but does not list multiple specific concrete actions such as parsing chief complaints, organizing assessments, formatting plans, etc.	2 / 3
Completeness	The 'what' is present (convert dictation to SOAP notes), but the 'when' clause is essentially absent — 'Trigger.' is a meaningless fragment that provides no explicit guidance on when Claude should select this skill.	1 / 3
Trigger Term Quality	Includes relevant terms like 'dictation', 'SOAP notes', and 'physician', but misses common variations users might say such as 'medical notes', 'clinical documentation', 'progress notes', 'transcription', or 'HPI'.	2 / 3
Distinctiveness Conflict Risk	The combination of physician dictation and SOAP notes is a very specific niche that is unlikely to conflict with other skills; it clearly targets medical documentation workflows.	3 / 3
	Total	8 / 12 Passed

Implementation

22%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill is heavily padded with generic boilerplate sections (Risk Assessment, Security Checklist, Lifecycle Status, Evaluation Criteria, Response Template) that consume significant tokens without adding medical-scribe-specific value. The core task—converting dictation to SOAP notes—lacks concrete, domain-specific workflow steps and instead relies on abstract procedural language. While the SOAP output template and Python API examples provide some actionable content, the skill would benefit enormously from stripping boilerplate and adding specific guidance on medical terminology normalization, section classification heuristics, and clinical validation steps.

Suggestions

Remove all generic boilerplate sections (Risk Assessment, Security Checklist, Lifecycle Status, Evaluation Criteria, Response Template, Input Validation) that don't contain medical-scribe-specific content—these waste ~40% of the token budget.

Replace the generic workflow with concrete medical-scribe-specific steps: e.g., how to identify chief complaint from dictation, how to classify content into SOAP sections, how to normalize abbreviations, and explicit validation checkpoints for clinical completeness.

Eliminate circular self-references ('See ## Features above', 'See ## Usage above') and consolidate duplicated content into a single logical flow.

Add a concrete input/output example showing raw dictation text transformed into a completed SOAP note, so Claude has a clear pattern to follow.

Dimension	Reasoning	Score
Conciseness	Extremely verbose and bloated. Contains massive amounts of boilerplate (Risk Assessment tables, Security Checklists, Lifecycle Status, Evaluation Criteria) that add no value for Claude. Multiple self-referential sections ('See ## Features above', 'See ## Usage above') create circular references. Redundant commands repeated (--help listed 3 times). Explains concepts Claude already knows and includes generic template sections that aren't specific to this skill.	1 / 3
Actionability	Provides some concrete code examples (Python API usage, CLI commands) and a clear SOAP output template, but much of the guidance is generic and procedural rather than specific to medical scribe dictation. The workflow steps are abstract ('Confirm the user objective', 'Validate that the request matches') rather than giving concrete medical-domain-specific instructions for how to actually parse dictation into SOAP sections.	2 / 3
Workflow Clarity	The workflow section is entirely generic boilerplate ('Confirm the user objective, required inputs...') with no medical-scribe-specific steps. There are no validation checkpoints for clinical content quality, no feedback loops for handling ambiguous medical terminology, and no concrete sequence for the actual dictation-to-SOAP conversion process. The 'Example run plan' is also generic and doesn't address the core task.	1 / 3
Progressive Disclosure	References to `references/` directory files (soap-templates.md, medical-abbreviations.json, etc.) are well-signaled and one level deep. However, no bundle files are provided to verify these exist. The document itself is monolithic with many sections that should be separated (Risk Assessment, Security Checklist, Evaluation Criteria are all inline boilerplate). Multiple circular self-references ('See ## Features above') indicate poor organization.	2 / 3
	Total	6 / 12 Passed

Validation

90%

Warnings & errors only

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

Validation — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: aipoch/medical-research-skills
Commit: 73f6514

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

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.