automated-soap-note-generator

1. Confirm the user objective, required inputs, and non-negotiable constraints before doing detailed work. 2. Validate that the request matches the documented scope and stop early if the task would require unsupported as.

Quality

13%

Does it follow best practices?

Impact

Pending

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/automated-soap-note-generator/SKILL.md

Quality

Discovery

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

This description is severely deficient across all dimensions. It reads like generic process instructions rather than a skill description, lacks any domain specificity, contains no natural trigger terms, and appears to be truncated ('unsupported as.'). It would be impossible for Claude to determine when to select this skill over others.

Suggestions

Identify and state the specific domain or task this skill handles (e.g., 'Validates API requests', 'Reviews code submissions', 'Processes form data').

Add a 'Use when...' clause with concrete trigger terms that users would naturally say when needing this skill.

Replace abstract process language with specific, concrete actions the skill performs (e.g., 'checks input formats', 'validates JSON schemas', 'verifies required fields').

Dimension	Reasoning	Score
Specificity	The description uses vague, abstract language like 'user objective', 'required inputs', 'non-negotiable constraints', and 'detailed work' without specifying any concrete actions or domain. No specific capabilities are listed.	1 / 3
Completeness	The description fails to answer 'what does this do' in any meaningful way and completely lacks a 'when should Claude use it' clause. It describes a generic validation process without context.	1 / 3
Trigger Term Quality	Contains no natural keywords users would say. Terms like 'non-negotiable constraints', 'documented scope', and 'unsupported as' (appears truncated) are technical jargon that users wouldn't naturally use when seeking help.	1 / 3
Distinctiveness Conflict Risk	Extremely generic description that could apply to virtually any skill. 'Confirm user objective' and 'validate request' are universal practices, not distinctive triggers for a specific skill.	1 / 3
	Total	4 / 12 Passed

Implementation

27%

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

This skill suffers from severe verbosity and poor organization, with the same information repeated multiple times across different sections. While it contains some actionable CLI commands and code examples, much of the content explains concepts Claude already knows (SOAP note structure, NER basics) and includes extensive inline documentation that should be in separate reference files. The skill would benefit from aggressive trimming to ~25% of its current length.

Suggestions

Remove redundant sections - the workflow appears 3+ times; consolidate into a single authoritative workflow section

Move the extensive API documentation (entity types tables, parameter tables, output format examples) to a separate REFERENCE.md file and link to it

Delete explanatory content about what SOAP notes are, what NER does, and basic medical documentation concepts - Claude knows these

Convert commented-out 'Returns:' pseudocode blocks into actual executable examples or remove them entirely

Dimension	Reasoning	Score
Conciseness	Extremely verbose with significant redundancy - the workflow is repeated multiple times, there are self-referential sections ('See ## Usage above'), and extensive explanations of concepts Claude already knows (what SOAP notes are, what NER is, basic Python usage). The document is ~400 lines when it could be ~100.	1 / 3
Actionability	Contains executable code examples and concrete CLI commands, but many code blocks are commented-out pseudocode showing expected output rather than actual executable code. The main.py examples are actionable, but the SOAPNoteGenerator class examples appear to be illustrative rather than matching actual implementation.	2 / 3
Workflow Clarity	The workflow section provides clear numbered steps with validation checkpoints, but the same workflow is duplicated in multiple places with slight variations. The error handling section mentions fallbacks but doesn't provide concrete recovery steps. Missing explicit validation commands between steps.	2 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files despite mentioning 'references/' directory. Contains inline API documentation, parameter tables, and extensive examples that should be in separate reference files. Self-referential links ('See ## Usage above') indicate poor organization.	1 / 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: 4a48721

Reviewed: about 8 hours 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.