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.
30
13%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./scientific-skills/Academic Writing/automated-soap-note-generator/SKILL.mdQuality
Discovery
0%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 reads like generic process instructions rather than a skill description. It lacks any concrete actions, domain specificity, trigger terms, or 'use when' guidance. The text also appears truncated ('unsupported as' cuts off), further reducing its utility for skill selection.
Suggestions
Rewrite to specify the concrete domain and actions this skill performs (e.g., 'Validates API request parameters against schema definitions' rather than generic 'validate that the request matches the documented scope').
Add an explicit 'Use when...' clause with natural trigger terms that describe when Claude should select this skill over others.
Remove the numbered process-step format and instead describe capabilities and triggers concisely in third person (e.g., 'Performs X, Y, Z. Use when...').
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description contains no concrete actions or domain-specific capabilities. Phrases like 'confirm the user objective' and 'validate that the request matches the documented scope' are abstract process steps, not specific skill actions. | 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 reads like internal process instructions rather than a skill description. | 1 / 3 |
Trigger Term Quality | There are no natural keywords a user would say. Terms like 'non-negotiable constraints', 'documented scope', and 'unsupported as' (which appears truncated) are not phrases users would use when seeking help with a task. | 1 / 3 |
Distinctiveness Conflict Risk | The description is extremely generic—confirming objectives and validating scope could apply to virtually any skill. It provides no domain, file type, or task-specific information to distinguish it from other skills. | 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 is extremely bloated, repeating its scope/purpose in at least four different sections and inlining extensive medical domain knowledge that Claude already possesses (SOAP format definitions, NER categories, negation detection patterns). The core actionable content — CLI commands, script paths, and the 5-step workflow — is buried under hundreds of lines of reference material that should either be in separate files or omitted entirely. The self-referential cross-links ('See ## Usage above') suggest poor organization.
Suggestions
Reduce content by 60-70%: Remove all medical domain explanations (SOAP definitions, NER categories, temporal extraction rules, negation detection) that Claude already knows, or move them to a separate REFERENCE.md file.
Eliminate redundant sections: The scope/purpose is stated in 'When to Use', 'Key Features', 'Workflow', and 'Overview' — consolidate into a single brief overview.
Move the detailed 'Core Capabilities' section (sections 1-6 with all code examples and tables) into a separate file like CAPABILITIES.md and link to it from the main skill.
Add explicit validation checkpoints for output quality — e.g., verify the generated SOAP note contains all four sections, check for negation accuracy, and confirm no PII leakage before returning results.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose with massive redundancy. The description, scope, and workflow are repeated multiple times in different sections ('When to Use', 'Key Features', 'Workflow', 'Overview'). Extensive tables explaining medical NER categories, temporal extraction, and SOAP classification rules are things Claude already knows. The content is ~400+ lines when it could be under 100. | 1 / 3 |
Actionability | Contains concrete CLI commands and Python code examples that appear executable, but many code blocks are illustrative rather than truly executable (e.g., importing from `scripts.soap_generator` with commented-out return values). The audit-ready commands section is good, but much of the 'Core Capabilities' section reads like API documentation for a hypothetical library rather than actionable instructions. | 2 / 3 |
Workflow Clarity | The Workflow section provides a clear 5-step sequence with a fallback path, and the Example Usage section has a 4-step run plan. However, validation checkpoints are weak — the only explicit validation is `py_compile` which just checks syntax. There's no feedback loop for verifying SOAP output quality or handling partial failures during the generation pipeline. | 2 / 3 |
Progressive Disclosure | Monolithic wall of text with no references to external files despite mentioning `references/` directory. All detailed API documentation, entity tables, classification rules, and format specifications are inlined. Content that should be in separate reference files (NER details, SOAP classification rules, temporal extraction specifics) bloats the main skill file enormously. Self-referential links like 'See ## Usage above' and 'See ## Workflow above' add confusion. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
90%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
8277276
- 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.