Clinical Documentation Assistant

Overview

This skill enables an OpenClaw agent to connect to any FHIR R4-compliant EHR, retrieve structured patient data, and generate high-quality clinical documentation drafts. It covers the most time-consuming document types in outpatient and inpatient settings.

Supported document types:

• - SOAP notes (Subjective / Objective / Assessment / Plan)
• Referral letters (specialist, imaging, therapy)
• Prior authorization requests (insurance)
• Discharge summaries
• Care plan narratives
• Patient-facing after-visit summaries

Supported FHIR backends:

• - Epic (SMART on FHIR)
• Cerner (Millennium)
• Azure Health Data Services
• HAPI FHIR (public sandbox for testing)
• Any R4-compliant server

⚠️ Clinical Disclaimer: All output is a documentation draft intended to be reviewed, edited, and signed by a licensed clinician. This skill does not provide clinical advice, diagnoses, or prescriptions.

🔒 Privacy / PHI Warning: FHIR data is fetched into the agent's context for the session only and is not written to disk by this skill. If you use the hosted backend (CLINICAL_DOC_API_URL), patient context is transmitted to that server — only use a backend you control in a HIPAA-eligible environment. Do not use a third-party hosted backend with real patient data unless a BAA is in place. For development and testing, always use FHIR_SANDBOX_MODE=true with synthetic data only.

---

Quick Start (Sandbox Mode — No EHR Needed)

Set FHIR_SANDBOX_MODE=true to use the public HAPI R4 sandbox. No credentials required. Ideal for testing and development.

CODEBLOCK0

Then ask your agent:

"Pull patient John Smith from the FHIR sandbox and draft a SOAP note for today's hypertension follow-up."

---

Authentication

This skill uses SMART on FHIR (OAuth2) for EHR connections. Set up once per environment.

Step 1 — Register your app with your EHR

Each EHR has its own developer portal:

• - Epic: https://fhir.epic.com → create a non-production app → note Client ID
• Cerner: https://code.cerner.com → register app → note Client ID + Secret
• Azure AHDS: Azure Portal → FHIR service → Authentication

Step 2 — Set environment variables

CODEBLOCK1

Step 3 — Test the connection

Ask the agent:

"Check my FHIR connection status."

The agent will attempt a token fetch and a GET /metadata call, then report back.

---

FHIR Data Retrieval

The agent fetches only the resources needed for the requested document. All calls are read-only GET requests.

Patient lookup

CODEBLOCK2

Internally calls:
CODEBLOCK3

Condition list

CODEBLOCK4

Calls:
CODEBLOCK5

Medication list

CODEBLOCK6

Calls:
CODEBLOCK7

Recent vitals

CODEBLOCK8

Calls:
CODEBLOCK9

Lab results

CODEBLOCK10

Calls:
CODEBLOCK11

Encounter history

CODEBLOCK12

Calls:

GET /Encounter?patient=[id]&date=ge2025-09-01&_sort=-date

---

Document Generation

Once patient data is retrieved, ask the agent to generate any document type.

SOAP Note

Trigger phrases:

• - "Draft a SOAP note for today's visit"
• "Write a SOAP note for this patient's diabetes follow-up"
• "Generate a clinical note — chief complaint is chest pain"

What the agent does:

1. 1. Retrieves active conditions, current meds, recent vitals, and relevant labs
2. Asks you for any additional subjective information (chief complaint, HPI)
3. Structures the note into S / O / A / P sections
4. Flags any data gaps (missing vitals, no recent labs)

Example output structure:

CODEBLOCK14

---

Referral Letter

Trigger phrases:

• - "Write a referral to cardiology for this patient"
• "Draft a referral letter to Dr. Chen for physical therapy"
• "Generate an imaging referral for MRI of the lumbar spine"

What the agent does:

1. 1. Pulls relevant conditions, meds, and recent encounter notes
2. Asks for referring provider name, specialty, and clinical question
3. Formats a professional referral letter with clinical context

Example:

CODEBLOCK15

---

Prior Authorization Request

Trigger phrases:

• - "Draft a prior auth for [medication/procedure]"
• "Generate a prior authorization for Humira for this patient"
• "Write a PA request for MRI lumbar spine — payer is BlueCross"

What the agent does:

1. 1. Retrieves diagnosis codes (ICD-10) from active conditions
2. Looks up the requested item's typical HCPCS/CPT code
3. Generates a structured PA narrative with clinical justification
4. Lists supporting labs or imaging that strengthen the case

Key fields generated:

• - Member ID (from input)
• Requesting provider NPI (from input)
• Diagnosis codes (from FHIR Condition resources)
• Requested service + procedure/drug code
• Clinical justification narrative
• Supporting documentation checklist

---

Discharge Summary

Trigger phrases:

• - "Generate a discharge summary for this patient"
• "Draft a hospital discharge note — patient is going home today"

What the agent does:

1. 1. Pulls the current/recent encounter, active conditions, procedures, and meds
2. Asks for admission diagnosis, hospital course summary, and discharge instructions
3. Formats a complete discharge summary with follow-up plan

---

After-Visit Summary (Patient-Facing)

Trigger phrases:

• - "Write a patient-friendly after-visit summary"
• "Generate an AVS in plain language for this patient"

What the agent does:

1. 1. Translates clinical note content into plain English (8th-grade reading level)
2. Lists medications with plain-language instructions
3. Includes follow-up appointments and warning signs to watch for

---

Manual Mode (No FHIR Connection)

If no EHR is connected, the agent will prompt you to provide patient data manually. Useful for small practices, telehealth, or demos.

Ask: "Draft a SOAP note — I'll provide the patient data manually."

The agent will ask for:

• - Chief complaint and HPI
• Vitals
• Active conditions and medications
• Assessment and plan outline

---

Hosted Backend (Credit-Based Generation)

For high-volume use or team deployments, a managed API backend handles generation, audit logging, and HIPAA-aligned data handling.

Set these variables to enable:
CODEBLOCK16

When set, document generation routes through the hosted backend instead of the local LLM. Credits are deducted per document generated. Visit [your site] to purchase credits and manage your account.

Hosted backend advantages:

• - Audit log of every document draft (for compliance)
• No patient data stored — stateless processing
• Team accounts with per-provider usage tracking
• 99.9% uptime SLA

---

Data Privacy & HIPAA Considerations

• - Local mode: Patient data is fetched into the agent's context for the duration of the session only. No data is written to disk by this skill.
• Hosted mode: Requests are processed statelessly. No PHI is retained after response delivery. Review the hosted backend's BAA before use in production.
• Audit trail: Clinicians should save final signed documents in their EHR per their organization's policies. This skill generates drafts only.
• De-identification: For development and testing, use FHIR_SANDBOX_MODE=true with synthetic data only.

🔒 Before using with real patient data, ensure your deployment satisfies your organization's HIPAA security requirements and that a Business Associate Agreement (BAA) is in place with any third-party service.

---

Troubleshooting

"FHIR connection failed: 401 Unauthorized"

• - Token may have expired. The skill auto-refreshes tokens, but check that FHIR_CLIENT_SECRET is current.
• Confirm your app registration is approved and not in sandbox-only mode.

"Patient not found"

• - Try searching by MRN instead of name (name matching varies by EHR).
• Check that your app has Patient.read and Patient.search scopes granted.

"Missing vitals / labs in output"

• - The patient may not have recent observations in the EHR.
• The agent will flag missing data sections in the draft and prompt you to fill them in manually.

"SMART on FHIR scopes error"

• - Ensure your registered app includes these scopes:

INLINECODE8

Sandbox mode not working

• - Public HAPI sandbox: INLINECODE9
• Confirm FHIR_SANDBOX_MODE=true is set and FHIR_BASE_URL is unset or points to the sandbox.

---

Example Workflows

Full outpatient visit workflow

CODEBLOCK17

Quick prior auth

User: "Generate a prior auth for Ozempic for this patient — payer is Aetna."
Agent: [Pulls active conditions, labs (HbA1c), current meds]
       "Draft PA narrative ready. Diagnosis: T2DM (E11.9). Supporting:
        HbA1c 8.4% (2026-02-01), inadequate response to Metformin 2000mg.
        Do you want to add any additional clinical notes before I finalize?"

---

Version History

Version	Date	Changes
1.0.4	2026-03-29	Fixed misleading ANTHROPICAPIKEY comment; clarified patientcontext is forwarded to Anthropic when backend is used; added CORS production warning.
1.0.3

2026-03-29 | Fixed env var declarations (moved optional vars out of requiredEnv); added ANTHROPICAPI_KEY to optionalEnv with context; added PHI/privacy warning. | | 1.0.0 | 2026-03-29 | Initial release. SOAP, referral, prior auth, discharge, AVS. SMART on FHIR auth. Sandbox mode. |

---

Questions or issues? Open a GitHub issue or reach out via the OpenClaw Discord.