Healthcare Domain-Aware AI Workflows

Most AI coding assistants are excellent at generic software and quietly wrong about healthcare. Ask one to scaffold a FHIR API and it gives you a service that looks right — until you notice it's holding a Condition as a string, missing US Core must-supports, and using a Patient.identifier system that doesn't exist. Ask it to do a HIPAA review and it produces a confident checklist with no bearing on the code in front of it. Ask it to model an oncology product without telling it about line-of-therapy, performance status, or biomarker testing — and you'll get something that has never met a real patient.

The model isn't stupid. It's generic. And healthcare is the opposite of generic: it's a domain with a regulator in every room, a code system behind every concept, a clinical workflow around every screen, and a procurement process around every decision.

This post is about what we think domain-aware AI workflows actually look like in practice, and the announcement of a project that's been a long time coming: the initial set of Reason healthcare tech skills — an open, installable set of skills for AI coding agents, purpose-built for the people who build healthcare technology.

You can install them now:

npx skills add https://github.com/reason-healthcare/health-skills/tree/dist

The repository lives at github.com/reason-healthcare/health-skills, and it's open source. Try them, break them, fork them, and most of all — tell us what you wish they did that they don't.

What "domain-aware" means in a coding workflow

In a healthcare software project, a domain-aware AI workflow has a few properties that the generic version doesn't:

• It knows the regulatory markets it might be operating in. A US health plan, a US provider, an EU medical device manufacturer, and a US+EU digital health startup all live under different rule sets. The model shouldn't silently default to HIPAA because that's the most common one in the training data — it should look at the repo, ask if the evidence is unclear, and persist its best guess so it doesn't have to re-derive it every run.
• It knows the standards it should be reaching for. US Core before custom profiles. QI-Core before ad hoc. LOINC for labs, SNOMED CT for conditions, RxNorm for medications, ICD-10 for billing. The right resource for the right job — not whatever the model vaguely remembers.
• It knows the lifecycle of a healthcare software change. Discovery before specs. Modeling before API design. Compliance, human factors, and documentation reviewed alongside the code, not bolted on at the end. A generic dev workflow can ship a feature; a healthcare workflow has to also survive an audit, a clinician review, and an integration test against an EHR.
• It produces report-only output where the right answer is "stop and let a human decide." When the question is "are we HIPAA-compliant?" or "is this UI safe for a tired nurse at minute 14 of a 12-hour shift?" the answer shouldn't be a confident generation. It should be a structured set of findings a human can act on.

Generic AI is fine for a lot of this in isolation. The problem is the cost of getting it wrong. A wrong FHIR profile is a downstream integration bill. A wrong compliance finding is a release that shouldn't have shipped. A wrong discoverability story is a product that won't get adopted. Domain-awareness is what makes those costs tractable.

Why we built this as a skills repo

The natural way to package domain-aware workflows for AI agents is a skill — a focused, self-contained set of instructions, references, and helpers that an agent loads when it recognizes a matching task. Skills are composable, versionable, and easy to share. They survive across agents and across teams. They don't require anyone to adopt a new product, a new runtime, or a new vendor. They just need an agent and a use case.

We've been writing healthcare skills internally for over a year — for our own client work, for our own platform, and for our own teams. The majority of that material has been hardened through real engagements and is now ready to share.

The package is vendor-neutral. None of the skills require ReasonHub to be useful. They'll work with Claude Code, Pi, OpenAI Codex, Google's agent tooling, or whatever you happen to run. The only requirement is an agent that understands the skills format.

The initial set: eight skills across the healthcare dev lifecycle

The skills are organized by where they sit in the lifecycle of a healthcare software project. The same skeleton is useful in greenfield work and brownfield work — what changes is which skills fire, and when.

Bootstrap

health-init — Start here, in any project. The skill reads repository evidence and persists a small .health-context.yaml (jurisdiction, primary audience, project stage) so every other healthcare skill downstream doesn't have to re-derive the same answers from scratch. Crucially, it doesn't force a confident classification from weak signals — a sparse repo or a tooling-only directory gets an unclear, not a confident guess.

Planning

health-product-discovery — Stress-test a healthcare product idea before committing to specs. Maps incentive structures (in healthcare, the person who uses, buys, benefits from, and pays for the product are almost never the same person), adoption dynamics (EHR gravity, clinician burnout, committee decisions), evidence requirements, payment-model dependencies, and workflow integration. Comes with explicit US and EU market overlays so payment, procurement, and market-access assumptions stay visible and debatable.

Implementation

health-fhir-api-design — Design FHIR R4 API interactions: search queries, operations ($expand, $validate, $translate, etc.), validation strategy, workflow patterns, and custom SearchParameter / OperationDefinition resources. You give it the requirement; it gives you a concrete R4 approach with the trade-offs documented. This is the interaction layer; pair it with health-fhir-modeling.

health-fhir-modeling — Map domain concepts to FHIR R4 resources and understand profile compliance. Selects the right base resources, reads US Core and QI-Core constraints, models relationships, finds existing extensions, and applies terminology bindings. Produces annotated example instances — built for app developers, not profile authors.

Verification

This is the part generic AI workflows tend to skip, and the part that matters most in a regulated domain. Four skills, all report-only:

health-refactor — Produce a scope-bounded, plan-only refactoring assessment for healthcare codebases. Resolves a bounded file set via git range, file area, or symbol/dependency context. Proposes US, EU, or US+EU overlays from evidence. Then orchestrates healthcare-aware code refactoring, human-factors review, and regulatory review into a unified plan with findings and a prioritized checklist. Never modifies code.

health-docs — Audit and consolidate documentation against a seven-dimension hierarchy with jurisdiction-aware regulatory detection. Two modes: analyze for a coverage assessment, and document for consolidation and gap-filling. Reuses .health-context.yaml when present, and composes other healthcare skills for deep review passes.

health-compliance-review — Deterministic regulatory and security findings from engineering evidence. Covers HIPAA (HHS/OCR), ONC (21st Century Cures, HTI-1), CMS, FDA (SaMD/510(k)), GDPR (EU DPA), NHS Digital (DTAC), EHDS, and ISO 27001. Selects the right jurisdiction overlay from repo evidence; if it's mixed, it says so explicitly rather than silently defaulting to US. No code changes. Three tiers of confidence — confirmed, likely, and inferred — so reviewers can spend their time where it counts.

health-human-factors — Review healthcare and EHR software UIs against a comprehensive design style guide grounded in NIST, FDA, IEC 62366, ISO 9241, ISO 14971, WCAG 2.1, ONC SAFER, and HL7 FHIR. Patient safety, usability, accessibility, and data clarity — without modifying code or designs. The findings from this skill are the ones you want a clinician to read.

How the skills fit into existing agent frameworks

We didn't want to ship something that competes with the structured agent workflows people already use. The skills are designed to slot in as overlays on top of common healthcare-adjacent frameworks:

• Spec-Kit — best mapped to greenfield, exploration, and brownfield phases. Run health-init before constitution, health-product-discovery during specify, the FHIR pair during plan, and the verification set during analyze.
• OpenSpec — the workflow this repo itself uses. health-product-discovery during explore, the FHIR pair during continue-change for Design/Specs, health-refactor and health-docs during apply-change, and the full verification set during verify-change.
• BMAD — the health-* skills work as specialist overlays on top of the agent roles, not as replacements. bmad-analyst gets health-init and health-product-discovery; bmad-architect gets the FHIR pair; bmad-ux-designer gets health-human-factors; bmad-agent-dev gets health-refactor and the verification discipline.

The full mapping lives in docs/framework-skill-mapping.md, including copy-pasteable AGENTS.md snippets for each framework.

For multi-skill work, the biggest efficiency gains come from composition — running several skills in parallel against the same scope and merging the findings:

Skills accept a scoped invocation mode — a "Modes" section that defines both standalone and scoped behavior. In scoped mode, the skill accepts a pre-determined file list from an orchestrating skill and returns findings-only output. That's how the composition pattern works without turning the agent into a chatbot.

How the skills are built and maintained

A few decisions we made early that shaped the project:

• The repo is the source of truth. Skills are authored in skills/ on main. Local install trees under .agents/skills/, .claude/skills/, and the like are generated by scripts/compose_skills.py, not hand-edited. Consumers install from the dist branch, which is a clean publishable layout built by scripts/publish_dist_branch.py. Edit source on main → validate → compose → publish to dist.
• .curated vs .experimental. Curated skills are reviewed and ship to dist. Experimental skills are still being shaped and don't. The first eight skills are curated; everything new starts in experimental and graduates.
• A CI quality gate. Pull requests run validate_skill_library.py, compose_skills.py, and the skills.sh compatibility check. If a skill doesn't validate, doesn't compose, and isn't installable, it doesn't ship.
• OpenSpec-driven creation. New skills go through proposal → scaffold → design → specs → tasks → implementation → verification → archive. The full process is in docs/skill-creation-guide.md.
• Overlays, not forks. Agent-specific differences live under profiles/<agent>/<skill>/ as SKILL.append.md or agents/openai.yaml overlays. The base skill stays clean; the agent-specific version is the only one that drifts.
• Jurisdiction awareness is a feature, not a footnote. US and EU behavior diverges often enough that the relevant material is broken into per-skill references/us-*.md and references/eu-*.md overlays, with one top-level skill per concern. The skill selects the right one from evidence, including the option of us+eu or unclear if the repo doesn't commit.

The goal is for the skills to behave like a real, maintained open-source library — not a one-off dump.

How to try it

The shortest path:

# Install the full curated set
npx skills add https://github.com/reason-healthcare/health-skills/tree/dist

Then point your agent at any healthcare repository and start with health-init. It will read the repo, propose values for jurisdiction, audience, and stage, and persist a .health-context.yaml so the rest of the skills can reuse them. From there, the rest of the lifecycle is yours to walk.

If you want to author or contribute, the contribution guide is in DEVELOPER.md. If you want to read the rationale before you install, the docs/ directory has the repository model, the framework mapping, the jurisdiction-aware overlay design, and the skill creation guide.

What we need from you

This set is shaped by the projects we and our clients have actually shipped. The next set should be shaped by the projects you are shipping — the ones we don't see.

If you're building in health tech — provider, payer, vendor, society, consultant, in-house team, public sector, research, anything — and you want AI workflows that respect the standards, the regulators, the clinicians, and the patients in the loop, we'd love to hear from you. Specifically:

• Try the skills and tell us where they fall short. A skill that gives the wrong answer is a bug report. A skill that gives a confidently wrong answer is a priority bug report.
• Tell us what skill is missing entirely. If you keep reaching for the same prompt that doesn't exist as a skill, that's a skill we should write.
• Tell us what shouldn't be a skill. Some things are better as patterns, principles, or just careful human review. We want to know what those are too.
• Open issues, send PRs, fork and customize. The repo is open for a reason. The dist branch is generated; main is where the work happens.

Thanks for reading. The best healthcare AI isn't the one that knows the most about medicine. It's the one that knows the most about your medicine, your market, your patients, and your standards. Skills are how we get there. Let's build the rest of the catalog together.