OpenAPI Formatopenapi-format

AI Agents

Use openapi-format with AI agents when you want the model to help with OpenAPI work, but still keep the actual transformation grounded in a real CLI workflow. The skill gives the agent a stable command surface for sorting, filtering, overlays, casing, generation, conversion, renaming, splitting, and bundling.

Consistent commands

Agents get a repeatable CLI vocabulary instead of inventing their own OpenAPI editing rules.

Use context efficiently

The CLI does the heavy lifting more efficiently, so the agent does not need to read and parse the full OpenAPI document itself. That keeps context use and token burn lower for large specs.

Inspectable output

Ask the agent for the exact command, config file, and expected result so you can review the change before applying it.

Install the Skill

Install the skill once so the agent can use openapi-format as a shared playbook for sorting, filtering, overlays, casing, generation, conversion, renaming, splitting, and bundling.

Terminal
npx skills add https://github.com/thim81/openapi-format --skill openapi-format

The skill docs include command recipes, config patterns, and troubleshooting notes. That is what keeps AI output aligned with the actual CLI behavior.

Prompting Pattern

Ask the agent for the exact command and config file, not just the final result. That makes the response reproducible and easier to review.

Prompt example
Use openapi-format on ./openapi.yaml to sort paths by tags, remove internal endpoints, and write the result to ./openapi-public.yaml. Show me the exact command and the filter config you used.

What the Skill Covers

Transformation stages

  • Generate operation IDs from templates.
  • Filter by methods, tags, flags, content, and unused components.
  • Apply OpenAPI Overlay files, including `extends`-based workflows.
  • Sort fields, path order, and selected component groups.
  • Apply casing to operation IDs, properties, parameters, and components.
  • Convert OpenAPI 3.0 or 3.1 documents to later versions.
  • Rename the API title, split output trees, or disable bundling.

Agent-friendly outputs

  • Exact CLI commands you can paste into a terminal.
  • Minimal config files instead of broad, generic snippets.
  • Clear warnings when a transformation has side effects.
  • Notes about processing order so the agent does not reorder stages.
  • Troubleshooting guidance for missing files, output, or overlay input.

The CLI Pipeline

The skill follows the actual processing order used by openapi-format. That matters when you combine multiple actions in one request.

Processing order
generate -> filter -> overlay -> sort -> casing -> convertTo -> rename -> write output

If an agent suggests a different order, it is wrong. For example, overlays run after filtering and before sort/casing/conversion.

OpenAPI Overlay Workflows

Overlays are one of the most useful cases for AI agents because the model can draft the target actions while the skill keeps the format and execution rules grounded.

Good agent tasks

  • Patch descriptions or titles across a spec.
  • Add or update server entries, tags, or operation metadata.
  • Use `extends` to layer overlay changes on top of a base document.
  • Inspect the action summary to see what was used or left unused.

Review points

  • Check the overlay JSONPath targets the agent selected.
  • Confirm the base input if the overlay uses `extends`.
  • Prefer a final file diff over trusting the agent's prose summary.

Example Agent Request

Prompt
Use the openapi-format skill to:
1. remove internal operations,
2. apply an overlay that updates the API description,
3. sort the output by tags,
4. and write the result to ./dist/openapi.public.yaml.

Show the exact command, the minimal config or overlay file, and explain the processing order.

Recommended Workflow

  1. Give the agent the input file and the desired transformation.
  2. Ask for the command plus any config or overlay file content.
  3. Review the proposed processing order and output path.
  4. Run the command locally or in CI so the result is reproducible.
  5. Inspect the output diff before accepting the change.
Open the playground from a sample OpenAPI file

When It Helps Most

Best fit

  • Prompting an agent to clean up a spec before publishing.
  • Drafting overlay actions or filter config from natural language.
  • Turning a rough request into a concrete CLI invocation.

Less ideal

  • Large batch changes that need deterministic CI execution only.
  • Situations where you already know the exact CLI flags.
  • One-off edits where the overhead of an agent is unnecessary.