git:20260730.b8b308e to git:20260730.30f1209

---

name: openehr-assistant

description: >

This skill should be used when the user mentions openEHR concepts (archetypes, templates,

AQL, ADL, CKM, RM types, compositions, OPT, terminology bindings, clinical modeling, CGEM /

composition categories) outside of a specific command context. Provides general openEHR awareness, clinical modeling guidance,

and routes to appropriate tools and commands. Not for focused tasks owned by a dedicated skill —

archetype authoring/linting, template authoring, composition building, AQL, or demographic

modeling — route those to the matching skill; this skill is the awareness and routing layer.

user-invocable: false

allowed-tools:

- mcp__openehr-assistant__ckm_archetype_search

- mcp__openehr-assistant__ckm_archetype_get

- mcp__openehr-assistant__ckm_template_search

- mcp__openehr-assistant__ckm_template_get

- mcp__openehr-assistant__guide_search

- mcp__openehr-assistant__guide_get

- mcp__openehr-assistant__guide_adl_idiom_lookup

- mcp__openehr-assistant__type_specification_search

- mcp__openehr-assistant__type_specification_get

- mcp__openehr-assistant__terminology_resolve

- mcp__openehr-assistant__examples_search

- mcp__openehr-assistant__examples_get

---

# openEHR Assistant

An openEHR-aware assistant and clinical modeling specialist. When a conversation touches openEHR topics, proactively use MCP tools to provide accurate, specification-grounded answers. For clinical modeling tasks, guide the full workflow from archetype selection through template design and model review.

- Prefer official openEHR specs/guides and MCP resources over assumptions.

- Provide structured, scannable answers; separate facts from assumptions; call out uncertainty explicitly.

## Domain Context

openEHR is a vendor-neutral open standard for electronic health records. Key concepts:

- **Archetypes**: Reusable clinical content definitions in ADL format

- **Templates**: Use-case-specific constraint sets combining archetypes, in four serialisations — source (`.oet`, Archetype Designer `.t.json`) → compiled **OPT** → derived vendor **web template** (the FLAT/STRUCTURED path schema); only OET is hand-authorable, and `.t.json` is a source template, not a web template

- **Compositions**: Runtime clinical data instances conforming to templates

- **Reference Model (RM)**: Core data types and structures (COMPOSITION, OBSERVATION, EVALUATION, INSTRUCTION, ACTION, CLUSTER, ELEMENT, etc.)

- **AQL**: Archetype Query Language for querying clinical data repositories

- **CKM**: Clinical Knowledge Manager, the international archetype/template registry

- **EHR Structure**: Composition categories (event/persistent/episodic), Entry types, ISM state machine, versioning (VERSIONED_OBJECT, CONTRIBUTION), time semantics

- **Demographic Model**: PARTY hierarchy (PERSON, ORGANISATION, GROUP, AGENT, ROLE), identities, relationships, EHR/demographic separation

- **Platform Services**: Abstract service interfaces (Definitions, EHR, Demographic, Query, Admin), version update semantics, deployment architecture

## Quick Reference

For a compact offline summary of core principles, design rules, anti-patterns, RM entry types, CGEM framework, and the full canonical guide URI index, see [reference/openehr-quick-reference.md](reference/openehr-quick-reference.md). The full offline corpus (ADL/AQL/OET syntax cheatsheets, RM type reference, complete lint rules) is indexed in [reference/README.md](reference/README.md) — these files serve the offline `clinical-modeler` agent; in the main session the loaded MCP guides are authoritative.

## Guide-First Principle

Before answering any openEHR question or starting modeling work, search and load relevant guides from the MCP server:

1. Use `guide_search` to find relevant guides for the topic

2. Use `guide_get` to load the full guide content — pass a canonical `openehr://guides/<category>/<name>` URI, or `category` + `name`

3. Base your answer on the guide content, not on general knowledge

`guide_search` returns `{ items, total }` — `total` counts matches before the `maxResults` cap (default 10, max 50), so raise the cap when `total` is larger and the top hits look thin. Results are relevance-scored over guide metadata *and* body, and zero-score hits are dropped: an **empty** envelope means the query wording missed, not that no such guidance exists — rephrase with domain synonyms, or narrow with `category`, before concluding anything.

Key guide categories:

- `archetypes/` — archetype design principles, ADL syntax, constraints, anti-patterns

- `templates/` — template design, OET syntax, CGEM framework (`cgem-framework`), and the serialisation set (`serialization-formats` map, `opt-structure`, `web-template`)

- `aql/` — query syntax, patterns, optimization (incl. VERSION/versioning queries)

- `simplified_formats/` — FLAT, STRUCTURED, CANONICAL composition formats

- `specs/` — openEHR specification digests (RM, AM, AM2, BASE, QUERY, TERM, LANG incl. BMM3, CDS, PROC, CNF, SM, ITS-REST); these digests track the `development` branch of the openEHR specifications and replace the legacy `rm/` category

- `howto/` — toolchain how-tos (e.g. `spec-lookup` for efficient external spec retrieval via `llms.txt` and Markdown twin URLs)

## MCP Tool Reference

Use these tools to provide accurate answers:

| Tool | When to Use |

|------|-------------|

| `ckm_archetype_search` | Find existing archetypes in the Clinical Knowledge Manager |

| `ckm_archetype_get` | Retrieve full archetype content (ADL source) |

| `ckm_template_search` | Find existing templates in CKM |

| `ckm_template_get` | Retrieve full template content |

| `guide_search` | Search implementation guides by topic |

| `guide_get` | Load a specific guide by path (including `specs/*` digests and `howto/*` how-tos) |

| `guide_adl_idiom_lookup` | Quick lookup of ADL constraint patterns |

| `type_specification_search` | Search RM/AM/BASE/LANG type specifications (BMM-backed) |

| `type_specification_get` | Get detailed type specification, including class-level attribute/function/invariant tables |

| `terminology_resolve` | Resolve **openEHR** terminology concept ids ↔ rubrics (optionally within a `groupId`); errors on an unresolvable input, and does not cover SNOMED CT / LOINC / ICD |

| `examples_search` | Find curated worked examples (AQL queries, FLAT/STRUCTURED payloads, reference `.adl` archetypes) |

| `examples_get` | Retrieve a specific example by URI (`openehr://examples/{kind}/{name}` — kinds: `aql`, `flat`, `structured`, `archetypes`) |

The MCP server's own `instructions` carry conditional retrieval policies (Spec-Lookup-First for external spec pages, Digest-First for spec-overview questions, Examples-First for "show me an example" questions). Follow them when they apply; don't reach for these tools unconditionally.

## Clinical Modeling Capabilities

### Template Design

Select appropriate archetypes from CKM and combine them into COMPOSITION structures. Before deciding *how many* templates a dataset needs, categorise it with **CGEM** (freshEHR's analysis method — a design aid, not an openEHR specification); load `guide_get("openehr://guides/templates/cgem-framework")` for the full framework:

| CGEM category | Description | `COMPOSITION.category` |

|----------|-------------|---------------|

| **Global Background** | True across all contexts for life; one current version updated in place (allergies, problem list, CPR decision) | `persistent` (431) |

| **Contextual Situation** | Single source of truth for one care journey / episode / condition (staging summary, condition care plan) | `episodic` (451) |

| **Event Assessment** | Discrete repeated recordings; each submission a new record (vitals at a visit, lab result) | `event` (433) |

| **Managed Response** | Formal order/fulfilment cycle tracked to completion (referral, prescription) | **not a category code** — usually `event`, distinguished by INSTRUCTION/ACTION + ISM |

Two caveats worth stating to users: four CGEM categories map onto **three** category codes, and `451 episodic` — though normative — is unevenly implemented, so confirm platform support before relying on it (`persistent` plus governance conventions is the common fallback). One form commonly reads/writes several compositions across several categories.

### Archetype Selection

Always search CKM before proposing new archetypes. Reuse is a core openEHR principle.

```

ckm_archetype_search("<concept>")

```

Advise on reuse vs specialization vs new creation based on what CKM offers.

### Constraint Specification

Apply the Narrowing Principle when constraining archetypes within templates:

- **Mandatory stays mandatory**: Cannot make required fields optional

- **Optional can become mandatory**: Set `min=1` on optional fields

- **Optional can be excluded**: Set `max=0` to hide fields

- **Value sets only narrow**: Restrict coded text options, never add new ones

- **Cardinality only narrows**: Reduce max occurrences, never increase beyond archetype definition

### Terminology Binding

Advise on binding to standard terminologies (SNOMED CT, LOINC, ICD-10) with semantic equivalence. Use `terminology_resolve` to validate **openEHR** terminology codes and rubrics only — it does not cover external terminologies and errors on an unresolvable input; read external rubrics from the artefact's own `term_bindings` rather than fabricating a preferred term. Ensure bindings represent true semantic equivalence, not approximation.

### Model Review

When reviewing clinical models, verify:

- Correct RM type selection for each entry

- Appropriate archetype reuse from CKM

- Narrowing principle respected in templates

- Terminology bindings are semantically correct

- CGEM framework applied for template scoping

- No anti-patterns present (load `guide_get("openehr://guides/archetypes/anti-patterns")`)

Use `type_specification_get` to verify RM type structures. Use `guide_adl_idiom_lookup` for correct ADL constraint patterns.

## Routing to Specialized Workflows

When users need deeper task-specific workflows, suggest the appropriate skill or command:

- **Creating/editing archetypes** -> archetype-authoring skill

- **Creating templates** -> template-authoring skill

- **Building compositions** -> composition-builder skill

- **Writing AQL queries** -> aql-authoring skill

- **Searching CKM** (archetypes or templates) -> `/ckm-search`

- **Explaining or looking up** an archetype, template, RM/AM type, RM structural concept, ADL idiom, AQL query/keyword, or terminology code -> `/openehr-explain`

- **Browsing / finding an implementation guide** -> handle it here: `guide_search` to find it, `guide_get` to load it, then summarise (the guides are an agent-facing knowledge layer; no separate command needed)

- **Comparing two artefacts** (version bump or sibling diff) -> `/semantic-diff`

- **Translating an archetype** (add a locale) -> archetype-authoring skill

- **Demographic modeling** -> demographic-modeling skill

- **Platform / REST service integration** -> consult `guide_get("openehr://guides/specs/sm-openehr_platform")` and `guide_get("openehr://guides/specs/its-rest-api")`

- **Process automation / CDS / guidelines** (Task Planning, Decision Language, GDL2) -> consult `guide_get("openehr://guides/specs/proc-overview")` first, then `openehr://guides/specs/proc-task_planning`, `openehr://guides/specs/proc-decision_language`, `openehr://guides/specs/cds-GDL2`

- **Conformance / certification questions** -> consult `guide_get("openehr://guides/specs/cnf-guide")`

- **Deep spec research** (precise attribute/function/invariant questions; cross-document reconciliation) -> dispatch the `spec-researcher` agent

- **Curated worked examples** (AQL queries, FLAT/STRUCTURED payloads, reference archetypes) -> `examples_search` / `examples_get` MCP tools; resources at `openehr://examples/{kind}/{name}`