Skip to content

ajhcs/healthcare-agents

v2.0.0-beta.2Apache-2.0

Healthcare administration skills, six deep workflows and a custom workflow builder.

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

Beta · v2.0.0-beta.2 Use the versioned GitHub prerelease or pin healthcare-agents@2.0.0-beta.2 on npm. See the release evidence for the scope of host and model testing.

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 hereWhat I get
Build my own workflowCHNA interview-plan walkthroughAn editable local pack, case template and review checklist
Try a synthetic workflowRun the local example belowValidated aggregate calculations, with evidence and limitations
Use the skill in my AI hostConnect an approved host, then use a prompt belowA task-specific draft from the host model
Find a specialistExplore the catalogA 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 v2.0.0-beta.2
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.

Synthetic denial example: baseline 10 percent, current 18 percent, an increase of 8 percentage points

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 withGet a reviewable artifactSupported local calculation
Denial spikeCohort comparison, hypotheses, evidence pulls and recovery ownersBaseline/current rates, percentage points and relative change
Ambulatory access backlogDemand/capacity scenario and monitored access planShortfall, net weekly capacity and backlog clearance scenario
Survey readiness gapsStandard-to-evidence gap register and retest planMissing-evidence counts; no compliance certification
Prior authorization appealSource-linked administrative packet and document gap mapSupplied calendar window and missing documents
Payer underpaymentContract-linked variance registerUSD line/net variance, with overpayments retained
Discharge barriersAggregate barrier owners and dependenciesSupplied 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
DomainSpecialists
Clinical Operations8
Emergency Preparedness1
Health IT & Informatics6
Operations & Administration7
Payer & Managed Care6
Pharmacy Programs2
Population Health & Community Health3
Quality, Safety & Compliance7
Revenue Cycle & Finance6
Strategy & Advisory5

The Healthcare Agents router skill starts with the compact workflow index and opens the detail file for each selected workflow. The specialist fallback uses a compact role brief and opens the full prompt when needed. Free-text choose and workup calls offer discovery candidates. The host records inferred choices and their rationale with --selection. Use --workflow or --agent when the user explicitly selected the ID. A workflow selection can retain multiple requested workstreams. 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 release evidence identifies the checks and the revisions they cover.
  • 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