CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

24

Quality

13%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./scientific-skills/Academic Writing/automated-soap-note-generator/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

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 meta-instructions for how to handle any task rather than a description of a specific skill's capabilities. It lacks any concrete actions, domain specificity, trigger terms, or 'use when' guidance. The text also appears truncated ('unsupported as'), further reducing its utility.

Suggestions

Replace the generic process steps with concrete actions describing what the skill actually does (e.g., 'Generates project requirement documents' or 'Validates API request schemas').

Add a 'Use when...' clause with specific trigger terms that reflect what users would naturally say when they need this skill.

Identify the specific domain or task type this skill covers and name it explicitly to distinguish it from other skills.

DimensionReasoningScore

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 entirely abstract and could apply to any skill.

1 / 3

Completeness

The description fails to answer 'what does this do' in any concrete way and completely lacks a 'when should Claude use it' clause. It reads like generic 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 in requests.

1 / 3

Distinctiveness Conflict Risk

The description is entirely generic—confirming objectives and validating scope could apply to virtually any skill. It provides no distinguishing domain, file type, or task category, making it highly prone to conflicts.

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 verbose, inlining extensive medical NLP documentation that should be split across reference files and explaining many concepts Claude already understands (SOAP format, NER, negation detection, temporal extraction). While it provides some concrete CLI commands and a reasonable workflow skeleton, the signal-to-noise ratio is very low — the actionable content could be compressed to roughly 20% of its current size. The lack of progressive disclosure and the redundant/self-referential sections significantly reduce its effectiveness as a skill file.

Suggestions

Reduce content to ~80-100 lines by removing explanations of concepts Claude already knows (SOAP format definitions, what NER is, temporal extraction theory, negation detection categories) and move detailed API documentation for each capability into separate files in `references/`.

Eliminate redundant sections: merge the duplicate parameter tables, remove self-referential 'See ## X above' links, and consolidate 'When to Use' and 'Key Features' which largely repeat the description.

Add explicit validation checkpoints in the workflow, e.g., 'Verify the generated SOAP note contains all four sections before delivering' and 'Validate entity extraction results against input text before classification step.'

Create referenced files (e.g., `references/entity-types.md`, `references/soap-classification.md`, `references/output-formats.md`) and replace inline documentation with one-level-deep links to keep SKILL.md as a concise overview.

DimensionReasoningScore

Conciseness

Extremely verbose at ~350+ lines. Massive amounts of content Claude already knows (what SOAP notes are, what NER is, what negation detection is, medical entity types, temporal extraction concepts). Redundant sections (e.g., 'When to Use' repeats the description, 'Key Features' restates workflow, parameters listed twice, 'See ## Usage above' self-references). The skill explains basic medical documentation concepts at length rather than focusing on tool-specific instructions.

1 / 3

Actionability

Provides some concrete CLI commands (e.g., `python scripts/main.py --input ... --patient-id P12345`) and Python API examples, but many code examples are illustrative rather than executable — they import from `scripts.soap_generator` which may not exist as shown, and output is shown in comments rather than being verifiable. The audit-ready commands section is concrete and copy-paste ready, but the bulk of the 'Core Capabilities' section reads more like API documentation than actionable skill instructions.

2 / 3

Workflow Clarity

The 'Workflow' section provides a clear 5-step sequence with a fallback path (step 5), and the 'Example Usage' run plan has 4 numbered steps. However, there are no explicit validation checkpoints between steps (e.g., no 'verify output before proceeding' gates). The error handling section mentions fallbacks but doesn't integrate them into the workflow steps with concrete validation commands. For a tool generating medical documentation, the lack of explicit validation/verification steps is a notable gap.

2 / 3

Progressive Disclosure

This is a monolithic wall of text with no external file references despite mentioning `references/` directory multiple times. All content — from basic SOAP definitions to NER entity tables to temporal extraction to negation detection — is inlined in a single massive file. The detailed API documentation for each capability (sections 1-6) should be in separate reference files. Self-referential links like 'See ## Usage above' and 'See ## Workflow above' add confusion rather than structure.

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.

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

10

/

11

Passed

Repository
aipoch/medical-research-skills
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.