--- canonical: https://docs.jentic.com/cli/api-improve-skill/ representation: markdown-alternate # Canonical page: https://docs.jentic.com/cli/api-improve-skill/ # This is the Markdown alternate of the page above. --- # API Scorecard – Agent Skill (Improvements) The `jentic-api-improve` **agent skill** closes the loop on scoring: it raises an OpenAPI document’s JAIRF score with non-breaking improvements and produces an improved spec, a reusable OpenAPI Overlay, and a before/after changelog. Install it through whichever path fits your agent. --- ## jentic-api-improve Scoring tells you _what_ to fix; the `jentic-api-improve` skill closes the loop and _fixes_ it. Point an AI coding agent at an OpenAPI document and it runs a baseline score, identifies the weak dimensions and the semantic diagnostics, applies improvements (by default **non-breaking** — adding `summary`/`description`/`example`/`tags`, never changing existing paths, parameters, or response shapes), and produces three artifacts: an improved spec, an [OpenAPI Overlay](https://spec.openapis.org/overlay/v1.1.0.html) (the reusable delta), and a changelog with before/after scores. A `mode` argument bounds how far the skill may go: - **`summary-description`** — applies only the LLM-sourced `summary`/`description` suggestions from the scorecard's diagnostics (requires `--with-llm`; fails if no LLM is available). - **`non-breaking`** (default) — the full strictly-additive set above. - **`full`** — more iterations and a broader set of edits, **including breaking changes**, bounded by a guard that never lets any JAIRF dimension drop below baseline. Every run also runs an [`oasdiff`](https://github.com/oasdiff/oasdiff) breaking-change check against the original spec: the result is reported in the changelog in all modes, and a detected break **fails the run** in `summary-description` / `non-breaking` (it is reported but non-fatal in `full`). This skill orchestrates the scorecard CLI plus a few extra command-line tools, so it needs more than the CLI alone. In addition to the scorecard CLI's [Requirements](./api-scorecard.md#requirements) (Node.js ≥ 20.19, a running Docker daemon, and a `JENTIC_API_KEY` for local-file scoring), install: ```bash pipx install jentic-openapi-tools # validation pipx install jentic-apitools-cli # overlay verification (command: jentic-apitools) pipx install check-jsonschema # overlay schema validation go install github.com/oasdiff/oasdiff@latest # breaking-change detection (or: brew install oasdiff) # plus python3 and jq, which most systems already have ``` Install the skill through whichever path fits your agent — the same three channels as the [scoring skill](./api-scorecard-skill.md#jentic-api-scorecard): ### Claude Code The improve skill is a **separate plugin** in this repository's marketplace: ``` /plugin marketplace add jentic/jentic-api-scorecard /plugin install api-improve@jentic-api-scorecard ``` The marketplace half is the same `jentic-api-scorecard` as the [scoring skill](./api-scorecard-skill.md#jentic-api-scorecard) — only the plugin name changes, to `api-improve`. Installing the plugin also registers the companion `jentic-api-improve` subagent (used for multi-iteration improvement loops). Once installed, ask Claude to improve a spec: ``` > Improve ./openapi.yaml for AI-readiness > Raise the JAIRF score of my API and give me an overlay ``` ### Vercel `skills` CLI ```bash npx skills add jentic/jentic-api-scorecard --skill jentic-api-improve ``` ### TanStack Intent The `@jentic/api-scorecard-cli` npm package ships this skill (and the companion agent definition) inside its published tarball, so it's discoverable by [TanStack Intent](https://tanstack.com/intent) for projects that already depend on the CLI. The agent file lands at `agents/jentic-api-improve.md`; copy it into your `.claude/agents/` to enable the declarative subagent (optional — the skill falls back to spawning a subagent from an inline brief). --- ## Related links * [CLI Reference](./api-scorecard.md) * [Agent Skill (Scoring)](./api-scorecard-skill.md) * [GitHub Action](./api-scorecard-action.md) * [API Scoring – Getting Started](../getting-started/api-scoring.md) * [API Improvements – Getting Started](../getting-started/api-improvements.md) * [Skill definition (SKILL.md)](https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-improve/SKILL.md)