701-technologies-openapi

Use when you need framework-agnostic OpenAPI 3.x guidance — spec structure, metadata and versioning, paths and operations, reusable schemas, security schemes, examples, documentation quality, contract validation (e.g. Spectral), breaking-change awareness, and handoffs to codegen — without choosing Spring Boot, Quarkus, or Micronaut. This should trigger for requests such as Review an OpenAPI; Improve an OpenAPI; Improve API contract; Improve API schema design. Part of Plinth Toolkit

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

70%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is well-structured with a clear validated workflow and clean one-level-deep progressive disclosure, but it is only partially actionable and carries some repo-build noise in its Constraints. Concrete OpenAPI examples in the body and trimming build directives would lift it.

Suggestions

Move or remove the repo-internal Maven build directives ('./mvnw compile', './mvnw clean install -pl skills-generator', 'mvn clean verify') from Constraints — they are repository plumbing, not OpenAPI contract guidance, and pad the skill without adding value.

Add one or two concrete, executable OpenAPI snippets (e.g. a minimal paths/components skeleton or a Spectral rule example) directly in the body so guidance is actionable without opening the reference.

Tighten abstract step phrasing like 'Apply technology-aligned changes' and 'Gather scope and decide target improvements' into more specific, directive instructions tied to the contract-first scope.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean (bullet lists, short scope, tight workflow) but the Constraints section carries repo-internal build directives like './mvnw compile' and 'Regenerate skills with ./mvnw clean install -pl skills-generator' that are environment noise unrelated to the skill's contract-first scope. Not level 3 because of this padding; not level 1 because it avoids over-explaining concepts Claude already knows.	2 / 3
Actionability	Provides directional guidance ('Implement or refactor artifacts following the reference patterns', 'Identify requested outcomes, constraints, and the minimum safe set of changes') but no concrete OpenAPI code, commands, or copy-paste examples in the body itself — real detail is deferred to the reference. Not level 1 because it names specific actions (read the reference, run verification); not level 3 because there are no executable examples here.	2 / 3
Workflow Clarity	A clear four-step sequence (Read reference → Gather scope → Apply changes → Run verification and report) with an explicit validation/report checkpoint in step 4 and an 'EDGE CASE' ask-before-acting clause. Not level 2 because validation is present rather than missing; the destructive-op cap does not apply.	3 / 3
Progressive Disclosure	A single one-level-deep reference (references/701-technologies-openapi.md, no nested refs inside it) is clearly signaled twice — in Workflow step 1 and a dedicated Reference section — and the body is a genuine overview. Not level 2 because navigation is well signaled and content is appropriately split.	3 / 3
	Total	10 / 12 Passed

Description

100%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific, trigger-rich, and complete, naming concrete OpenAPI domains and explicit natural-language triggers while explicitly bounding its framework-agnostic scope. It is distinctive and unlikely to conflict with adjacent skills.

Dimension	Reasoning	Score
Specificity	Enumerates many concrete capability areas — 'spec structure, metadata and versioning, paths and operations, reusable schemas, security schemes, examples, documentation quality, contract validation (e.g. Spectral), breaking-change awareness, and handoffs to codegen' — matching the score-3 anchor of multiple specific actions. Not level 2 because the action list is comprehensive rather than partial.	3 / 3
Completeness	Clearly answers both what (the enumerated guidance areas) and when via explicit 'Use when…' and 'This should trigger for requests such as…' clauses. Not level 2 because the when-trigger is explicit, not merely implied.	3 / 3
Trigger Term Quality	Includes natural user-facing trigger phrases — 'Review an OpenAPI; Improve an OpenAPI; Improve API contract; Improve API schema design' — phrased as a user would say them, plus 'Use when you need framework-agnostic OpenAPI 3.x guidance'. Good coverage of natural terms. Not level 2 because common variations are well covered.	3 / 3
Distinctiveness Conflict Risk	Carves a clear niche — framework-agnostic OpenAPI 3.x contract guidance explicitly excluding 'Spring Boot, Quarkus, or Micronaut' — with distinct triggers unlikely to fire for unrelated skills. Not level 2 because the scope is sharply bounded against adjacent framework skills.	3 / 3
	Total	12 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: jabrena/plinth
Commit: aaee915

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.