linking-umls-concepts

Links entities extracted by OpenMed to UMLS Metathesaurus CUIs using the USER'S OWN UTS API key, with nothing from the Metathesaurus bundled or cached. Use when the user wants to normalize concepts across vocabularies to a single CUI, resolve synonyms via the UMLS, filter by semantic type, or cross-walk between SNOMED CT, ICD-10, RxNorm and MeSH through their shared CUI. Trigger keywords: UMLS, CUI, Metathesaurus, UTS API key, semantic type, TUI, MetaMap, QuickUMLS, concept normalization, cross-vocabulary. Pairs after OpenMed NER: consume Disease/Pharmaceutical/Chemical/Anatomy entities from openmed.analyze_text and resolve each span to a CUI out-of-process. UMLS is license-restricted — the Metathesaurus is NEVER bundled; every call uses the user's UTS account.

Quality

88%

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

Quality

Content

76%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 is highly actionable with executable code and a clear workflow, and it is well structured for a no-bundle skill. Its main weaknesses are redundant licensing emphasis that hurts conciseness and the absence of explicit validation/retry checkpoints in a batch workflow against a rate-limited API.

Suggestions

Add an explicit validation/retry checkpoint to the Workflow (e.g., retry on HTTP 429 rate limits, confirm a single ranked CUI before cross-walking) so the batch sequence has feedback loops.

Consolidate the licensing boundary into one authoritative callout and remove the repeated restatements in the intro and edge-cases to tighten conciseness.

Consider moving the 'Edge cases & gotchas' bullets into a references file (e.g., GOTCHAS.md) and linking from the main body to improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	Mostly efficient, code-driven prose that assumes Claude's competence, but the licensing boundary is restated four times (callout, intro, edge cases, closing) and a few edge-case bullets could be trimmed, leaving minor over-explanation.	4 / 5
Actionability	Two complete, copy-paste-ready Python blocks with a real API base, query parameters, and timeouts cover the common search/concept/crosswalk cases and the OpenMed hand-off loop.	5 / 5
Workflow Clarity	Six well-sequenced steps (extract, search, filter by TUI, rank, cross-walk, emit) are present, but this batch operation against a rate-limited API has no explicit validation checkpoints or retry/feedback loops in the workflow itself, capping clarity at 3.	3 / 5
Progressive Disclosure	A single, well-organized SKILL.md with clear section headers and one-level external reference links; the dense edge-cases block could be split into a reference file, leaving minor organization gaps.	4 / 5
	Total	16 / 20 Passed

Description

100%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 exemplary: it states concrete capabilities, provides comprehensive natural trigger keywords, and explicitly covers both what the skill does and when to use it within a sharply distinct niche. It reads in third person and avoids vague language throughout.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — link entities to CUIs, normalize concepts across vocabularies, resolve synonyms, filter by semantic type, and cross-walk between SNOMED CT/ICD-10/RxNorm/MeSH — with comprehensive coverage and no gaps.	5 / 5
Completeness	Explicitly answers both 'what' (links OpenMed entities to UMLS CUIs via the user's UTS key) and 'when' (normalize concepts, resolve synonyms, filter by semantic type, cross-walk vocabularies) with concrete trigger phrases.	5 / 5
Trigger Term Quality	An explicit 'Trigger keywords:' clause covers UMLS, CUI, Metathesaurus, UTS API key, semantic type, TUI, MetaMap, QuickUMLS, concept normalization, and cross-vocabulary, plus natural phrases in the 'Use when' clause.	5 / 5
Distinctiveness Conflict Risk	A clear niche — UMLS CUI linking gated on the user's own UTS API key with an explicit license boundary and OpenMed pairing — yields distinct triggers and minimal conflict risk with other skills.	5 / 5
	Total	20 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: maziyarpanahi/openmed
Path: skills/linking-umls-concepts/SKILL.md
Commit: 80da98c

Reviewed: 1 day 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.