Skip to content

API Improvements – Getting Started

Score it. Then fix it — automatically.

The Jentic api-improve agent skill closes the loop on scoring. 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 ready to drop in
  • an OpenAPI Overlay — the reusable, reviewable delta between the original and improved spec
  • a changelog with before/after JAIRF 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 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).

Prerequisites

The improve skill orchestrates the scorecard CLI plus a few additional tools. You'll need everything from the API Scoring prerequisites (Node.js ≥ 20, Docker, JENTIC_API_KEY), plus:

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

The improve skill is a separate plugin in the Jentic API Scorecard marketplace:

/plugin marketplace add jentic/jentic-api-scorecard
/plugin install api-improve@jentic-api-scorecard

Installing the plugin also registers the companion jentic-api-improve subagent, used for multi-iteration improvement loops.

npx skills add jentic/jentic-api-scorecard --skill jentic-api-improve

The skill ships inside the @jentic/api-scorecard-cli npm tarball and is discoverable by TanStack Intent for projects that already depend on the CLI.

Improve a spec

Once installed, ask your AI coding agent in plain language:

> Improve ./openapi.yaml for AI-readiness
> Raise the JAIRF score of my API and give me an overlay

The skill will:

  1. Run a baseline score and surface the weakest dimensions.
  2. Apply targeted, improvements to descriptions, summaries, examples, and tags. Changes are non-breaking by default, but refer to the mode option for greater control.
  3. Re-score to confirm the improvements lifted the grade.
  4. Write three output artifacts alongside your original spec:
  5. openapi.improved.yaml — the improved spec
  6. openapi.overlay.yaml — the reusable OpenAPI Overlay
  7. CHANGELOG.md — before/after scores and a summary of changes

Next steps