jentic-api-improve
OpenAPI Improve
Overview
Improve the OpenAPI document at the provided path or URL ($0) for AI-readiness. The target document is the first argument passed to this skill. An optional second argument ($1) specifies the output directory; when omitted, the outputs land in the input file's own directory (see "Output").
This skill runs a baseline score that includes diagnostics, identifies weak dimensions and actionable diagnostics, then applies targeted improvements — either inline for simple fixes or via a subagent for multi-iteration loops. Improvements are non-breaking (they only add to the spec, never change or remove existing paths, parameters, or response shapes) and produce both an improved spec and an OpenAPI Overlay (the reusable delta).
If the jentic-api-scorecard skill is installed, you can use it for a more thorough initial and/or final analysis before starting improvements or within iterations.
Reference files in references/ are large and should be loaded lazily — only read a reference file when its content is specifically needed (e.g. to understand scoring formulas or overlay structure). Do not preload all references at once.
For Claude Code users: copy agents/jentic-api-improve.md (from the repo root) to your project's .claude/agents/ or ~/.claude/agents/ to enable the declarative subagent definition. This is optional — the skill works without it by spawning subagents via inline brief.
Running Autonomously
The skill is engineered to minimise permission prompts, but Claude Code's permission model is layered and the choice of permission mode decides which prompts you will actually see. Three paths get you to autonomous execution:
--permission-mode bypassPermissions(or--dangerously-skip-permissions) — zero prompts; all guards off. Works regardless of what the skill'sallowed-toolsdeclares (the two are at different layers, not mutually exclusive). The simplest path when you want hands-off behaviour and accept the broader trust posture; appropriate for sandboxed/containerised runs. Recommended for fully unattended automation.