agentsclimarketplace
Sign in

Its rest

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

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).From its SKILL.md

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.

2 things 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.
  • runs commandsInstructs the agent to run 3 commands, including `make bundle SPEC=ehr` and 2 more.

SKILL.md

5.9 KB, ~1.3k tokens by cl100k_base, 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

What ships with it: 2 files

10.5 KB alongside SKILL.md

references/

Keep looking

Skills are one crate of 325,949. 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.