agentsclimarketplace

Its rest

Skill openEHR/ai-plugins/plugins/openehr-specs/skills/its-rest

AI plugins for openEHR - specification authoring, review and governance skills. Claude Code marketplace.

Install
npx -y skills add openEHR/ai-plugins --skill its-rest

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Create, edit, or review the openEHR ITS-REST API sources (OpenAPI 3.0 YAML + Markdown) in the `specifications-ITS-REST` repo. This skill should be used when the user asks to add or edit a REST endpoint/operation/schema/response, write an operation description, review the ITS-REST spec, or update its amendment record. Not for AsciiDoc specs (use authoring) — including the AsciiDoc docs under `specifications-ITS-REST/docs/` (simplified_formats, smart_app_launch).

SKILL.md

5.9 KB, as published. Nobody here has run it

openEHR ITS-REST API Specification Authoring

This skill covers creating and editing the openEHR REST API specification sources in the specifications-ITS-REST repository. Unlike other specifications-XX repos that use AsciiDoc, ITS-REST uses OpenAPI 3.0.3 YAML with Markdown descriptions, split across many small files that are bundled into publishable artifacts.

Exception: The docs/ directory contains some AsciiDoc-based specs (e.g., simplified_formats, smart_app_launch) that follow the standard openEHR authoring conventions. This skill does NOT cover those — use the authoring skill instead.

References

  • File-format conventions: see references/file-formats.md for the detailed format and conventions of each source type — top-level entry YAML, operation files, schema files, Markdown description files, and the HTML amendment record. Load it when writing or editing any of these.
  • Build toolchain: see references/build-pipeline.md for the full Redocly + PHP pipeline, validation, live preview, and code generation.

Repository Structure

specifications-ITS-REST/
├── specifications/                    # Source OpenAPI specs (authoring)
│   ├── overview.openapi.yaml          # Top-level entry: overview/cross-cutting concerns
│   ├── ehr.openapi.yaml               # Top-level entry: EHR API
│   ├── query.openapi.yaml             # Top-level entry: Query API
│   ├── definition.openapi.yaml        # Top-level entry: Definition API
│   ├── demographic.openapi.yaml       # Top-level entry: Demographic API
│   ├── system.openapi.yaml            # Top-level entry: System API
│   ├── admin.openapi.yaml             # Top-level entry: Admin API
│   ├── operations/                    # One YAML file per API operation
│   ├── schemas/<domain>/              # Reusable schema components (ehr, query, common, …)
│   ├── parameters/{path,query,header}/ # Reusable parameter definitions
│   ├── responses/                     # Reusable response definitions
│   ├── headers/                       # Reusable response header definitions
│   ├── docs/<domain>/                 # Markdown description files (overview, ehr, query, …)
│   └── tags/                          # Tag description files (schema docs)
├── computable/OAS/                    # Build output (bundled specs in JSON/YAML)
├── docs/                              # AsciiDoc specs AND rendered HTML output
│   ├── simplified_formats/            # AsciiDoc spec (use authoring skill)
│   ├── smart_app_launch/              # AsciiDoc spec (use authoring skill)
│   └── *.html                         # Rendered HTML (build output)
├── development/                       # Build tooling (PHP, Docker, Makefile)
├── manifest.json                      # Component manifest
├── Makefile                           # Top-level build targets
└── .redocly.yaml                      # Redocly configuration

Source File Types

Each source type has its own format and conventions — detailed in references/file-formats.md:

SourceLocationHolds
Top-level entryspecifications/<domain>.openapi.yamlinfo/x-status/x-spec, servers, paths wiring operations via $ref
Operationspecifications/operations/<resource>_<action>.yamloperationId, summary, tags, params, requestBody, responses (all $ref)
Schemaspecifications/schemas/<domain>/<SchemaName>.yamlPascalCase title = RM class name, properties, $refs
Markdown descriptionspecifications/docs/<domain>/Description.mdRFC 2119 prose, hardcoded spec URLs, http/json code examples
Amendment recordspecifications/docs/overview/Amendment_record.mdHTML table, SPECITS Jira links (not AsciiDoc)

Build Toolchain

Quick reference from the development/ directory (full details in references/build-pipeline.md):

make bundle SPEC=ehr        # Bundle a single spec
make validate SPEC=ehr      # Validate
make all                    # Bundle all specs

Adding a New Endpoint

  1. Create the operation file: specifications/operations/<operation_id>.yaml
  2. Add shared parameters to specifications/parameters/ if new ones are needed
  3. Add shared response definitions to specifications/responses/ if new ones are needed
  4. Add or reference schemas in specifications/schemas/<domain>/
  5. Wire the operation into the appropriate top-level *.openapi.yaml under paths:
  6. Update the amendment record in specifications/docs/overview/Amendment_record.md
  7. Bundle and validate: cd development && make bundle SPEC=<spec> && make validate SPEC=<spec>

Adding a New Schema

  1. Create specifications/schemas/<domain>/<SchemaName>.yaml
  2. Reference it from the operation or parent schema via $ref
  3. Use title matching the RM class name
  4. Follow existing patterns for required, type, properties, and description

Scope Boundaries

  • This skill covers the OpenAPI YAML and Markdown sources in specifications-ITS-REST/specifications/
  • It does NOT cover AsciiDoc documents in specifications-ITS-REST/docs/ (simplified_formats, smart_app_launch) — use authoring for those
  • It does NOT cover the PHP build tooling in development/ — consult .junie/guidelines.md for that
  • It does NOT cover other specifications-XX repositories

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.