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
Quality
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 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%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
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.