Clinical Doc Assistant

Use this skill when a clinician, practice manager, or healthcare developer needs to draft, structure, or retrieve clinical documentation — including SOAP not...

Security Scan

The skill's declared purpose (FHIR-based clinical document drafting) matches the implementation, but there are important inconsistencies and privacy risks (metadata mismatch about required env vars and an option that forwards patient_context to a third‑party LLM) that the user should understand before installing or using with real PHI.

Purpose & Capability

The SKILL.md and backend.py both implement a FHIR R4 document-generation assistant and require SMART-on-FHIR credentials (client id/secret, token URL) and/or a FHIR sandbox mode. This is coherent for the stated purpose. However, the top-level registry metadata reported to the scanner shows "Required env vars: none" while SKILL.md explicitly lists multiple requiredEnv variables (FHIR_CLIENT_ID, FHIR_CLIENT_SECRET, FHIR_TOKEN_URL, FHIR_BASE_URL). That metadata mismatch is an inconsistency that should be resolved before trusting the skill's manifest.

Instruction Scope

SKILL.md instructs the agent to fetch patient FHIR resources into the agent session and not to write PHI to disk — that is consistent with a drafting tool. But the package also includes backend.py which, when used, expects the agent to POST the structured patient_context to a hosted backend which then forwards the patient_context (embedded in an LLM prompt) to Anthropic's API. SKILL.md does warn about not sending PHI to third parties without a BAA, but the runtime instructions permit transmitting patient data to remote LLMs; this is a privacy/exfiltration risk if the hosted backend or Anthropic are used without appropriate legal/technical protections.

Install Mechanism

There is no install spec — the skill is instruction-first and includes optional source for a self-hostable backend. No downloads or obscure install URLs are present. This is low install-mechanism risk.

Credentials

The environment variables required by SKILL.md (FHIR client id/secret/token URL, and optional ANTHROPIC_API_KEY or CLINICAL_DOC_API_* for the hosted backend) are proportionate to connecting to an EHR and an LLM backend, but they are highly sensitive. The skill requests OAuth client secrets (which grant access to patient data) and may require an Anthropic API key for LLM calls. Those credentials are appropriate only if you intend to connect to an EHR or to self-host the backend; they are excessive and dangerous if provided to an unknown third‑party hosted backend. The manifest/registry metadata omission of these env vars increases risk because an installer might not realize what secrets are needed or transmitted.

Persistence & Privilege

The skill does not request 'always: true' nor modify other skills or system-wide settings. No persistent or elevated platform privileges are requested by the package itself.

What to consider before installing

What to consider before installing or using this skill: - Metadata mismatch: The registry metadata for this package said "no required env vars" while SKILL.md requires FHIR OAuth credentials (client id/secret/token URL). Treat that as a red flag — confirm the manifest before supplying secrets. - PHI risk: If you use the hosted backend or supply CLINICAL_DOC_API_URL to a third party, the skill will transmit the full patient_context to that backend and then to Anthropic's API. Do NOT send real PHI to any third-party backend unless you (a) control the backend, (b) deploy it in a HIPAA-eligible environment, and (c) have appropriate BAAs in place. - Safer options: For testing, set FHIR_SANDBOX_MODE=true and use only synthetic data. If you need production use, self-host backend.py on infrastructure you control, keep ANTHROPIC_API_KEY in a secure store, and ensure logging does not capture PHI. Consider anonymizing or redacting identifiers before sending to an LLM. - Audit the backend: If you will use a hosted instance, review backend.py (it’s included) and confirm it does not persist PHI to logs or DBs, and verify what the hosted operator does with received data. The included backend currently has no DB integration implemented (placeholders), and uses an HTTP POST to api.anthropic.com — that behaviour is expected but sensitive. - Least privilege: Only provide FHIR credentials with scopes limited to minimum read access needed, rotate keys regularly, and restrict network access to trusted endpoints. - If you are unsure: do not provide EHR credentials or real patient data. Use sandbox mode for evaluation and request clarification from the skill author about the manifest/registry mismatch and about where patient_context will be sent in hosted mode.

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.

export FHIR_SANDBOX_MODE=true

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

export FHIR_BASE_URL="https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4"
export FHIR_CLIENT_ID="your-client-id"
export FHIR_CLIENT_SECRET="your-client-secret"
export FHIR_TOKEN_URL="https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token"

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

"Find patient [name] born [DOB]"
"Look up patient MRN 1234567"
"Search for patients with last name Rodriguez"

Internally calls:

GET /Patient?name=Rodriguez&birthdate=1975-04-12
GET /Patient/[id]

Condition list

"What are the active conditions for this patient?"

Calls:

GET /Condition?patient=[id]&clinical-status=active

Medication list

"Pull current medications for patient [id]"

Calls:

GET /MedicationRequest?patient=[id]&status=active

Recent vitals

"Get the last set of vitals for this patient"

Calls:

GET /Observation?patient=[id]&category=vital-signs&_sort=-date&_count=10

Lab results

"Pull recent labs — focus on HbA1c and BMP"

Calls:

GET /Observation?patient=[id]&category=laboratory&_sort=-date&_count=20

Encounter history

"Show encounters from the last 6 months"

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. 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:

SUBJECTIVE:
Patient is a 58-year-old male presenting for routine diabetes follow-up.
Reports improved energy since medication adjustment. No hypoglycemic episodes.
Denies chest pain, shortness of breath, or lower extremity edema.

OBJECTIVE:
Vitals (2026-03-15): BP 132/78, HR 72, Wt 198 lbs, BMI 29.4
HbA1c (2026-02-10): 7.2% (↓ from 7.9% in November)
Current Meds: Metformin 1000mg BID, Lisinopril 10mg daily

ASSESSMENT:
1. Type 2 Diabetes Mellitus — improving, at goal
2. Hypertension — controlled

PLAN:
1. Continue current regimen
2. Repeat HbA1c in 3 months
3. Annual ophthalmology referral ordered
4. Follow up in 3 months or sooner if concerns

---

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. 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:

[Date]

Re: [Patient Name], DOB [Date], MRN [Number]

Dear Dr. [Specialist],

I am referring the above-named patient for cardiology evaluation.
[Patient] is a 64-year-old female with a history of hypertension and
hyperlipidemia presenting with exertional dyspnea over the past 6 weeks.
Recent ECG showed non-specific ST changes. Echo has not been performed.

Current medications: Amlodipine 5mg, Atorvastatin 40mg, ASA 81mg.

I would appreciate your evaluation and recommendations.

Sincerely,
[Referring Provider]

---

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. 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. 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. 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:

export CLINICAL_DOC_API_URL="https://api.yourdomain.com/v1"
export CLINICAL_DOC_API_KEY="your-api-key"

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: patient/Patient.read patient/Condition.read patient/MedicationRequest.read patient/Observation.read patient/Encounter.read

Sandbox mode not working

• Public HAPI sandbox: https://hapi.fhir.org/baseR4
• Confirm FHIR_SANDBOX_MODE=true is set and FHIR_BASE_URL is unset or points to the sandbox.

---

Example Workflows

Full outpatient visit workflow

User: "Pull patient Jane Doe, DOB 1968-03-22, from the FHIR server."
Agent: [Fetches Patient, Condition, MedicationRequest, Observation]
       "Found Jane Doe (MRN 7823991). Active conditions: HTN, T2DM, CKD stage 2.
        Current meds: Lisinopril, Metformin, Amlodipine. Last vitals: 3 weeks ago."

User: "She's here for a diabetes follow-up. Chief complaint: fatigue, better than last visit.
       Draft a SOAP note."
Agent: [Generates full SOAP note with populated O section from FHIR data]
       "Here is the draft SOAP note. Vitals from today's visit are missing —
        please add them before signing."

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 ANTHROPIC_API_KEY comment; clarified patient_context 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 ANTHROPIC_API_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.