medical-scribe-dictation

Convert physician verbal dictation into structured SOAP notes. Trigger.

Quality

46%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

tessl review fix ./scientific-skills/Academic Writing/medical-scribe-dictation/SKILL.md

Quality

Content

35%

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

The body contains genuine domain-specific material (parameters table, SOAP output template, technical architecture, real CLI/API examples) but is weighed down by extensive generic boilerplate, broken cross-references, and an off-topic trigger bullet. Core execution guidance is concrete but incomplete.

Suggestions

Remove or relocate generic scaffolding that restates what Claude already knows (Output Requirements, Response Template, Input Validation, Error Handling, Lifecycle Status, Evaluation Criteria) to slim the body to a true overview.

Delete the broken "See `## Features`/`## Usage`/`## Workflow` above" stub lines (those sections appear below) and the off-topic "academic writing tasks" bullet in When to Use.

Complete the actionability gaps: show the MedicalScribe class interface/constructor arguments and remove the duplicate `python scripts/main.py --help` from Audit-Ready Commands.

Dimension	Reasoning	Score
Conciseness	The ~280-line body is padded with generic boilerplate Claude already knows (Output Requirements, Response Template, Input Validation, Error Handling, Lifecycle Status, Evaluation Criteria), broken "See `## Features`/`## Usage`/`## Workflow` above" stubs, and an off-topic "academic writing tasks" bullet.	1 / 3
Actionability	It provides concrete executable commands (`python scripts/main.py --input ... --output-format soap`, `--audio consultation.wav`) and a Python API example, but these are incomplete — the MedicalScribe class interface is undefined and the duplicate `--help` command signals carelessness.	2 / 3
Workflow Clarity	The Workflow section lists a clear sequence with a scope-validation checkpoint and a fallback, but lacks an explicit execution-level feedback loop (run → validate output → fix → retry); checkpoints are partial.	2 / 3
Progressive Disclosure	Reference files are real and clearly signaled one level deep (## References lists soap-templates.md, medical-abbreviations.json, terminology-sources.md, example-cases.md), but the body is bloated with inline content and the broken "See X above" cross-references hurt navigation.	2 / 3
	Total	7 / 12 Passed

Description

57%

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 states a clear, distinctive purpose but relies on a "Trigger." placeholder instead of real trigger guidance and covers only one action. It needs an explicit "Use when..." clause and broader natural keywords.

Suggestions

Replace the placeholder "Trigger." with an explicit "Use when..." clause naming natural trigger situations, e.g. "Use when a physician dictates a patient encounter and needs it structured into a SOAP note, or when transcribing clinical audio into a medical record."

Add natural trigger keywords users would actually say: "dictation", "transcribe", "clinical notes", "medical notes", "scribe", "SOAP note".

Expand beyond a single action to name concrete capabilities: transcription, SOAP sectioning, medical terminology normalization, and clinical quality checks.

Dimension	Reasoning	Score
Specificity	It names a concrete domain and one clear action ("Convert physician verbal dictation into structured SOAP notes"), but lists only a single action rather than multiple specific capabilities like terminology normalization or QA checks.	2 / 3
Completeness	The "what" is clearly stated, but "when" is absent — "Trigger." is a stub, not an explicit "Use when..." clause, so per the rubric guideline completeness is capped at 2.	2 / 3
Trigger Term Quality	It includes some natural keywords ("physician verbal dictation", "SOAP notes") but misses common variations ("transcribe", "clinical notes", "medical notes", "scribe"), and the literal "Trigger." is a placeholder stub rather than a natural trigger phrase.	2 / 3
Distinctiveness Conflict Risk	The physician-dictation-to-SOAP-notes niche is clearly distinct from other skills and unlikely to trigger for the wrong task.	3 / 3
	Total	9 / 12 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

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

	Total	15 / 16 Passed

Repository: aipoch/medical-research-skills
Commit: 7cc5680

Reviewed: 3 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.