Skip to content

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 (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 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 (Node.js ≥ 20.19, a running Docker daemon, and a JENTIC_API_KEY for local-file scoring), install:

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:

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

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 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).