name: hl7-healthcare
description: >
Generate, validate, parse, and transmit HL7 v2 messages for healthcare interoperability workflows.
Use this skill whenever the user needs to work with HL7 messages of any type — including ADT^A04
(patient/donor registration), ORM^O01 (lab orders), ORU^R01 (results), and ACK (acknowledgments).
Also trigger for MLLP transport, SoftBank/Epic/Beaker integration, anonymous donor workflows,
ISBT-128 product registration, or any task involving healthcare system messaging, HL7 segment
construction, field mapping, or clinical interoperability. Even if the user just says "build an
HL7 message" or "send a result to Epic", use this skill.

HL7 Healthcare Interoperability Skill

Generates, validates, parses, and transmits HL7 v2.x messages. Designed for clinical lab,
stem cell, and hospital integration workflows — including anonymous donor handling (FACT/JACIE, FDA 21 CFR Part 1271).

Supported Message Types

Quick Start

1. Generate a message

# ADT^A04 — anonymous donor registration
python scripts/generate_adt_a04.py \
  --din "W000055508D001" \
  --donor-id "DONOR-2026-0042" \
  --sending-app "VERITAS" \
  --sending-facility "LSU_SCL" \
  --receiving-app "SOFTBANK" \
  --receiving-facility "LSU"

# ORM^O01 — lab order panel
python scripts/generate_orm_o01.py \
  --donor-id "DONOR-2026-0042" \
  --din "W000055508D001" \
  --product-type "PBSC" \
  --output orders.hl7

# ORU^R01 — results routing to Epic
python scripts/generate_oru_r01.py \
  --donor-id "DONOR-2026-0042" \
  --recipient-mrn "MRN123456" \
  --din "W000055508D001" \
  --results results.json \
  --output oru_result.hl7

2. Validate a message

python scripts/validate_hl7.py --file message.hl7
python scripts/validate_hl7.py --stdin < message.hl7

3. Parse / inspect a message

python scripts/parse_hl7.py --file message.hl7 --segment PID
python scripts/parse_hl7.py --file message.hl7 --all

4. Send via MLLP

python scripts/mllp_sender.py \
  --host softbank.lsu.edu \
  --port 2575 \
  --file message.hl7 \
  --timeout 10

Anonymous Donor Rules (LSU / FDA 21 CFR Part 1271)

When registering an anonymous HSC donor, strictly follow these field rules:

The recipient's MRN must never appear in any ADT or ORM segment. It lives only in the
encrypted linking table, hashed as SHA-256 in audit events.

LOINC Codes — HSC Standard Panel

For bone marrow (BM) and cord blood (CB) product types, read references/product_panels.md
for the product-specific order sets.

HL7 Segment Reference

For full field-by-field documentation of each message type:
- ADT^A04 → references/adt_a04.md
- ORM^O01 → references/orm_o01.md
- ORU^R01 → references/oru_r01.md

MLLP Framing

HL7 v2 over TCP uses MLLP (Minimal Lower Layer Protocol) framing:

<VT> [HL7 message bytes] <FS><CR>

• <VT> = 0x0B — Start Block character
• <FS> = 0x1C — End Data character
• <CR> = 0x0D — Carriage Return

The mllp_sender.py script handles framing automatically. For raw integration, see references/mllp_protocol.md.

Validation Rules

validate_hl7.py checks:
1. MSH segment present and correctly delimited (|^~\&)
2. Message type in supported set
3. Required segments present for message type
4. PID-3 (Patient ID) non-empty
5. Timestamp format valid (YYYYMMDDHHMMSS)
6. For ADT^A04 anonymous donor: PID-5 must be ANONYMOUS^DONOR, PID-7 must be 00010101
7. No MRN-like identifiers in ORM/ADT segments (anonymous donor safety check)
8. ACK code parsing (AA=accepted, AE=error, AR=rejected)

Error Handling

All scripts exit with:
- 0 — success
- 1 — validation error (message printed to stderr)
- 2 — network/MLLP error
- 3 — parse error

Scripts log to stdout in structured JSON when --json flag is passed, useful for agent integration.

File Layout

hl7-healthcare/
├── SKILL.md                    ← You are here
├── scripts/
│   ├── generate_adt_a04.py     ← Build ADT^A04 messages
│   ├── generate_orm_o01.py     ← Build ORM^O01 lab order panels
│   ├── generate_oru_r01.py     ← Build ORU^R01 result messages
│   ├── validate_hl7.py         ← Validate any HL7 v2 message
│   ├── parse_hl7.py            ← Parse and inspect HL7 messages
│   └── mllp_sender.py          ← Transmit via MLLP over TCP
├── references/
│   ├── adt_a04.md              ← ADT^A04 field reference
│   ├── orm_o01.md              ← ORM^O01 field reference
│   ├── oru_r01.md              ← ORU^R01 field reference
│   ├── product_panels.md       ← HSC product-type order sets
│   └── mllp_protocol.md        ← MLLP framing specification
└── examples/
    ├── anonymous_donor_registration.hl7
    ├── lab_order_panel_pbsc.hl7
    └── results_routing_to_epic.hl7