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 semantic diagnostics, applies non-breaking improvements (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

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
# 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, non-breaking improvements to descriptions, summaries, examples, and tags.
  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