ReasonHub Skills: Resolution, Not Retrieval

We just released three terminology skills for AI agents, and they were built around a deliberate, slightly contrarian idea: every code the agent returns is looked up against a live terminology server. SNOMED CT, LOINC, ICD-10-CM, RxNorm. Not retrieved from training weights. Not guessed. Not paraphrased from memory. Resolved.

The skills are open source, install in a couple of minutes, and plug into any agent that understands the skills standard. They live in reason-healthcare/reasonhub-skills on GitHub, and they're built on the ReasonHub MCP server at reasonhub.app. The post below is the longer version of the LinkedIn announcement — what's actually inside, how it works, what it unlocks, and where the gaps are.

The model we picked, and the one we didn't

There's a version of "AI does terminology" that works fine in a demo and breaks the moment a downstream system touches it. A model takes a clinical phrase, picks a code that looks right, returns it, and the calling code round-trips it through an expansion, a crossmap, a measure, a registry, a payer. Most of the time the code passes. Some of the time it doesn't, and the failure mode is the worst kind: the code is plausible. It exists. It just isn't the right one.

That's the failure mode we set out to make impossible. The mechanism is straightforward: the model is not allowed to invent a code. The model is allowed to ask. Asking goes to a terminology service that returns the real code, with the real hierarchy, in the real FHIR shape. The model orchestrates. The terminology service resolves.

Concretely, that means:

• No "I think the code is E11.9" — the model asks, the service returns the actual E11 series, the model picks the one that fits.
• No "this is roughly the right SNOMED concept" — the service walks the IS-A hierarchy and the attribute relationships, and returns the actual concepts that match.
• No quietly-wrong RxNorm ingredient — the service traverses ingredient → product, returns the actual generic clinical drugs.
• No "this LOINC is close enough" — the service uses LOINC's multi-axis filters (CLASS, COMPONENT, SYSTEM, panel-parent) and returns codes that actually belong to the right hierarchy.

This is the difference between retrieval and resolution. Retrieval finds something. Resolution finds the right thing and proves it.

What's in the box

The repo ships four files in the skills/ tree. Three are user-triggered. One is shared reference material. The three are the ones you ask an agent to run.

reasonhub-snomed-semantic

Query SNOMED CT using its semantic attribute relationships.

SNOMED CT is unique among clinical terminologies: every fully-defined concept carries explicit attribute relationships encoded as FHIR properties — finding site, causative agent, associated morphology, procedure site, and so on. That means you can answer "all disorders of the cardiovascular system" or "all conditions with infarct morphology" as a structured query, not a keyword search.

The skill walks the full workflow: find the pivot concept, inspect its relationships, choose the right attribute, build a valueset_expand filter that returns exactly the right set of codes. The output is a FHIR ValueSet populated with concepts that actually exist in the hierarchy, in the right version of the terminology.

reasonhub-clinical-search

Search ICD-10-CM, LOINC, and RxNorm by clinical concept, then build a property-filtered FHIR ValueSet.

Most clinical data lives in ICD-10-CM (diagnoses), LOINC (lab and clinical observations), and RxNorm (drugs). Each system has its own query model:

• ICD-10-CM has a hierarchy and tabular exclusions — the skill walks the chapter/subcategory structure and pulls all the descendants.
• LOINC has multi-axis filters — CLASS, COMPONENT, SYSTEM, METHOD, TIME, plus panel-parent navigation for panel codes.
• RxNorm has ingredient → product navigation, with separate axes for clinical drug vs. branded drug vs. dose form.

The skill detects which code system fits the question, prompts the user when it's ambiguous, and constructs the ValueSet against the live terminology server — not a snapshot. Use this when you know the data lives in ICD-10/LOINC/RxNorm. Use snomed-semantic for relationship queries that need SNOMED's depth.

reasonhub-terminology-crossmap

Map a code from any clinical terminology into SNOMED CT, and then use the SNOMED model.

ICD-10-CM, LOINC, and RxNorm all have strong use cases but limited semantic depth. SNOMED CT's attribute model is what you want when the question is about relationships — what's adjacent, what causes this, what is this a finding site of. The crossmap skill is the bridge: given a code in any of the three, find its SNOMED equivalent (and an equivalence statement), and from there use the snomed-semantic skill to query relationships.

The output is a FHIR ConceptMap (source → SNOMED mapping with declared equivalence), a FHIR ValueSet of attribute-filtered concepts, and a provenance table so the mapping is auditable.

reasonhub-expand-mechanics (shared reference)

Not a user-triggered skill. It's the debugging checklist for valueset_expand — failure modes, universal CLI fallbacks, bulk Python scripting for large expansions, truncation handling. The other three skills consult it when expansion goes sideways. You don't need to install it directly; it comes along for the ride.

What that unlocks for a terminologist

The skills don't replace the terminologist. They remove the part of the terminologist's day that's pure mechanics — typing the right filter, walking the right hierarchy, writing the right ValueSet URL, double-checking the right code actually got returned. The part that's judgment — what the clinical question actually is, which hierarchy traversal makes sense, what counts as "complete" — stays with the human.

Three concrete interactions, lifted from the README, that show what changes:

"Give me all SNOMED disorders caused by Staphylococcus aureus for an HAI dashboard."

I need all SNOMED disorders attributed to Staph aureus for an HAI dashboard —
cellulitis, endocarditis, bacteremia, osteomyelitis, toxic shock syndrome,
pneumonia. Use causative agent Staphylococcus aureus.

The agent uses reasonhub-snomed-semantic. It resolves "Staphylococcus aureus" to the SNOMED organism concept, inspects the Causative agent attribute on disorder concepts, builds a valueset_expand filter that returns every disorder with that causative agent, and returns a ValueSet of the codes that actually exist in the hierarchy. The result is the set you'd want — not a hand-curated guess, not a text-search miss-and-include, not a hallucinated "all infections of any kind."

"Build a cross-system eCQM bundle: T2DM diagnoses, glucose LOINC observations, metformin RxNorm products."

For a diabetes management eCQM I need three ValueSets in one resource: all
T2DM ICD-10 diagnoses, all active glucose LOINC observations, and all generic
metformin RxNorm drugs. Combine into a single cross-system ValueSet.

The agent uses reasonhub-clinical-search. The skill detects that three code systems are in play, walks the E11 subcategory hierarchy in ICD-10-CM, applies the LOINC CLASS and COMPONENT filters to find active orderable glucose observations, and walks the RxNorm ingredient → generic clinical drug product path for metformin. The result is a Bundle containing three ValueSet resources, each server-validated, all rooted in their respective hierarchies.

"We have I25.10 in our encounter data. Crossmap to SNOMED and pull coronary procedure codes."

We have I25.10 (Atherosclerotic heart disease) in our encounter data and need
a ValueSet of coronary procedures to match against it — PCI, CABG,
angiography, stent placement. Map the ICD-10 code to SNOMED and then pull
all procedures on that artery.

The agent uses reasonhub-terminology-crossmap to map I25.10 into SNOMED (the result is a ConceptMap with declared equivalence and a provenance table), then reasonhub-snomed-semantic to walk the SNOMED procedure hierarchy using the Procedure site attribute (coronary artery structure) to return the right set of coronary procedure codes. The two skills compose — that's the point. The crossmap is the entry point; the semantic query is the follow-through.

In all three cases, the expert drives the clinical question. The skill handles the lookup, the hierarchy traversal, the ValueSet construction. The output is inspectable — you can read the filter, you can read the returned codes, you can re-run the expansion — and standards-aligned (FHIR ValueSet, ConceptMap, Bundle).

How to install it

Two minutes, give or take. Detailed per-agent instructions are in the repo's INSTALL.md. Short version:

1# 1. Sign up at reasonhub.app and copy your access token from Settings
2
3# 2. Install the skills
4npx skills add reason-healthcare/reasonhub-skills
5
6# 3. Install the CLI helper (for direct scripting outside the agent)
7curl -fsSL https://raw.githubusercontent.com/reason-healthcare/reasonhub-skills/main/bin/reasonhub-skills \
8  -o ~/.local/bin/reasonhub-skills && chmod +x ~/.local/bin/reasonhub-skills
9
10# 4. Add the ReasonHub MCP server to your agent's config
11# (with the bearer token from step 1)

It works with any agent that understands the skills standard — Claude Code, Pi, OpenAI Codex, Cursor, and others. The MCP server is at https://reasonhub.app/mcp. The CLI is a thin Python wrapper that calls the same MCP tools, for the cases where you want to script expansions outside an agent session.

If you're on Claude Desktop specifically, the skill-file discovery isn't supported, so the docs walk you through a project-custom-instructions workaround. It's a quirk of that client, not of the skills.

What this is not

A few things, so nobody's surprised:

• It's not a replacement for terminology work. A terminologist who knows their hierarchies, their value sets, and their downstream systems is still the source of truth on what a query should return. The skill removes the mechanical distance between the question and the answer. It doesn't replace the question.
• It's not a model trained on SNOMED. The skill doesn't try to teach a model the SNOMED hierarchy. It connects the model to a real, versioned, server-side terminology that knows the hierarchy. The training data drifts. The server doesn't.
• It's not specific to one terminology. Three of the four major clinical code systems (SNOMED CT, LOINC, ICD-10-CM, RxNorm) are first-class. UCUM, CPT, and others can be added — the framework is open, and the crossmap skill can move between systems.
• It's not finished. Three skills is the v1 set. There's a list below.

What we want feedback on

These are the first three. The list below is roughly the order we expect to grow it in. It's shaped by what we run into and what we think the next-most-useful shape is. We're not precious about that ordering.

• More clinical-search coverage. Mental health (SNOMED + DSM crossmaps), oncology (mCODE-aligned), social determinants (Gravity), pediatrics. Each of these has its own value set patterns that deserve first-class skills.
• Drug-class and NDC-level navigation. RxNorm is good for generic clinical drugs. NDCs, drug classes, and the formulary hierarchy are an adjacent problem with its own idioms.
• Cohort definition assistance. "Find me all patients with stage III colorectal cancer who had a complete response to neoadjuvant chemo" is a problem the skills should be able to help with, especially as it composes with mCODE and mCODE-shaped data.
• Audit and provenance tooling. When the model is allowed to resolve, the audit story is dramatically better than when it's allowed to invent. We want a CLI-level tool that produces an audit trail for any ValueSet or ConceptMap the skills produce — what was asked, what was returned, what filter was used, which version of the terminology was consulted.
• Evaluation harnesses. Golden queries with known-correct ValueSet outputs, runnable in CI. The skills should be testable the same way the standards they're based on are testable.
• More languages for cross-system mapping. ICD-11, ICD-10-CM, and SNOMED's international editions are where a lot of cross-border work happens. The crossmap skill is structured to extend; we'd love to hear where the demand is.

You can file issues, send PRs, fork and customize. The repo is MIT. Reach out the usual ways: GitHub issues, or in the ReasonHub community.

The part under the part

The reason this set exists in this shape is that we kept running into the same problem in different costumes. A model would generate a ValueSet URL that looked right. An expansion would return codes that almost fit. A measure would compute over a denominator that was 80% right. The errors were never the kind that throw a stack trace. They were the kind that pass review and look fine in a meeting.

The fix isn't a better prompt. The fix is structural: don't let the model invent a code when it can ask. Don't let the model paraphrase a hierarchy when it can walk one. Don't let the model return a ValueSet that wasn't expanded. Every layer of "ask the server" we add is a layer of plausible-but-wrong output we close off.

The skills in this repo are three of those layers, packaged for the agent workflows people are already running. The terminologist still drives. The model still orchestrates. The server resolves. The output is inspectable, and the inspectability is the point.

If you build terminology work in agent workflows — value sets, concept maps, semantic queries, the boring middle of every measure and every registry — try these. The ones in the box do what they say. The ones we don't have yet, tell us. The next batch should be shaped by the teams that hit the gaps.

Thanks for reading. Resolution beats retrieval. The server knows. Let's use it.