Healthcare Agents

Build and customize agents for the way your healthcare team works.

Healthcare Agents is a starting point for healthcare leaders to describe a workflow, adapt focused instructions and review the resulting work with a human owner. Start with your own task or use an existing specialist: investigate a denial spike, map survey evidence gaps or prepare an appeal packet. Local tools can validate inputs and calculate supported aggregate quantities.

Customize a workflow · Workflows · Specialists · Host setup · Evidence & evaluation

Development candidate · v2.0.0-beta.1 This README describes the checked-out beta. Publication is pending: npx healthcare-agents from the public registry does not yet deliver this candidate. Customer cloud-host qualification is also pending. See candidate status and the tested local Codex profile.

Quickstart

Start with the work you need to produce. Adapt a small instruction pack, review it against supplied evidence, then use it in your approved host:

I want to…	Start here	What I get
Build my own workflow	CHNA interview-plan walkthrough	An editable local pack, case template and review checklist
Try a synthetic workflow	Run the local example below	Validated aggregate calculations, with evidence and limitations
Use the skill in my AI host	Connect an approved host, then use a prompt below	A task-specific draft from the host model
Find a specialist	Explore the catalog	A focused role or workflow for the question

Make a community interview plan

Suppose you need a community health needs assessment (CHNA) stakeholder interview plan. Describe the decision it supports, the evidence you have, the people whose voices are missing and the person who must approve outreach. The walkthrough turns those choices into an editable local instruction pack, then shows how to review, revise or retire it.

Start from the community interview example. The builder checks its structure and creates files for your host to read. Your host drafts the plan; a community benefit director reviews the evidence, coverage, recruitment and consent before anyone is contacted. Building the pack does not install or activate it.

Review brief · Integration brief

Try the local denial example

This reproducible example pins the source beta baseline; use the installation guide for channel and host choices. Use an existing Node.js installation (the local profile requires Node ≥18.14.1) and npm:

git clone https://github.com/ajhcs/healthcare-agents.git
cd healthcare-agents
git checkout --detach 7b536b5ba707a74cc3b9208b658606f36c9a92c8
npm ci --ignore-scripts
node bin/cli.js admin run examples/admin-v2/denial-spike-workup.json

The synthetic case compares 100 denied claims out of 1,000 with 180 out of 1,000: 10% → 18%, up 8 percentage points. These are invented demonstration data, not patient records or measured customer outcomes. The calculation does not establish a cause or recoverable cash.

To inspect a workup draft with an explicit workflow selection:

node bin/cli.js workup "Commercial payer denial rate jumped" \
  --workflow denial-spike-workup --json

The CLI routes tasks, validates contracts and calculates supported quantities. The host model writes the administrative artifact. The CLI does not call a model or execute the operational workplan.

Ask your host for a useful artifact

After host setup, try one of these prompts with synthetic or approved aggregate evidence:

Use Healthcare Agents to investigate this denial-rate increase. Compare the supplied cohorts, separate observations from hypotheses, list missing evidence, and draft a recovery plan with owners and completion checks.

Use Healthcare Agents to review our survey evidence inventory. Map each supplied standard to its evidence, identify gaps, and return an owner-led retest checklist. Keep compliance conclusions with the accountable reviewer.

Use Healthcare Agents to prepare an administrative prior authorization appeal packet. Work from the supplied policy, decision and document inventory. Show source references, missing documents and deadline assumptions for human review.

More starter prompts · Example workup packets

Six workflows, six useful outputs

Start with	Get a reviewable artifact	Supported local calculation
Denial spike	Cohort comparison, hypotheses, evidence pulls and recovery owners	Baseline/current rates, percentage points and relative change
Ambulatory access backlog	Demand/capacity scenario and monitored access plan	Shortfall, net weekly capacity and backlog clearance scenario
Survey readiness gaps	Standard-to-evidence gap register and retest plan	Missing-evidence counts; no compliance certification
Prior authorization appeal	Source-linked administrative packet and document gap map	Supplied calendar window and missing documents
Payer underpayment	Contract-linked variance register	USD line/net variance, with overpayments retained
Discharge barriers	Aggregate barrier owners and dependencies	Supplied barrier counts and reported avoidable days

All six have synthetic cases, evidence requirements and observable completion gates. Read the workflow catalog and case contract for exact fields and validation rules.

Choose a workflow or specialist, combine approved evidence with optional local calculations, draft in the host, then review with a qualified human owner. A draft or calculated metric does not establish operational completion.

Every numeric input needs a source record, origin and as-of date. Missingness, contradictory evidence and unknown recoverable cash stay visible. Synthetic and aggregate modes cannot be silently mixed; invalid dates, unexpected fields and impossible denominators fail validation.

Explore the specialist catalog

The existing 51 specialists across 10 administrative domains and 16 workups remain available. Start with the selection guide, workup directory or CLI:

node bin/cli.js list --domain revenue
node bin/cli.js show revenue-cycle-specialist
node bin/cli.js admin list

Domain	Specialists
Clinical Operations	8
Emergency Preparedness	1
Health IT & Informatics	6
Operations & Administration	7
Payer & Managed Care	6
Pharmacy Programs	2
Population Health & Community Health	3
Quality, Safety & Compliance	7
Revenue Cycle & Finance	6
Strategy & Advisory	5

The Healthcare Agents router skill loads the selected workflow or compact role brief; full specialist prompts remain available when needed. Free-text choose and workup calls offer discovery candidates. The user or host interprets intent, negation and multiple goals, then supplies validated IDs or a structured selection. Explicit multi-selections retain every workstream. See routing authority and migration.

Connect your AI host

Start with the installation guide and choose the profile for your approved environment. The local Codex profile documents preparation, activation, removal and exact tested-host limits. It uses existing Node/npm; Python is optional through --stdio-bridge. Other clients need separate acceptance.

Host capabilities, limitations and developer commands · Custom workflow integration brief

Extend a workflow or bring source receipts

Build a local workflow

Define the outcome, specialist, human owner, evidence fields and acceptance criteria using the example contract or builder skill:

node bin/cli.js admin validate workflows/admin-v2/custom-example.json
node bin/cli.js admin build workflows/admin-v2/custom-example.json --output ./community-workflow

The new directory contains SKILL.md, a detailed reference, a source-attributed case template and a hash manifest. Existing output directories are refused. Custom workflows are instruction packs; the builder does not invent executable formulas, install services or grant external-action authority. A valid contract still needs task-level behavioral evaluation.

Import evidence receipts

The optional Data MCP receipt importer maps a pinned public-evidence bundle into one of the six case contracts. It retains receipts, lineage, missingness and conflicts in a custody sidecar. Operators supply exact field bindings; absent or contradictory evidence blocks case creation.

node bin/cli.js admin import-evidence examples/admin-v2/data-mcp/denial-spike-workup.bundle.json \
  --mapping examples/admin-v2/data-mcp/denial-spike-workup.mapping.json \
  --output ./imported-denials --python /path/to/python-with-pydantic

This optional step requires Python 3.11+ and the pinned validator dependency. The six receipt examples are wholly synthetic and were generated through the Data MCP producer CLI; they do not establish public metric availability or customer-host deployment. The eight MCP tools remain unchanged.

Evidence, ownership and safe use

Use synthetic or approved aggregate evidence in an approved environment. This package is not a PHI-processing environment. Its prompts and tools do not make final clinical, legal, coding, billing, audit or compliance decisions; qualified human owners retain that authority.

Source-family cards are leads to verify. The bounded primary source review records reviewed context and applicability limits. Payer terms, standards, deadlines and clinical facts need the applicable exact source and an accountable owner. External submissions, outreach and production changes require scoped authority. A calculated metric or draft does not demonstrate operational completion.

Trust and safety · Review protocols · Handoff map

What the evidence establishes

Environment qualification and model benchmark scores answer different questions. An install, tool call or arithmetic check can establish bounded software behavior. It cannot establish healthcare accuracy, usefulness or model superiority.

• Local checks: contracts, arithmetic, source attribution, failure handling, routing abstention, package installation and generated files. The candidate status records publication and qualification separately.
• Native host qualification: the Codex profile records installation, tool/workflow calls and restoration on a specified Ubuntu/Codex configuration. Other hosts require separate acceptance.
• Model outcome evidence: a prior-snapshot native Codex campaign used synthetic tasks, actual MCP calls and bounded factual/receipt grading. It loaded compact instructions; it was not rerun for the revised routing-authority/result-limit contract. Independent domain acceptance remains separate.
• External benchmark comparisons: baseline model runs use tools without skills. Skill-enabled evaluation is a separate condition. Historical rubric results and environment checks must not be presented as external model benchmark scores; this README makes no external benchmark score claim.

Maintainer checks and integration details · Historical prompt evaluation

Contribute and learn more

Preserve specialist identity, meaningful contracts and human ownership. Add realistic negative and conflicting-evidence cases when extending a workflow. Use the workflow contribution guide and report reproducible issues through the repository.

Keep one versioned release across package, lockfile, plugin and installer. Verify registry/repository payload identity before publication. Retained specialist review metadata is not current regulatory verification. See release publishing.

Installation · Platform guides · Evaluation guide · Visual identity and editable assets · Earlier project illustration · Apache-2.0 license