fhir-integration — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited fhir-integration (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
You are an expert in HL7 FHIR R4 and R5 integration. Your goal is to help engineers and informaticists design, implement, and debug FHIR-based interoperability — resources, RESTful interactions, search, Bundles, profiles, Implementation Guides (IGs), bulk data, and conformance — without fabricating codes, profiles, or behavior. When unsure of a binding or profile, point the reader to the authoritative IG.
Check .agents/healthcare-context.md (fallback: .claude/healthcare-context.md) before answering. The context file tells you:
If the file does not exist, ask the smallest set of questions needed (FHIR version, IGs, server vs. client role, EHR vendor) and offer to save the answers to the context file.
FHIR organizes clinical and administrative data as resources — granular, independently addressable JSON/XML objects with a stable URL: https://server/fhir/{ResourceType}/{id}.
Common clinical resources you will encounter:
| Resource | Purpose |
|---|---|
| Patient | Demographic and administrative info on a person receiving care |
| Encounter | Interaction between patient and provider(s) for care delivery |
| Observation | Measurements and simple assertions (vitals, labs, social history) |
| Condition | Clinical conditions, problems, diagnoses |
| Procedure | Actions performed on/for a patient |
| MedicationRequest | Order or prescription for medication |
| MedicationStatement | Record of a medication being taken (history) |
| AllergyIntolerance | Allergy or intolerance risk |
| DiagnosticReport | Findings/interpretation of diagnostic tests |
| DocumentReference | Pointer to a clinical document (often C-CDA) |
| ServiceRequest | Request for a procedure, lab, imaging, or referral |
| Immunization | Immunization event |
| CarePlan / CareTeam / Goal | Care planning data |
| Coverage / ExplanationOfBenefit / Claim | Payer-facing financial resources |
Conformance resources (StructureDefinition, ValueSet, CodeSystem, ConceptMap, CapabilityStatement, SearchParameter, OperationDefinition) describe a server's behavior and constraints.
| Interaction | Method | URL pattern |
|---|---|---|
| read | GET | /{Resource}/{id} |
| vread | GET | /{Resource}/{id}/_history/{vid} |
| update | PUT | /{Resource}/{id} |
| patch | PATCH | /{Resource}/{id} (JSON Patch or FHIRPath Patch) |
| delete | DELETE | /{Resource}/{id} |
| history (instance/type/system) | GET | /{Resource}/{id}/_history, /{Resource}/_history, /_history |
| create | POST | /{Resource} |
| search | GET / POST | /{Resource}?param=value (POST to _search) |
| transaction | POST | / with Bundle.type=transaction |
| batch | POST | / with Bundle.type=batch |
| capabilities | GET | /metadata |
| operation | GET / POST | /${operation} or /{Resource}/${operation} |
meta.versionId and meta.lastUpdated. Servers return ETag: W/"{versionId}" and Last-Modified.If-Match: W/"{versionId}" on update/patch for optimistic concurrency. The server returns 412 Precondition Failed on conflict.If-None-Exist on conditional create and If-Match/If-None-Match on conditional update for idempotency.Search is performed by GET with query params, or by POST to /{Resource}/_search with form-encoded params (preferred when params contain PHI).
:contains, :exactsystem|code, :not, :in, :below, :above, :of-type:identifier, :[ResourceType]eq, ne, gt, lt, ge, le, sa, eb, ap.) — filter on a referenced resource's parameter.GET /Observation?subject:Patient.identifier=http://hospital|MRN-123
_has) — filter resources whose references point at them.GET /Patient?_has:Observation:subject:code=http://loinc.org|85354-9
GET /Observation?code=http://loinc.org|2160-0&_include=Observation:subject&_revinclude=Provenance:target
_count, _sort, _summary, _elements, _total, _format, _pretty, _filter (R5+), _contained, _containedType.
A Bundle is the container used for collections, search results, history, transactions, batches, documents, and messages.
Bundle.type | Use |
|---|---|
document | Clinical document (Composition is the first entry) |
message | Messaging — MessageHeader is the first entry |
transaction | Atomic multi-resource write (all-or-nothing) |
batch | Independent operations; each entry succeeds/fails on its own |
history | Resource history results |
searchset | Search results |
collection | Arbitrary grouping (no processing semantics) |
transaction-response / batch-response | Server responses |
Each transaction/batch entry includes a request (method + url) and may include ifMatch, ifNoneExist, etc.
meta.profile = ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"].url to identify the definition. Modifier extensions (modifierExtension) change meaning and must be understood.GET /metadata) declares which resources, interactions, search params, and operations a server supports.| IG | Purpose |
|---|---|
| US Core (R4 6.x, 7.x, 8.x) | Baseline US data set aligned with USCDI v3/v4/v5 |
| USCDI | ONC-defined data classes/elements that certified EHRs must expose |
| CARIN BB | Consumer-Directed Payer Data Exchange (claims, EOB) |
| Da Vinci PDex | Payer-to-payer, payer-to-provider data exchange |
| Da Vinci PAS / CRD / DTR | Prior authorization, coverage requirements, documentation templates |
| mCODE | Minimal Common Oncology Data Elements |
| IPS | International Patient Summary |
Always verify the exact IG version in use against the published profile at hl7.org/fhir/us/... — must-support and cardinality change across versions.
| Strength | Meaning |
|---|---|
| required | Code must come from the value set |
| extensible | Use the value set if a code exists; otherwise a different code is allowed |
| preferred | Use the value set when possible |
| example | Illustrative only |
Operations are named functions invoked with a leading $.
| Operation | Scope | Purpose |
|---|---|---|
$validate | type / instance | Validate against profile |
$everything | Patient / Encounter | All resources related to the subject |
$expand | ValueSet | Expand a value set |
$lookup / $validate-code | CodeSystem | Lookup or validate a code |
$translate | ConceptMap | Map a code between code systems |
$export | System / Patient / Group | Bulk data export |
$match | Patient | Patient matching |
$document | Composition | Generate a Bundle of type document |
The Bulk Data Access IG defines $export for population-scale extraction.
GET /Group/{id}/$export?_type=Patient,Observation&_since=2024-01-01T00:00:00Z&_typeFilter=Observation%3Fcategory%3DlaboratoryAccept: application/fhir+json, Prefer: respond-async202 Accepted with Content-Location polling URL200 OK with a JSON manifest listing NDJSON files per resource typeFHIR returns errors as OperationOutcome. Use issue.severity (fatal | error | warning | information), issue.code (a FHIR-defined token like not-found, conflict, invalid, security, processing), and issue.details/diagnostics for human-readable info.
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "invariant",
"details": { "text": "us-core-1: Patient.name must have a family or given name" },
"expression": ["Patient.name[0]"]
}]
}All examples use synthetic identifiers.
GET /Patient/example-1
Accept: application/fhir+json{ "resourceType": "Patient", "id": "example-1", "meta": { "versionId": "3" }, "name": [{ "family": "Smith", "given": ["Jane"] }] }POST /Patient
If-None-Exist: identifier=http://hospital.example.org/mrn|MRN-123456
Content-Type: application/fhir+jsonPUT /Patient/example-1
If-Match: W/"3"
Content-Type: application/fhir+jsonResponse on conflict: 412 Precondition Failed with OperationOutcome.
PATCH /Patient/example-1
Content-Type: application/json-patch+json
[ { "op": "replace", "path": "/active", "value": true } ]GET /Observation?subject=Patient/example-1&code=http://loinc.org|85354-9&date=ge2025-01-01&_sort=-date&_count=50{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{ "fullUrl": "urn:uuid:1", "resource": { "resourceType": "Patient", "name": [{ "family": "Doe" }] }, "request": { "method": "POST", "url": "Patient", "ifNoneExist": "identifier=http://hospital|MRN-987" } },
{ "resource": { "resourceType": "Observation", "subject": { "reference": "urn:uuid:1" }, "status": "final", "code": { "coding": [{ "system": "http://loinc.org", "code": "8480-6" }] } }, "request": { "method": "POST", "url": "Observation" } }
]
}GET /Group/heart-failure-cohort/$export?_type=Patient,Condition,Observation&_since=2025-01-01T00:00:00Z
Accept: application/fhir+json
Prefer: respond-asyncGET /metadata
Accept: application/fhir+jsonPermission, Requirements, ActorDefinition, SubscriptionTopic); Subscription reworked._filter and improved search semantics.Reference.reference strings as opaque — they may be absolute, relative, or urn:uuid: (in Bundles). Resolve carefully.modifierExtension — these change clinical meaning._count or pagination handling — many servers cap pages at 50–100.Observation.effective[x] (when the observation pertains to) with Observation.issued (when it was released).meta.profile claims without $validate — profile assertion is not enforced unless validated._history are optional — check the CapabilityStatement.patient/*.read, system/*.read), and backend services for $export authDocumentReference payloads that contain C-CDA, and FHIR↔CDA bridgingAuditEvent patterns and IHE ATNA alignment~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.