Healthcare Data Domain

When This Skill Applies

Activate when the data product involves: electronic health records (EHR), claims/billing data, clinical terminology, patient-level data, OMOP CDM, FHIR/HL7, or any data governed by HIPAA.

Do NOT activate for: general analytics, marketing data, financial data, or non-clinical datasets.

Core Standards

FHIR (Fast Healthcare Interoperability Resources) - Modern API standard for health data exchange. Resource-based (Patient, Observation, MedicationRequest, Condition, Encounter). Use for real-time integrations and patient-facing apps.

HL7 v2 - Legacy messaging standard still dominant in hospital systems. Pipe-delimited segments (MSH, PID, OBX). Expect to encounter this in any EHR integration project.

OMOP CDM (Common Data Model) - Research-optimized schema for observational health data. Core tables: PERSON, VISITOCCURRENCE, CONDITIONOCCURRENCE, DRUGEXPOSURE, MEASUREMENT, OBSERVATION, PROCEDUREOCCURRENCE. Use for analytics and real-world evidence studies.

Clinical Terminology Systems

| System | What It Codes | Example | |--------|--------------|---------| | ICD-10-CM | Diagnoses | F32.1 (Major depressive disorder, single episode, moderate) | | CPT | Procedures | 99213 (Office visit, established patient) | | SNOMED CT | Clinical concepts | 73211009 (Diabetes mellitus) | | LOINC | Lab tests/observations | 2345-7 (Glucose, serum/plasma) | | RxNorm | Medications | 197361 (Sertraline 50mg tablet) | | NDC | Drug packages | National Drug Code for specific manufacturer/package |

ALWAYS use standard terminology codes rather than free-text descriptions. Map to the appropriate code system for the use case.

OMOP Analytics Patterns

The 30-40 normalized OMOP tables are wrong for analytics dashboards. Transform to star schema with strategic denormalization:

• Fact tables: Drug exposures, visits, conditions (events become facts)
• Dimension tables: Patient, drug, diagnosis
• Pre-calculated cohort definitions for common queries
• NEVER fully denormalize (One Big Table). Healthcare's many-to-many relationships cause exponential row growth.

See domain-reference.md for detailed OMOP table relationships and FHIR resource mappings.

FHIR Gotchas

Common mistakes when working with FHIR resources:

| Gotcha | What Trips You Up | Fix | |--------|-------------------|-----| | Coding vs CodeableConcept | Coding is a single code. CodeableConcept wraps multiple codings with a display text. Most FHIR fields use CodeableConcept. | Always access .coding[0].code, not .code directly. | | Patient.identifier vs Patient.id | .id is the FHIR server's internal ID. .identifier holds MRNs, SSNs, and other business identifiers. | Query by .identifier.value with the correct .identifier.system. | | Observation.value[x] | Polymorphic field. Could be valueQuantity, valueString, valueCodeableConcept, or others. | Check the resource profile or test data to know which type your source sends. | | Bundle pagination | Search results return pages of 20-50 resources. The full result set requires following Bundle.link where relation = "next". | Always paginate. NEVER assume a single Bundle contains all results. |

FHIR-to-OMOP Mapping

When transforming FHIR resources into OMOP CDM:

| FHIR Resource | OMOP Table | Key Mapping Notes | |---------------|-----------|-------------------| | Patient | person | Map Patient.birthDate → year_of_birth. Gender codes differ between systems. | | Condition | conditionoccurrence | Condition.code → condition_concept_id via SNOMED-to-OMOP vocabulary mapping. | | Observation | measurement | Lab results map here. Use LOINC code from Observation.code for measurement_concept_id. | | MedicationRequest | drugexposure | Map RxNorm codes. MedicationRequest.dosageInstruction → dose_value/dose_unit. | | Encounter | visit_occurrence | Encounter.class → visit_concept_id. Map inpatient/outpatient/emergency. |

Common LOINC Codes for Vitals

| Vital Sign | LOINC Code | Units | |------------|-----------|-------| | Blood pressure, systolic | 8480-6 | mmHg | | Blood pressure, diastolic | 8462-4 | mmHg | | Heart rate | 8867-4 | /min | | Body temperature | 8310-5 | Cel | | Body weight | 29463-7 | kg | | Body height | 8302-2 | cm |

HIPAA Awareness

CRITICAL: Any data product handling patient data must consider the 18 HIPAA identifiers. See domain-reference.md for the full list. De-identification is required before data leaves a HIPAA-governed environment.

This skill provides general domain context, not compliance advice. Involve your privacy officer and legal team for HIPAA compliance decisions.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hollandkevint
• Source: hollandkevint/data-product-operator
• License: MIT
• Homepage: https://www.kevintholland.com/

Install and usage instructions live in the source repository linked above.