Introducing our Agentic Framework for Computable Clinical Knowledge

We're releasing RH Skills: an open-source, agentic workflow toolset that turns clinical evidence — guidelines, quality measures, assessments, prior-authorization policies — into deterministic, computable rules. Structured artifacts that embed directly into EHRs, quality programs, and clinical decision support systems.

The problem it solves is real. Research shows it takes up to 17 years for clinical findings to reach routine practice. Published guidelines sit in narrative prose — PDFs, Word documents, web pages — that clinicians must interpret individually, inconsistently, and from memory. Computable rules close that gap: once encoded, a guideline fires consistently at the point of care, across every patient, every encounter, every system.

RH Skills makes that encoding reliable, repeatable, and inspectable.

Why this matters

The distance between "a guideline exists" and "a guideline is operating in a production EHR" is enormous. In practice it runs through several failure modes:

• Ambiguity. Narrative guidelines express clinical intent in prose. Two informaticists reading the same paragraph will encode two different PlanDefinition resources. Neither is wrong; both are under-specified.
• Inconsistency. A quality measure authored as CQL in one institution is rewritten from scratch at another, because there's no shared intermediate representation.
• Opacity. A prior-authorization policy lives in a PDF, invisible until it becomes an obstacle to care.
• Hallucination risk. An LLM asked to "write a CQL measure for HbA1c screening" will produce plausible CQL that may not compile, may not align to the source measure, and may silently use wrong codes.

RH Skills addresses all four. It produces structured, versioned, human-readable intermediate artifacts (L2) that a reviewer can inspect before they become FHIR resources (L3). And it keeps all deterministic work — file I/O, checksums, schema validation, package assembly — in the CLI, while all clinical reasoning lives in auditable agent prompts.

How it works

The framework moves clinical knowledge through three artifact levels:

L1 Raw / Normalized        L2 Structured              L3 Computable
─────────────────────      ─────────────────────      ─────────────────────
PDFs, Word docs,       →   Typed YAML artifacts   →   FHIR R4 JSON + CQL
web pages, HTML            (human-editable)           (machine-executable)

Seven L2 artifact types are supported: evidence-summary, decision-table, care-pathway, terminology, measure, assessment, and policy. Each type maps to a specific formalization strategy that produces the right FHIR R4 resources — PlanDefinition, Measure + Library, ValueSet, ConceptMap, Questionnaire, and more.

Four pipeline stages

Every topic moves through four stages:

1. Discovery — Find and evaluate evidence sources. Search PubMed, ClinicalTrials.gov, published guidelines, and terminology registries. Build a curated source registry with domain advice, enforce source constraints, and download open-access sources.

2. Ingest — Acquire and normalize. Register local sources, convert PDF/DOCX/HTML to Markdown, classify by evidence level, and annotate clinical concepts. The output is machine-readable L1 content ready for extraction.

3. Extract — Derive structured L2 artifacts. The agent proposes artifact names and types from the seven-type catalog. A reviewer approves each one. The agent then generates structured YAML, and the CLI validates and renders verification reports with Mermaid diagrams.

4. Formalize — Convert L2 artifacts into L3 FHIR R4 resources. Type-specific strategies handle PlanDefinition, Measure + CQL Library, ValueSet, Questionnaire, and related resources. The output is a FHIR NPM package — standard, deployable, portable.

Plan → Implement → Verify

Every stage transition follows a mandatory three-step pattern:

• Plan — The agent proposes what to do: which artifacts to create, which sources to use, what convergence strategy to apply. It writes a review packet.
• Implement — After human approval, the agent executes via deterministic CLI commands.
• Verify — Non-destructive validation checks schemas, required fields, and cross-artifact consistency. Reports blocking errors and advisory warnings.

No artifact is created without explicit reviewer approval. Every state change is tracked in tracking.yaml. The framework is deterministic where it matters and agentic where it helps — and the boundary is explicit.

Separation of concerns

The guiding principle is:

All deterministic work in rh-skills CLI commands. All reasoning in SKILL.md agent prompts.

• The CLI handles: file I/O, SHA-256 checksums, YAML reads/writes, schema validation, event tracking, package assembly.
• The agent handles: clinical reasoning, artifact naming, source evaluation, convergence strategy, CQL authorship.

This means every output can be inspected, every step can be replayed, and no hallucinated logic makes it past the plan gate.

Two usage modes

Both modes use the same CLI. The agent simply automates the reasoning layer. Install the skills into your project with:

1# First-time setup — prompts for which agents to support
2rh-skills skills init
3
4# Check for drift
5rh-skills skills check
6
7# Update after upgrading
8pipx upgrade rh-skills && rh-skills skills update

Supported platforms include Claude, Cursor, Copilot, and Gemini — each with their own install location. A .rh-skills-lock.yaml tracks versions.

ReasonHub MCP integration

The skills optionally connect to the ReasonHub MCP service for terminology support: SNOMED CT, LOINC, ICD-10-CM, RxNorm, and UCUM. Value set expansion, code-system search, and code validation all resolve against a live server — not training weights, not cached snapshots.

Without it the skills still function, but terminology and value_sets[] sections will contain placeholder text rather than validated codes. Setup is free and takes under a minute.

What you produce

A completed topic yields a FHIR NPM package containing:

• PlanDefinition resources (clinical protocols, decision rules, coverage policies)
• Measure + Library resources (quality measures with CQL logic)
• ValueSet + ConceptMap resources (coded terminology)
• Questionnaire resources (screening instruments, DTR forms)
• Evidence + EvidenceVariable resources (graded clinical findings)
• ImplementationGuide resource (package metadata)

These are standard FHIR R4 artifacts, deployable to any FHIR-compatible system.

Get started

1# Install
2pipx install git+https://github.com/reason-healthcare/rh-skills.git
3
4# Verify
5rh-skills --help
6
7# Create a topic and start working
8rh-skills init my-topic
9rh-skills status my-topic

Full documentation is in the repo:

• Introduction — high-level orientation
• Getting Started — installation and first walkthrough
• Workflow — lifecycle model and directory structure
• Commands — full CLI reference

The repo is open source. File issues, send PRs, fork and customize. If you're building computable content — guidelines, measures, CDS rules, prior-auth policies — and you want the output to be inspectable, deterministic, and standards-aligned, try it. We'd like to hear where the gaps are.