Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    hl7 fhir bridge

    1

    - **Profile validation** checks the output against US Core, CL Core (Chile) and CO Core (Colombia).

    Free

    3 usesSecurity scanned
    hl7 fhir bridge

    hl7 fhir bridge

    Example session with this skill installed

    I'm wiring Acme Lab's result feed into our patient-facing app, which consumes FHIR R4. Can you convert this ORU to FHIR and tell me if it's US Core-ready? I also need a short list of what to ask the lab to fix.

    MSH|^~\&|ACMELAB|ACME|PATAPP|CLINIC|20261014093000||ORU^R01^ORU_R01|ACME000417|P|2.5.1
    PID|1||MRN-88231^^^CLINIC^MR||RIVERA^ANA^M||19870412|
    OBR|1|ORD-5521^PATAPP|ACME-77310^ACMELAB|24357-6^URINALYSIS MACRO PANEL^LN|||20261014081500|||||||||||||||||F
    OBX|1|NM|2350-7^GLUCOSE UR^LN||100|mg/dL|<15|H|||F|||20261014084000
    OBX|2|CE|5778-6^COLOR OF URINE^LN||DKYEL^DARK YELLOW^99ACME||||||F|||20261014084000
    NTE|1|L|Specimen received 35 min after collection
    
    • Read your context and instructions
    • Compiled the hl7 fhir bridge

    Verdict: converted, but not US Core-ready. I validated against the us-core profile and got 1 error and 2 warnings. I also found two blocking problems the validator doesn't check: the DiagnosticReport has no status, and the timestamps have no time zone. Both are under "Not checked by the engine" below.

    This is a translation and validation aid, not a medical device. These results will reach patients, so have someone check the mapped output before go-live.

    Resources

    ResourceKey content
    Patientidentifier MRN-88231 (system CLINIC), name (family + first given), birthDate 1987-04-12, no gender
    Observation2350-7 GLUCOSE UR (LOINC), 100 mg/dL, reference range text <15, interpretation H (high), final, effective 2026-10-14T08:40:00
    Observation5778-6 COLOR OF URINE (LOINC), value DKYEL "DARK YELLOW" (no code system), final, effective 2026-10-14T08:40:00
    DiagnosticReport24357-6 URINALYSIS MACRO PANEL (LOINC), category LAB, links to both Observations and the Patient. No status, no effective/issued time, no identifier

    Observation.category = laboratory is a fixed value the ORU map always sets, because HL7 v2 has no field for it. It isn't a guess.

    Issues (from the engine)

    SeverityCodeLocationWhat it meansHow to fix
    errorPROFILE_REQUIREDPatient.genderUS Core Patient requires gender. PID-8 (the patient's administrative sex) is empty in the message.The lab populates PID-8. Don't fill the gap from the M in PID-5. That's the middle-name component (RIVERA^ANA^M), not sex.
    warningCODING_NO_SYSTEMObservation.valueCodeableConcept.coding[0]The urine-color answer DKYEL has no system URI. OBX-5.3 is 99ACME, a lab-local code system, so nothing downstream can tell what the code means.The lab adds a standard code (LOINC answer or SNOMED CT) in OBX-5.4–5.6 and/or gives us the canonical URI for 99ACME. We then register that URI in the ORU map. We don't guess it.
    warningUNMAPPED_SEGMENTNTEThe ORU map doesn't read NTE (comment) segments, so the note "Specimen received 35 min after collection" is not in the Bundle.Map side: NTE → Observation.note is still listed as pending in the ORU map. Until it's added, your app won't show this note.

    Not checked by the engine (my observations)

    I confirmed each of these by parsing the message or reading the Bundle. They're my own findings, separate from the deterministic list above.

    1. The DiagnosticReport has no status, which makes it invalid FHIR R4. The OBR segment has only 24 fields, so the F landed in OBR-24 (diagnostic service section) instead of OBR-25 (result status). The | before it is one short. status is mandatory (1..1) in base FHIR R4 and in US Core. I re-ran a synthetic message with F in OBR-25 and it mapped to status: final.

    Timestamps have no time zone. OBX-14 20261014084000 becomes 2026-10-14T08:40:00. FHIR R4 doesn't allow a dateTime with a time but no offset, so strict FHIR parsers will reject it. MSH-7 and OBR-7 have the same problem. I checked that an offset sent by the lab (e.g. …084000-0500) is kept in the output.
    3.

    The DiagnosticReport has no effective/issued time. OBR-7 (collection time) is in the message, but the ORU map doesn't map OBR-7 or OBR-22 yet (documented as pending). OBR-22 (report time) is also empty in the message. US Core's lab DiagnosticReport expects an effective time. This is a gap in the map, not a lab error.
    4.

    The order and report IDs aren't carried over. OBR-2 (placer ORD-5521) and OBR-3 (filler ACME-77310) don't reach DiagnosticReport.identifier or basedOn. Without them, a later corrected result can't be matched to this one, and your app would show duplicates. Map side.
    5.

    Patient.identifier.system is "CLINIC", not a URI. The map copies PID-3.4 (assigning authority) as-is. This is a known, deliberate TODO(mapeo) gap in the ORU map. It passes the engine's US Core rule because system and value are both present, but it isn't a resolvable namespace. This is your own MRN echoed back, so you decide the URI, not the lab.
    6.

    The NTE probably sits in the wrong place. It comes right after OBX 2, so under HL7 rules it's a note on the urine-color result. The text reads like a note about the whole specimen.
    7. Minor gaps:

    • The middle initial (PID-5.3) isn't mapped.
    • valueQuantity carries only the mg/dL text, with no UCUM system/code. It stays that way even if OBX-6 says ^^UCUM, which I checked. It's fine for display, but the map needs it if the app compares or converts units.

    The engine checks structure and must-support elements for Patient, Observation and codings. It doesn't check full IG conformance or terminology bindings. Before go-live, run the official HL7 FHIR Validator with US Core as a second pass.

    What to ask Acme Lab to fix

    1. Populate PID-8 (administrative sex). This clears the only US Core error.

    Put the result status in OBR-25. Add the missing | before F. Right now it lands in OBR-24 and the report has no status.
    3. Send timestamps with a UTC offset in MSH-7, OBR-7 and OBX-14, e.g. 20261014084000-0500.
    4.

    Code coded results with a standard system. Send a LOINC answer or SNOMED CT code in OBX-5.4–5.6 with coding system LN or SCT, and/or tell us the canonical URI of 99ACME.
    5. Two smaller items:

    • Populate OBR-22 (report time).
    • Check where the NTE belongs. If the note is about the whole specimen, they should send it right after OBR instead of after the urine-color OBX.

    Bundle (exactly as produced)

    {
      "resourceType": "Bundle",
      "type": "collection",
      "entry": [
        {
          "fullUrl": "urn:uuid:4d76e1a9-53d4-42ad-94e1-04d8cd13997e",
          "resource": {
            "resourceType": "Patient",
            "identifier": [
              {
                "value": "MRN-88231",
                "system": "CLINIC"
              }
            ],
            "name": [
              {
                "family": "RIVERA",
                "given": [
                  "ANA"
                ]
              }
            ],
            "birthDate": "1987-04-12"
          }
        },
        {
          "fullUrl": "urn:uuid:386051ae-c102-4c64-8ccc-da62ab40eca6",
          "resource": {
            "resourceType": "Observation",
            "category": [
              {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                    "code": "laboratory"
                  }
                ]
              }
            ],
            "status": "final",
            "code": {
              "coding": [
                {
                  "code": "2350-7",
                  "display": "GLUCOSE UR",
                  "system": "http://loinc.org"
                }
              ]
            },
            "valueQuantity": {
              "value": 100,
              "unit": "mg/dL"
            },
            "interpretation": [
              {
                "coding": [
                  {
                    "code": "H",
                    "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation"
                  }
                ]
              }
            ],
            "referenceRange": [
              {
                "text": "<15"
              }
            ],
            "effectiveDateTime": "2026-10-14T08:40:00",
            "subject": {
              "reference": "urn:uuid:4d76e1a9-53d4-42ad-94e1-04d8cd13997e"
            }
          }
        },
        {
          "fullUrl": "urn:uuid:f306779d-0e58-4e43-acd6-c051ed13b5c3",
          "resource": {
            "resourceType": "Observation",
            "category": [
              {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                    "code": "laboratory"
                  }
                ]
              }
            ],
            "status": "final",
            "code": {
              "coding": [
                {
                  "code": "5778-6",
                  "display": "COLOR OF URINE",
                  "system": "http://loinc.org"
                }
              ]
            },
            "valueCodeableConcept": {
              "coding": [
                {
                  "code": "DKYEL",
                  "display": "DARK YELLOW"
                }
              ]
            },
            "effectiveDateTime": "2026-10-14T08:40:00",
            "subject": {
              "reference": "urn:uuid:4d76e1a9-53d4-42ad-94e1-04d8cd13997e"
            }
          }
        },
        {
          "fullUrl": "urn:uuid:7e621ab3-2718-4b83-9759-7010e94d71dc",
          "resource": {
            "resourceType": "DiagnosticReport",
            "category": [
              {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/v2-0074",
                    "code": "LAB"
                  }
                ]
              }
            ],
            "code": {
              "coding": [
                {
                  "code": "24357-6",
                  "display": "URINALYSIS MACRO PANEL",
                  "system": "http://loinc.org"
                }
              ]
            },
            "result": [
              {
                "reference": "urn:uuid:386051ae-c102-4c64-8ccc-da62ab40eca6"
              },
              {
                "reference": "urn:uuid:f306779d-0e58-4e43-acd6-c051ed13b5c3"
              }
            ],
            "subject": {
              "reference": "urn:uuid:4d76e1a9-53d4-42ad-94e1-04d8cd13997e"
            }
          }
        }
      ]
    }
    

    Next steps

    1. Send the lab list above to Acme. Items 1–3 block US Core and valid R4. Item 4 removes the coding warning.
    2. Extend the ORU map on our side:
      • Map OBR-7 → DiagnosticReport.effectiveDateTime, OBR-22 → issued, and OBR-2/OBR-3 → identifier.
      • Map NTE → Observation.note.
      • Register the 99ACME URI once Acme provides it.
      • Decide the URI for the CLINIC MRN namespace.

    Re-test with a corrected sample. Re-run map --profile us-core on a corrected sample from Acme, then run the official HL7 FHIR Validator (US Core) as a second pass before go-live.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    This skill gives your agent a real translation engine instead of a guess. It ships a deterministic HL7 v2 → FHIR R4 engine (the open-source hl7-bridge-mcp core) and teaches the agent how to drive it and report back.

    What it does

    • Deterministic mapping converts ADT^A01, ORU^R01, ORM^O01 and OUL^R22 into FHIR R4 Bundles using declarative YAML maps you can read, diff and extend.
    • Profile validation checks the output against US Core, CL Core (Chile) and CO Core (Colombia). Built-in rules run offline. On request, the agent runs the official HL7 FHIR Validator against the latest published US Core or CL Core.
    • Exact error locations point to both the source field (PID-8) and the FHIR element (Patient.gender).
    • Message inspection lets you look at an unfamiliar HL7 v2 message field by field, without converting it.
    • Issue explanation turns validator output into plain-language causes and fixes, plus a fix list you can send to the lab or vendor.
    • No guessing: missing fields are reported, local codes are flagged, and unsupported message types are rejected with a structured error.

    How it works

    1. Choose the task: convert a message, validate an existing Bundle, or inspect a message's structure.
    2. Run the engine: the agent runs the bundled Node.js engine (hl7bridge.mjs) on your message. Nothing leaves your machine.
    3. Optional official validation: if you ask for "the official" or "the latest" check, the agent sends the Bundle to validator.fhir.org or to your own validator via --validator-url. It tells you before the first remote call, asks first if the data looks like real patient data, and never falls back silently to the built-in rules.
    4. Review the report: you get a verdict, a resource summary, an issues table with locations and fixes, and the Bundle as produced.

    Requirements

    Node.js 20+ and a shell the agent can run commands in. Official validation additionally needs outbound HTTPS to validator.fhir.org, or a self-hosted HL7 FHIR Validator.

    Why not just prompt for it

    The mapping lives in versioned YAML, not in a prompt. The same input produces the same output on every run, and you can audit why each field landed where it did. PHI stays local by default. The agent only reports what the engine produced and what the validator returned.

    Use cases

    • Convert a lab's ORU^R01 feed into FHIR R4 for a patient portal.
    • Check whether an HL7 v2 feed is US Core-ready before go-live.
    • Find out why an EHR or FHIR server rejects an ADT message or Bundle.
    • Pilot CL Core or CO Core profiles from existing HL7 v2 feeds.
    • Add a vendor-specific YAML map without rebuilding anything.

    Known limitations

    • Supports HL7 v2 → FHIR R4 only: no FHIR → HL7 v2 and no R5/R6.
    • Built-in validation is structural, not certification. It covers required and must-support elements, not terminology bindings or slicing. Use official validation for those.
    • Official validation covers US Core and CL Core only, needs network access, takes about 15 seconds or more per check, and results can change as new IG versions are published.
    • One order or specimen group per message.
    • Not a medical device. Outputs need human validation before clinical use.

    • FHIR R4 only, one direction. HL7 v2 → FHIR R4. No FHIR R5/R6, no FHIR → HL7 v2.
    • Four message types. ADT^A01, ORU^R01, ORM^O01, OUL^R22 (partial). Anything else is rejected with MAP_NOT_FOUND; the skill won't hand-map it.
    • One order/specimen group per message. An ORU with several OBR groups, or an OUL with several SPM, is rejected on purpose to avoid attaching results to the wrong order or specimen. Split such messages first.
    • Built-in validation is structural, not certification. Curated FHIRPath rules check required and must-support elements for US Core, CL Core v1.9.4 (Patient) and CO Core v0.1.0 (Patient). They don't check value-set bindings, slicing or terminology. For that, ask for official validation.
    • Official validation has its own limits:
      • It covers US Core and CL Core only. CO Core isn't published in the FHIR package registry, so the request is refused before anything is sent.
      • It needs network access and takes about 15 seconds or more per check.
      • It always uses the latest published IG, so results can change over time without a skill update.
      • Its findings come as the validator's own codes and messages.
      • The reported profile list only names profiles that produced findings, so a clean result shows an empty list.
    • Not every resource is profile-checked:
      • Built-in rules cover Patient, Observation and codings. DiagnosticReport, Encounter, ServiceRequest and Specimen pass through unchecked. For example, a DiagnosticReport whose OBR-25 is empty comes out without its required status, and the skill tells the agent to look for this.
      • Official validation checks every resource against base FHIR R4. For US Core it applies the matching profile to Patient, Encounter, lab Observation, lab DiagnosticReport, ServiceRequest and Specimen.
      • For CL Core it applies CorePacienteCl to Patient only. CL Core's other profiles, such as CoreObservacionCL, aren't applied.
    • Time zones are carried, not invented. HL7 timestamps without an offset become FHIR dateTimes without one. FHIR R4 doesn't allow that, and official validation flags it. The fix belongs at the sender.
    • National profiles are checked for core Patient elements only. For example, CL Core's coded-address extensions (comuna/región/país) aren't checked or produced, so a Chilean address still fails the official validator until those codes are supplied. The skill tells the agent to point this out.
    • CO Core is a development build (v0.1.0) of the Colombian IG and may change.
    • Identifiers and local codes stay as received. PID-3.4 is copied as a namespace (e.g. HOSP), not a canonical URI. Local codes (e.g. 99LAB) get no system URI and are flagged. National identifier typing (Chile RUN, Colombia document types) is a documented open item.
    • Partial field coverage. E.g. no NK1 (contacts), PV1-3/PV1-7 (bed, attending), NTE notes, or OBR-7/OBR-22 report times yet. Quantities carry the unit text without a UCUM code. Unconsumed segments are flagged as UNMAPPED_SEGMENT; unmapped fields inside a consumed segment are not.
    • Engine messages are in Spanish, and so are the official validator's (the request asks for Spanish). The agent translates them for you; codes and locations stay verbatim.
    • No de-identification. PHI is not masked. It's processed locally, and official validation sends the Bundle as-is to the validator you chose. The agent asks before sending anything that looks like real patient data. For real PHI, use your own validator instance.
    • Not a medical device. Outputs require human validation before any clinical use.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    3 uses

    Times used to date

    Free forever

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 21 days ago

    • Free with an Agensi account

    Requires

    Node.js 20+
    npm
    Terminal access

    Permissions

    Terminal / Shell
    Write Files
    Network Access

    **Network hosts** (for the declared-hosts field): - `validator.fhir.org`: official validation, only on request (`--validator remote`). Receives the FHIR Bundle. - `registry.npmjs.org`, or your organization's npm mirror: one-time `npm ci` setup. Receives package requests only, no message data. - A self-hosted HL7 FHIR Validator, only if you pass its URL with `--validator-url`.

    Listed1 month ago
    Updated21 days ago

    What's inside

    Frequently Asked Questions

    This skill utilizes a deterministic mapping engine with declarative YAML rules rather than relying on LLM inference for data transformation. This eliminates hallucinations, ensuring that every FHIR resource is traceable and strictly compliant with schema requirements.

    The bridge currently supports ADT^A01, ORU^R01, ORM^O01, and OUL^R22 message types. It is specifically designed to output FHIR R4 Bundles validated against US Core, CL Core, and CO Core profiles.

    This skill is built for Node.js 20+ environments and is designed to be integrated with AI agents that support local code execution or CLI-based tools. It functions as a specialized utility that your agent calls to process and validate healthcare data.

    The skill provides segment-level error reporting, pinpointing the exact location of a failure in the source HL7 segment and the corresponding FHIRPath. It also includes an 'Issue Explanation' feature to interpret complex validation logs into actionable fixes.

    You receive the core mapping engine (hl7bridge.mjs), the declarative YAML transformation maps, and the regional validation profiles. The package also includes documentation on how to execute the map, validate, and parse commands within your agent workflow.

    New in APIs & Backend