Generate medical referral letters with patient summary, reason for referral.
36
33%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./scientific-skills/Academic Writing/referral-letter-generator/SKILL.mdQuality
Discovery
40%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 identifies a clear niche (medical referral letters) with reasonable specificity, but it lacks a 'Use when...' clause which is critical for Claude to know when to select this skill. The capability list is also somewhat truncated, ending abruptly after 'reason for referral' suggesting it may be incomplete.
Suggestions
Add a 'Use when...' clause with trigger terms like 'Use when the user asks for a referral letter, specialist referral, GP letter, consultation request, or clinical correspondence.'
Expand the capability list with more specific actions such as 'include clinical history, diagnosis, current medications, and requested specialist assessment'
Add common keyword variations users might use: 'specialist referral', 'doctor letter', 'clinical referral', 'consultation letter'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (medical referral letters) and some actions (generate, patient summary, reason for referral), but doesn't list comprehensive specific actions like formatting, template selection, or clinical data extraction. | 2 / 3 |
Completeness | Describes what the skill does (generate medical referral letters) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing 'Use when' caps completeness at 2, and the 'what' portion is also only moderately detailed, warranting a 1. | 1 / 3 |
Trigger Term Quality | Includes relevant terms like 'medical referral letters', 'patient summary', and 'reason for referral' which users might say, but misses common variations like 'doctor referral', 'specialist referral', 'clinical letter', 'GP letter', or 'consultation request'. | 2 / 3 |
Distinctiveness Conflict Risk | Medical referral letters is a clearly defined niche that is unlikely to conflict with other skills. The combination of 'medical', 'referral', and 'letters' creates a distinct trigger profile. | 3 / 3 |
Total | 8 / 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 significantly bloated with boilerplate, redundant sections, and template-generated content that doesn't serve Claude's needs. While it contains some useful elements (parameter table, input JSON example, CLI/API usage), these are buried in excessive scaffolding including risk assessments, security checklists, lifecycle metadata, and evaluation criteria that belong elsewhere or nowhere. The skill would benefit enormously from being reduced to roughly one-third its current size, focusing on the concrete workflow and input/output specifications.
Suggestions
Remove all boilerplate sections that don't help Claude execute the task: Risk Assessment, Security Checklist, Lifecycle Status, Evaluation Criteria, and the generic Response Template. These consume tokens without adding actionable guidance.
Consolidate the duplicated content: merge the two workflow sections, the two usage sections, and the two dependency listings into single authoritative versions with consistent information (e.g., pick one Python version requirement).
Remove the broken 'See ## X above' cross-references that point to sections appearing later in the document, and eliminate sections that merely restate what other sections already cover.
Add a concrete, complete end-to-end example showing actual input data going in and the resulting referral letter output, replacing the abstract workflow steps with specific validation checkpoints (e.g., 'verify the PDF opens and contains all required sections').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose and repetitive. Multiple sections restate the same information (e.g., dependencies listed twice with conflicting Python versions, usage examples repeated, workflow described in multiple places). Contains boilerplate sections like Risk Assessment tables, Security Checklists, Lifecycle Status, and Evaluation Criteria that add no actionable value for Claude. Self-referential 'See ## X above' links point to sections that don't precede them. Much of the content (what a referral letter is, output format descriptions) is knowledge Claude already has. | 1 / 3 |
Actionability | Provides some concrete commands and a Python API example with parameter signatures, plus an input JSON example and parameter table. However, the actual code is not fully executable—the Python API example uses `{...}` placeholders, and it's unclear what `scripts/main.py` actually does or produces without the bundle. The audit commands are concrete but the overall guidance mixes actionable steps with vague directives like 'validate the request' and 'choose the packaged workflow.' | 2 / 3 |
Workflow Clarity | There are numbered workflow steps, but they are generic and abstract ('Confirm the user objective,' 'Validate that the request matches the documented scope'). The 'Example run plan' provides a slightly more concrete sequence but still lacks explicit validation checkpoints with specific success/failure criteria. Error handling is mentioned but not integrated into the workflow as feedback loops. For a task involving document generation, there's no step to validate the output document structure. | 2 / 3 |
Progressive Disclosure | The content is a monolithic wall of text with 20+ sections, many redundant. References to `references/` and `assets/` directories exist but no bundle files are provided, making them unverifiable. Multiple sections reference other sections with broken 'See ## X above' patterns. Content that could be in separate files (risk assessment, security checklist, evaluation criteria, lifecycle status) is inlined, bloating the main skill file without adding instructional value. | 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 | |
73f6514
Table of Contents
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.