unstructured-medical-text-miner

Mine unstructured clinical text from MIMIC-IV to extract diagnostic logic.

Quality

60%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./scientific-skills/Evidence Insight/unstructured-medical-text-miner/SKILL.md

Quality

Content

48%Weight 40%Scale 1-5

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

The body contains a real, mostly-verified executable core (working Python API examples and CLI flags backed by scripts/main.py) wrapped in a heavy layer of generic template boilerplate. The main defects are broken invocation paths in the two primary usage examples, a documented flag that does not exist, and substantial padding that should be trimmed or moved to reference files.

Suggestions

Fix the broken invocation paths: replace 'skills.unstructured_medical_text_miner.scripts.main' with the actual bundle layout ('from scripts.main import MedicalTextMiner' / 'python scripts/main.py'), remove the nonexistent '--db-path' flag from the CLI example, and delete the 'cd "20260318/..."' example path.

Cut the generic template sections (Risk Assessment, Security Checklist, Evaluation Criteria, Prerequisites, Response Template, Output Requirements) or move them into references/audit-reference.md — they pad the context window without adding skill-specific instruction.

Delete the empty self-referential pointers ('See `## Features` above for related details', 'See `## Usage` above', 'See `## Workflow` above') and merge the four overlapping workflow sections (Workflow, Example run plan, Implementation Details, Error Handling) into one canonical sequence.

Dimension	Reasoning	Score
Conciseness	The ~360-line body carries substantial generic template filler: a 'Risk Assessment' table, a 'Security Checklist', 'Evaluation Criteria', 'Prerequisites' (`pip install -r requirements.txt` — no requirements.txt exists in the bundle), two separate 'References' sections, and empty pointers like 'See `## Features` above for related details' and 'See `## Usage` above for related details' that convey nothing. This matches 'noticeably verbose; several unnecessary explanations or padded sections' rather than the mostly-efficient anchor, because the boilerplate constitutes a large fraction of the file.	2 / 5
Actionability	There is genuinely executable guidance — the Python API example (load_notes, get_patient_texts, extract_insights) matches real methods in scripts/main.py and --input/--output/--extract/--subject-id match the argparse surface — but the two primary usage examples fail as written: 'from skills.unstructured_medical_text_miner.scripts.main import MedicalTextMiner' and 'python -m skills.unstructured_medical_text_miner.scripts.main' do not resolve against the actual bundle layout, the documented '--db-path mimic_iv.db' flag does not exist in main.py, and 'cd "20260318/scientific-skills/..."' points to a nonexistent path. Concrete guidance is present but key details are wrong, matching the incomplete-guidance anchor rather than the mostly-executable one.	3 / 5
Workflow Clarity	The Workflow section gives a clear numbered sequence ('Confirm the user objective... Validate that the request matches the documented scope and stop early...') with an explicit pre-execution checkpoint (the 'Quick Check' py_compile command and 'Audit-Ready Commands') and an error-recovery fallback ('If execution fails or inputs are incomplete, switch to the fallback path'). This matches 'clear sequence with most checkpoints present; minor validation gaps' — it falls short of the top anchor because the checkpoints are scattered across four overlapping sections (Workflow, Example run plan, Implementation Details, Error Handling) rather than one canonical validated sequence.	4 / 5
Progressive Disclosure	The bundle reference is real, one level deep, and clearly signaled ('references/audit-reference.md - Supported scope, audit commands, and fallback boundaries' — the file exists), and scripts/__init__.py and scripts/main.py match the documented script paths. However, large blocks that belong in reference files (the three JSON output schemas, the config.yaml specification, the risk/security tables) are inlined in the ~360-line body, and the dangling 'See `## X` above' pointers substitute for real navigation. Good structure with organization gaps matches the anchor rather than the clear-split top anchor.	4 / 5
	Total	13 / 20 Passed

Description

53%Weight 40%Scale 1-5

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 is concise and names a genuine niche (MIMIC-IV unstructured clinical text), but it undersells the skill's capabilities and entirely omits when-to-use trigger guidance. Adding an explicit 'Use when...' clause and enumerating the concrete extraction actions would lift it substantially.

Suggestions

Add an explicit 'Use when...' trigger clause, e.g. 'Use when working with MIMIC-IV NOTEEVENTS, discharge summaries, radiology reports, or other clinical notes that need structured extraction.'

Enumerate the concrete capabilities instead of the single summary phrase, e.g. 'Extract diseases, symptoms, and medications, detect negated findings, build diagnostic reasoning chains and treatment timelines from clinical notes.'

Include the natural trigger terms users would actually say (clinical notes, NOTEEVENTS, discharge summaries, medical NLP) to improve keyword coverage.

Dimension	Reasoning	Score
Specificity	"Mine unstructured clinical text from MIMIC-IV to extract diagnostic logic" names the domain (MIMIC-IV clinical text) and one concrete action (extract diagnostic logic), but omits the other capabilities the skill actually provides (entity recognition, relation extraction, timeline, negation detection). This matches the anchor for naming a domain with 1-2 concrete actions without comprehensive coverage, and falls short of the several-specific-actions anchor above.	3 / 5
Completeness	The description clearly answers 'what' (mine unstructured clinical text from MIMIC-IV to extract diagnostic logic) but contains no 'Use when...' clause or equivalent trigger guidance. Per the judging guideline, a missing 'Use when...' clause caps completeness at 3, matching the 'clear what but when missing' anchor.	3 / 5
Trigger Term Quality	"MIMIC-IV" and "diagnostic logic" are natural terms a user of this database would say, but common variations and synonyms (clinical notes, NOTEEVENTS, discharge summaries, medical NLP, radiology reports) are missing. Some relevant keywords exist, but coverage is not good enough for the 'good keyword coverage' anchor.	3 / 5
Distinctiveness Conflict Risk	"MIMIC-IV" is a strong niche trigger and "unstructured clinical text" is specific to medical data mining, giving mostly distinct triggers with only minor overlap risk against closely related clinical-data skills. It lacks the explicit trigger phrases needed for the clear-niche-minimal-conflict anchor above.	4 / 5
	Total	13 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: aipoch/medical-research-skills
Path: scientific-skills/Evidence Insight/unstructured-medical-text-miner/SKILL.md
Commit: 686e09d

Reviewed: 13 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.