OpenAPI Improve

Overview

Improve the OpenAPI document at the provided path or URL ($0) for AI-readiness. The target document is the first argument passed to this skill. An optional second argument ($1) specifies the output directory; when omitted, the outputs land in the input file's own directory (see "Output"). An optional mode selects how far the skill may alter the spec — non-breaking (default), summary-description, or full (see "Change-Scope Modes"); when omitted, mode is non-breaking and the skill behaves exactly as it did before modes existed.

This skill runs a baseline score that includes diagnostics, identifies weak dimensions and actionable diagnostics, then applies targeted improvements — either inline for simple fixes or via a subagent for multi-iteration loops. In the default non-breaking mode improvements are non-breaking (they only add to the spec, never change or remove existing paths, parameters, or response shapes); summary-description is narrower still, and full opts into breaking changes bounded by the no-dimension-regression guard. Every run produces both an improved spec and an OpenAPI Overlay (the reusable delta), and every run runs an oasdiff breaking-change check against the original.

If the jentic-api-scorecard skill is installed, you can use it for a more thorough initial and/or final analysis before starting improvements or within iterations.

Reference files in references/ are large and should be loaded lazily — only read a reference file when its content is specifically needed (e.g. to understand scoring formulas or overlay structure). Do not preload all references at once.

For Claude Code users: copy agents/jentic-api-improve.md (from the repo root) to your project's .claude/agents/ or ~/.claude/agents/ to enable the declarative subagent definition. This is optional — the skill works without it by spawning subagents via inline brief.

Change-Scope Modes

The skill runs in one of three modes, selected by a mode argument (e.g. mode=full) or an equivalent instruction in the invocation. When no mode is given, the mode is non-breaking — identical to the skill's behavior before modes existed. The mode bounds which edits the skill may apply and how the oasdiff breaking-change check reacts; it threads through to the subagent via the brief's "Change-scope mode" field.