---
canonical: https://docs.jentic.com/getting-started/api-improvements/
representation: markdown-alternate
# Canonical page: https://docs.jentic.com/getting-started/api-improvements/
# This is the Markdown alternate of the page above.
title: "Fix APIs for AI Agents — Jentic API Improvements"
description: >-
  Get started with the Jentic api-improve agent skill: point it at an OpenAPI document
  and it scores, applies non-breaking fixes, and emits an improved spec.
---

# 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](https://spec.openapis.org/overlay/v1.1.0.html)** — 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`](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`).

---

## Prerequisites

The improve skill orchestrates the scorecard CLI plus a few additional tools. You'll need
everything from the [API Scoring prerequisites](./api-scoring.md#choose-your-mode) (Node.js ≥ 20,
Docker, `JENTIC_API_KEY`), plus:

```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

=== "Claude Code"

    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.

=== "Vercel `skills` CLI"

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

=== "TanStack Intent"

    The skill ships inside the `@jentic/api-scorecard-cli` npm tarball and is discoverable by
    [TanStack Intent](https://tanstack.com/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:
   - `openapi.improved.yaml` — the improved spec
   - `openapi.overlay.yaml` — the reusable OpenAPI Overlay
   - `CHANGELOG.md` — before/after scores and a summary of changes

---

## Next steps

- [API Scoring – Getting Started](./api-scoring.md) — score first to understand where to focus
- [Agent Skill (Improvements)](../cli/api-improve-skill.md) — full install reference for all platforms
- [Agent Skill (Scoring)](../cli/api-scorecard-skill.md) — scoring skill reference

- [JAIRF Overview](../reference/api-readiness-framework/overview.md) — the six scoring dimensions