ajhcs/healthcare-agents

Healthcare Agents

51 specialist AI agents for US healthcare administration. Installable prompts and skills for Claude Code, Codex, OpenCode, Cursor, Copilot, and other agentic coding tools.

Healthcare Agents is a model-agnostic prompt library for healthcare administration work: revenue cycle, quality and compliance, clinical operations, payer relations, health IT, population health, pharmacy programs, operations, strategy, and emergency preparedness.

Each agent is a long-form Markdown specialist with YAML frontmatter, role-specific source awareness, compliance boundaries, operational workflows, concrete deliverable templates, best-input guidance, output modes, and cross-agent handoff rules. The pack installs into tools that support subagents, custom instructions, repository rules, or SKILL.md folders.

TL;DR

These agents are for healthcare administration support. They are not clinicians, attorneys, auditors, coders of record, billing authorities, or a safe PHI-processing environment. See Trust and Safety for scope, PHI, human escalation, source freshness, and eval limits.

Versioned CSO Review Protocols

The Review Protocol Registry is a separate machine-readable seam from the general prompt catalog. It routes exact claims to seven competence classes and returns canonical ushso.strategic-review.v1 records over frozen evidence, identity, computation, claim, and Decision Scenario hashes.

healthcare-agents review protocols --json
healthcare-agents review evaluate --input request.json --output review.json

The evaluator validates model-assisted candidate assessments; it does not make professional judgments. Human reviewers retain competence verification, material disagreement resolution, adjudication, and release authority.

Healthcare Admin Workup Engine and Operator OS

The Workup Engine routes a plain-language healthcare administration problem to a canonical workflow, primary specialist, supporting handoffs, missing questions, evidence list, safety boundaries, and a platform-ready prompt. Operator OS adds the release-gated layer around those workflows: coverage status, offline evidence packs, citation cards, fixture provenance, package validation, and secure-environment defaults.

Use the Workup Engine when you want a structured first pass for an operational problem. Use the Operator OS commands when you need to inspect the evidence-control surface behind that workflow, generate a local evidence-pack scaffold, or verify which workflows have exemplar or standard-pack coverage.

healthcare-agents workflows
healthcare-agents workflow denial-spike-workup
healthcare-agents operator-os coverage
healthcare-agents evidence-pack list
healthcare-agents evidence-pack show denial-spike-workup
healthcare-agents evidence-pack scaffold clean-claim-rate-decline
healthcare-agents workup "Commercial payer denial rate jumped 18 percent after a policy change and our AR days are climbing."
healthcare-agents workup "Commercial payer denial rate jumped" --data-mode synthetic_only
healthcare-agents workup "Commercial payer denial rate jumped" --data-mode public-evidence
healthcare-agents workup "Prepare a HIPAA evidence checklist for a vendor security review." --target copilot
healthcare-agents export m365-declarative-agent denial-spike-workup

What a workup returns

Each routed workup includes:

• the selected workflow and routing confidence;
• the primary specialist and handoff agents;
• missing required inputs and optional evidence questions;
• evidence to collect from local systems or accountable owners;
• red flags and safety constraints;
• a platform-specific prompt for Codex, Claude, GitHub Copilot, or Microsoft 365 Copilot;
• evidence-pack context when the workflow has Operator OS coverage;
• optional fixture case data when an explicit data mode asks for it.

Operator OS coverage

Since version 1.5.0, all 16 workflow-pack entries have an Operator OS status. Denial Spike is the first exemplar; the remaining workflows ship as standard packs with offline evidence metadata and citation-card scaffolds.

The source of truth is workflows/operator-os-coverage.json. The human-readable table lives in Operator OS Catalog Coverage.

Denial Spike is the first Operator OS exemplar. It ships with a versioned, offline-first evidence pack and citation cards that identify source families, lookup paths, review owners, verification status, and red flags without requiring live network access. Runtime case enrichment is explicit-mode only: default workups use the prompt plus public evidence-pack metadata, while synthetic demo data requires --data-mode synthetic_only or --data-mode hybrid_synthetic_public and every generated field carries provenance. Hyphenated data-mode aliases such as --data-mode public-evidence are accepted for CLI ergonomics. Live evidence refresh/search and private case ingestion are future maintenance paths, not default runtime dependencies.

Evidence packs and citation cards

Evidence packs are committed, offline-first source-control artifacts. They do not store payer portal exports, private contract text, downloaded policy payloads, PHI, screenshots, or live-search results. They tell the agent which source families, local lookup paths, required fields, owners, and red flags matter for a workflow.

Citation-card statuses are intentionally conservative:

This is deliberate. The catalog is designed for Azure, Codex Cloud, locked-down enterprise workstations, and other secure environments that cannot rely on live external fetching. Live evidence refresh/search, payer portal connectors, private case ingestion, and MCP adapters are future integration paths, not default runtime dependencies.

Case data modes and provenance

Runtime case enrichment is explicit-mode only. Default workups use the prompt and public workflow metadata. Fixture or evidence metadata appears only when the user requests a data mode.

Hyphenated aliases are accepted for CLI ergonomics, so --data-mode public-evidence and --data-mode hybrid-synthetic-public normalize to the underscore forms.

Every generated fixture field carries provenance:

Prompt-derived facts such as payer, product, CARC/RARC code, interface type, dashboard domain, or review scope must not be labeled as purely synthetic.

Phase 2 expands the same Operator OS pattern across the workflow catalog. Use healthcare-agents operator-os coverage to see exemplar and standard-pack status for all 16 workflows, and see Operator OS Catalog Coverage plus Evidence Pack Authoring for coverage rules, provenance labels, citation-card status meanings, and secure-environment boundaries.

Start with the workflow gallery, example workup packets, and platform compatibility guides.

Current Release

Version 1.6.0 is the GPT-5.6 runtime and workflow-reliability release. It adds compact workflow-first routing indexes, cross-platform state-ledger and terminal-completion controls, Sol/Terra/Luna eval guidance, and synthetic HealthAdminBench-derived reliability canaries. See the v1.6.0 release notes for the research basis, validation evidence, and scope limits.

Install

Codex plugin install:

git clone https://github.com/ajhcs/healthcare-agents.git
cd healthcare-agents
bash scripts/install-codex-plugin.sh

For local development from this checkout:

bash scripts/install-codex-plugin.sh

The script creates a local Codex marketplace wrapper at ~/.healthcare-agents-codex-marketplace, symlinks it to this repo-root plugin, runs codex plugin marketplace add, and installs healthcare-agents@healthcare-agents-local. Start a new Codex thread after installing or updating the plugin so the self-directing router is loaded.

Use natural phrasing:

Use the Healthcare Agents plugin for a prior authorization appeal.
Use Healthcare Agents in the revenue cycle area for a denial spike.
Use the quality department for a survey readiness checklist.

Fast path:

npx --yes healthcare-agents install

GitHub-backed fallback:

npx --yes github:ajhcs/healthcare-agents install

Shell installer fallback:

curl -fsSL https://raw.githubusercontent.com/ajhcs/healthcare-agents/main/install.sh | bash

Target a specific tool:

Preview before writing files:

npx --yes healthcare-agents install --all --dry-run

Inspect local install targets and collisions:

npx --yes healthcare-agents doctor

Install one agent instead of the full pack:

npx --yes healthcare-agents install revenue-cycle-specialist --codex

Update existing installs:

npx --yes healthcare-agents install --all --force

Uninstall:

npx --yes healthcare-agents uninstall --all

Choose the Right Agent

Start with the task, not the agent name. Use the agent selection guide when you know the operational problem, the starter prompts when you want copy-ready examples, and the handoff map when the request spans departments.

The CLI exposes the same discovery surface:

healthcare-agents list --domain revenue
healthcare-agents show revenue-cycle-specialist
healthcare-agents choose "clean claim rate dropped after an EHR update"
healthcare-agents prompt quality-compliance-officer --mode audit/checklist

Every agent now supports four output modes:

Common starting points:

Quick Examples

Claude Code:

Use the revenue-cycle-specialist agent in quick triage mode to diagnose why our clean claim rate dropped, then list coding, contract, and prior authorization handoffs.

Codex:

Read the quality-compliance-officer healthcare agent and use audit/checklist mode to draft a HIPAA Security Rule evidence checklist for a small clinic.

OpenCode:

Use the revenue-contract-analyst skill to model payer contract underpayment risk from a sample allowed-amount table.

Rules-based tools:

Using the healthit-interoperability-engineer instructions, review this HL7v2 interface mapping for common ADT and ORU risks.

Manual project install:

git clone https://github.com/ajhcs/healthcare-agents.git
mkdir -p .claude/agents
cp healthcare-agents/agents/*.md .claude/agents/

Why Use This

Supported Tools

flowchart LR
  A["agents/*.mdsource prompts"] --> B["Claude Code~/.claude/agents"]
  A --> C["Codex~/.codex/agents + AGENTS.md"]
  A --> D["Rules foldersCursor · Windsurf · Copilot"]
  A --> E["Generated SKILL.md"]
  A --> I["Codex pluginrouter skill + source prompts"]
  E --> F["Claude SkillsDesktop · Cowork"]
  E --> G["OpenCode Skills"]
  E --> H["Open Agent Skills.agents/skills"]

Agent Catalog

Eval Status

The tracked eval evidence currently covers 51/51 evaluated agents. Those 51/51 tracked improved agents have an average latest score of 94.18 in eval/results.tsv and docs/eval/scorecard.json.

The remaining eval backlog is now closed: every registry agent has role baselines, prompt coverage, and a latest scored row in eval/results.tsv. The repository treats these rows as internal prompt-rubric evidence only, with public claims generated from docs/eval/scorecard.json.

These are internal prompt-rubric results only, not certification, accreditation, legal review, coding validation, billing approval, clinical validation, compliance approval, or proof of PHI readiness.

The eval kit is intentionally simple and auditable:

Same-question before/after comparisons must preserve full Q001-Q025 artifacts before answers are generated. This keeps score deltas tied to the exact same exam rather than paraphrased weak areas.

The GPT-5.6 runtime path routes from compact generated indexes, then loads one selected specialist prompt. Shared platform instructions require a compact long-horizon state ledger and an evidence-backed Completed, Partial, or Blocked terminal status. This reduces irrelevant starting context and targets the state-loss, document-transition, and subtask-versus-full-task failures reported by HealthAdminBench; it does not claim external benchmark improvement until the actual GUI benchmark is run.

Self-Improvement Kit

Install the eval loop into another project that already has agents/*.md:

git clone https://github.com/ajhcs/healthcare-agents.git
bash healthcare-agents/scripts/install-self-improvement-kit.sh /path/to/project

Run in Claude Code:

/eval revenue-medical-coding-specialist

Run in Codex:

Run the healthcare self-improvement loop for revenue-medical-coding-specialist.

During a normal eval run, only the requested agents/.md file should change, eval/results.tsv should only receive appended rows, and local artifacts should stay under ignored eval/run-logs/ paths.

Repository Layout

.
├── agents/                         # 51 source agent prompts
├── .claude/commands/eval.md         # canonical self-improvement workflow
├── eval/
│   ├── rubric.md                    # frozen scoring rubric
│   ├── results.tsv                  # append-only eval log
│   ├── role-baselines/              # expected capability baselines
│   └── run-logs/                    # local ignored exact-question artifacts
├── docs/eval/                       # scorecard, routing benchmark, canary suite, scorer guidance
├── docs/operator-os/                # catalog coverage and evidence-pack authoring docs
├── docs/usage/                      # agent chooser, starter prompts, handoff map
├── workflows/                       # workflow registry, Operator OS coverage, evidence packs
│   └── evidence-packs/              # offline-first evidence-pack JSON files
├── lib/operator-os/                 # data modes, provenance, fixtures, golden artifacts
├── bin/cli.js                       # GitHub-backed npx entrypoint
├── install.sh                       # multi-tool installer
└── scripts/                         # release, validation, scaffold, and self-improvement helpers

Validation

Validate agent prompt structure:

bash scripts/lint-agents.sh

Run the full local release gate used by CI:

npm run release:check

Run the Operator OS validators directly:

npm run validate:evidence-packs
npm run validate:operator-os-coverage
npm run test:evidence-packs
npm run test:case-data-provider
npm run test:operator-os-coverage

Validate the compact GPT-5.6 router inputs and HealthAdminBench-derived reliability canaries:

npm run validate:registry
npm run validate:health-admin-canaries

Dogfood the Operator OS catalog:

healthcare-agents operator-os coverage --json
healthcare-agents evidence-pack list --json
healthcare-agents evidence-pack show denial-spike-workup --json
healthcare-agents evidence-pack scaffold clean-claim-rate-decline
healthcare-agents workup "CARC 197 denials doubled for imaging authorizations" --target codex --data-mode public-evidence --json

Release maintainers should also run:

node scripts/verify-public-release.js
node scripts/validate-public-version-sync.js
npm pack --json --dry-run
npm publish --dry-run --access public

Preview installer behavior:

bash install.sh --all --dry-run

Check CLI help:

npx --yes healthcare-agents --help

Limitations

• The agents provide healthcare administration support, not final clinical, legal, coding, billing, audit, or compliance determinations.
• Operator OS evidence packs are source-family and local-governance controls. Most public cards are not verified pinpoint citations.
• Standard-pack workflows have evidence metadata and validation, but Denial Spike is the only exemplar with full golden-artifact scoring in v1.5.0.
• Live public search, scheduled evidence refresh, payer portal connectors, private payer contract ingestion, PHI-bearing upload parsing, and MCP adapters are not part of the default runtime.
• Regulations, code sets, payer policies, accreditation standards, and program manuals change. Verify against current primary sources before operational use.
• The prompts do not make an AI tool HIPAA-compliant and do not create a safe PHI-processing environment. Use approved privacy, security, de-identification, and vendor-review workflows.
• Tool support differs by runtime. The installer uses best-known current file layouts and keeps plain Markdown as the fallback.
• The eval scores measure performance against this repository’s rubric and role baselines; they are not external certification.

Troubleshooting

FAQ

Are these Claude Code agents or skills?

Both. The source files in agents/*.md install as Claude Code subagents. The installer can also generate one SKILL.md folder per agent for Claude Skills, Claude Desktop/Cowork where skills are available, OpenCode, and the open .agents/skills convention.

Do these work in Codex?

Yes. The recommended Codex path is the plugin install, which loads one self-directing Healthcare Agents router and keeps the 51 source prompts as external reference. Use it for prompts like “Use the Healthcare Agents plugin for a prior authorization appeal,” “Use Healthcare Agents in the revenue cycle area for a denial spike,” or “Use the quality department for a survey readiness checklist.”

The older installer path still works: npx --yes healthcare-agents install --codex copies prompts to ~/.codex/agents and writes a managed ~/.codex/AGENTS.md block. Use that when you want prompt files copied into your Codex home instead of installing the repo as a plugin.

Why did the frontmatter names change?

Claude Code and OpenCode expect lowercase hyphen identifiers. v1.1.1 and newer keep human labels in display_name while making name match the filename slug.

Can I use these for HIPAA, coding, payer, or compliance work?

Use them for structured analysis, checklists, source-aware workflows, and draft deliverables. Do not treat them as final legal, clinical, coding, billing, audit, or compliance determinations.

Can I use these with PHI?

Only inside an environment your organization has approved for PHI, with the right vendor agreements, access controls, retention settings, and de-identification practices. The prompts themselves do not solve that governance problem.

Does Operator OS fetch external evidence?

No. Normal workup generation, evidence-pack display, scaffold generation, tests, package validation, and release readiness do not fetch live external resources. Evidence packs contain offline metadata and lookup paths so teams can bring their own current local sources.

What is the difference between exemplar and standard pack?

An exemplar has the full Operator OS treatment: evidence pack, citation cards, fixture/provenance support, artifact scoring, docs, and domain review. A standard pack has evidence-pack metadata, citation cards, docs, and validation, but not full golden-artifact scoring yet. In v1.5.0, denial-spike-workup is the exemplar and the other 15 workflows are standard packs.

How do I publish the npm package after a release PR merges?

Publishing is maintainer-controlled. Use the release publishing runbook. The short local path is:

npm login --auth-type=legacy
npm whoami
npm run release:check
npm publish --dry-run --access public
npm publish --access public --otp=
node scripts/validate-public-version-sync.js --network
node scripts/verify-public-release.js --network

Can I add my own agents?

Yes. Follow the conventions in CONTRIBUTING.md, run bash scripts/lint-agents.sh, and keep the agent narrow, source-aware, and operationally concrete.

License

Apache 2.0. See LICENSE.