ai-plugins

AI-assistant plugins for openEHR — official plugin marketplace of the openEHR Foundation.

Repository Purpose

This repo contains AI-assistant plugins that support openEHR work — packaged as a dual Claude Code and Cursor plugin marketplace; the skill content (SKILL.md, an open cross-tool format) is the canonical artifact, and each assistant gets a thin manifest layer (.claude-plugin/, .cursor-plugin/) around the same skills, so further assistants can be added the same way. It is not a specification repository — it provides AI-assisted tooling for authors working in specifications-XX repos.

Structure

ai-plugins/
├── .claude-plugin/marketplace.json    # Claude Code marketplace manifest
├── .cursor-plugin/marketplace.json    # Cursor marketplace manifest
├── docs/                              # Contributor and user documentation
├── scripts/validate.py                # Manifest, frontmatter and template-set validation (CI)
├── scripts/test_scaffold.py           # Unit tests for the scaffold skill's script (CI)
├── scripts/test_check_bmm.py          # Unit tests for the bmm-authoring skill's checker (CI)
├── CHANGELOG.md                       # Release notes per plugin
└── plugins/<plugin-name>/             # One directory per plugin
    ├── .claude-plugin/plugin.json     # Claude Code plugin manifest
    ├── .cursor-plugin/plugin.json     # Cursor plugin manifest
    ├── README.md                      # Plugin purpose, install, and component inventory
    ├── skills/<skill-name>/           # Knowledge/workflow skills; user-only actions set disable-model-invocation: true
    │   ├── SKILL.md                   # Skill definition (YAML frontmatter + body)
    │   ├── references/                # Optional supplementary content
    │   └── assets/, scripts/              # Optional bundled templates and scripts (see `scaffold`)
    └── agents/<agent>.md              # Autonomous subagents (context-isolated, multi-file)

Current plugins: openehr-specs (skills, including user-only action skills, and subagents). plugins/openehr-specs/README.md is its inventory: update it, the root README.md, and the skill and subagent names in docs/prompting-guide.md, whenever a component is added, removed, or renamed. validate.py checks none of them.

Key Conventions

• Plugin names: openehr-<domain> (mandatory prefix — flat global namespace); skill names: terse activity nouns with no prefix (auto-namespaced as <plugin>:<skill>). User-only action skills and subagents follow the same no-prefix rule (spec-reviewer is the one exception).
• Component choice follows the nature of the work: skills = knowledge/workflows (model- or user-invoked); user-only action skills (publish, regen-classes, scaffold) = user-initiated actions, also in skills/, marked disable-model-invocation: true so their descriptions stay out of context and they don't compete with knowledge-skill triggering (Claude Code treats commands/ as the older format, so new actions are skills); subagents (agents/) = context-heavy, multi-file, or adversarial work that would otherwise pollute the main context. Action skills and agents reference their sibling knowledge skill rather than duplicating it.
• Skill description frontmatter is lean (~50–75 words): one what+scope sentence → a few representative triggers → short "Not for …" anti-triggers routing to the right sibling/plugin.
• Keep each SKILL.md body a lean overview (quick-reference + pointers); push bulky detail (tables, templates, format specs) into references/ so it loads only on demand.
• Versions must stay in sync across both plugin manifests (.claude-plugin/ and .cursor-plugin/), both marketplace entries, and the release tag ({name}--v{version}).
• Pull requests do not bump versions: add changelog lines under ## Unreleased, and a maintainer bumps at release. A push without a bump never reaches installed copies, because Claude Code compares versions.
• Never invent identifiers, paths, class names, or conventions — ground everything in published openEHR specifications. To verify, read the spec's Markdown twin: take any specifications.openehr.org/...page.html URL and swap .html → .md.
• Do not duplicate community tooling (e.g. CKM/clinical modeling is covered by Cadasto's plugins); this repo covers ground the Foundation owns.

Full details: docs/skill-authoring.md

Development

Pure-content repository (JSON manifests + markdown skills) — no build step or package manager. Two skills bundle a script, each with unit tests: scaffold (scripts/scaffold.py) and bmm-authoring (scripts/check_bmm.py). Run them with python3 -m unittest discover -s scripts -p 'test_*.py' (runs in CI).

• Validation: python3 scripts/validate.py (Claude + Cursor manifests, version sync, required skill/agent frontmatter fields, component paths, the scaffold template set's integrity, and that the BMM skills name every repo the template set excludes from BMM work — runs in CI; it does not check description length, inventories, or the release tag)
• Local testing: docs/testing.md; versioning/releases: docs/versioning.md
• End-user installation: docs/install.md

Component Dependencies

The skills are pure content, except that bmm-authoring runs a bundled checker; the subagents and the publish, regen-classes and scaffold action skills rely on external tools. All of them degrade gracefully when a tool is absent (each says so in its prompt):

• spec-reviewer, xref-auditor — need a specifications-XX checkout and (for attribute resolution) the sibling specifications-AA_GLOBAL.
• xref-auditor, identifier-grounding — use WebFetch to read spec Markdown twins (.html → .md); identifier-grounding additionally prefers the openehr-assistant MCP (type_specification_get) when connected, falling back to the twin.
• regen-classes — needs Docker (ghcr.io/openehr/bmm-publisher).
• bmm-authoring — needs python3 (standard library only) to run its read-only scripts/check_bmm.py; without it, it says so, reports the schema as unchecked and reviews the change by hand against its reference.
• scaffold — needs python3 (standard library only) to run its bundled scripts/scaffold.py, and says so and stops when it is missing. It writes into the repository it is run in, so it plans first and never overwrites a hand-edited file without being told to. For a new repository's BMM schema it asks Docker for the schemas the local ghcr.io/openehr/bmm-publisher image bundles, and never pulls the image. Without Docker or the image that one file is reported as blocked, and the rest are still written.
• publish — needs Docker and sibling specifications-AA_GLOBAL and component checkouts. It runs the published ghcr.io/openehr/asciidoctor image, which bundles the toolchain and spec_publish.sh; the boilerplate and references are still read from the AA_GLOBAL checkout. It checks that each HTML output was rebuilt and that the log has no missing includes, because the script reports success even when it built nothing or dropped the class tables.

None are bundled (the openehr-assistant MCP is interactively authenticated, not redistributable); document them, don't assume them.

Relationship to Other Repos

• specifications-AA_GLOBAL: shared infrastructure (boilerplate, publishing scripts, styles) consumed by all spec repos
• specifications-XX: individual component repos (RM, AM, BASE, etc.) where specs live
• Changes to this repo never touch those repos. The plugins do edit them (for example the authoring and amendment-record skills), but only when a user runs them inside a checkout.

Git

• Remote: https://github.com/openEHR/ai-plugins
• Main integration branch: main
• Commit messages follow Conventional Commits: type(scope): summary (e.g. feat(openehr-specs): add conformance skill) — see CONTRIBUTING.md