Agent skill

What it is

hl7-skill/ is a top-level directory in the workspace holding one file, SKILL.md, in the Agent Skills format: YAML frontmatter naming the skill and describing when to use it, followed by the instructions themselves.

hl7-skill/SKILL.md — frontmatter

---
name: hl7-skill
description: Explain Health Level Seven (HL7®) concepts, terminology,
  and ideas — what a segment, field, component, and repetition are; what
  MSH-9, ER7, the HL7 null, v2.xml, and Z-segments mean; how HL7 v2
  differs from v3 and FHIR® — with worked examples from the hl7-rust
  workspace. Use whenever the task is understanding an HL7 message or
  vocabulary, not only when this repo's code is involved: "what does
  MSH mean", "explain HL7 segments/fields", "what is ER7", "what's the
  difference between HL7 v2 and v3", "what is the HL7 null", an
  unfamiliar pipe-delimited (`MSH|^~\&|...`) message, or an HL7 v2/v3
  term used without explanation.
---

An agent that has this repository checked out, or that a user points at it, reads the description and decides for itself whether the current task — an unfamiliar HL7 message, a term like MSH-9 or “ER7”, a question about how v2 differs from v3 — is one this skill applies to. There is nothing to install and nothing to configure.

What is inside it

The skill is a condensed version of this site's Concepts page — a glossary with worked examples, not a restatement of any crate's spec:

• HL7 as a family of standards (v2, v3, the HL7® FHIR® standard) and how they differ.
• ER7's delimiters, and how a message decomposes into segments, fields, repetitions, components, and subcomponents.
• Paths versus names, the dictionary, and message structures.
• The HL7 null versus an absent field, escape sequences, the v2.xml and JSON mappings, and why Z-segments degrade rather than reject.
• A short “try it” section pointing at this workspace's CLI, for readers who want to test an idea against a real message.

One of the worked examples inside it

PID|1||444333222^^^ACME&1.2.3.4&ISO^MR||EVERYWOMAN^EVE^E
 ^  ^  ^                                       ^
 |  |  |                                       PID-5, an XPN (person name)
 |  |  PID-3, a CX (identifier), whose 4th component
 |  |  is itself an HD with subcomponents split by &
 |  PID-2, not sent
 PID-1, the set ID

Using it

With Claude Code, nothing to do beyond having the repository open — skills in a checked-out project are picked up automatically. Other agent tools that support the same SKILL.md convention can point directly at the file; everything else can still read it as plain Markdown, the same as any other page linked from this site.

Why a skill instead of just the README

The root README and this site already describe every crate at length; the skill exists so an agent that only needs the *vocabulary* — what a component is, what the HL7 null means — gets a short, self-contained answer instead of a tour of fourteen crates. It is deliberately general: the concepts hold for any HL7 v2 system, and this workspace supplies the worked examples.

Building or changing this workspace itself instead? See the companion Maintainer skill.