openapi-to-skills CLI
CLI that turns an OpenAPI spec into an Agent Skill of markdown files an agent reads piece by piece, saving context.
- 342 ★ on the repository
- Last commit
- Apache-2.0
Minimal access
Why this level
- The command reads a spec from a file or URL and writes files into the given directory.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/openapi-to-skillsDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The command reads a spec from a file or URL and writes files into the given directory.
This is third-party code. Review the repository files before installing.
What it does
`openapi-to-skills` takes a file or URL of an OpenAPI spec and outputs a directory in Agent Skills format: an overview, resource files, and separate files for operations and schemas. An agent starts from the overview and opens only the operations it needs instead of loading the whole spec. Operations are grouped by tag or path prefix, schemas by name prefix. Filters select tags, paths and deprecated methods, and Eta templates can be overridden. The package exports `convertOpenAPIToSkill` for build pipelines, and `skills/openapi-to-skills` holds a skill for agent-driven generation.
Who it is for. Developers who want an agent to know a large API without a hand-written MCP server and a bloated context.
Good fit when
- A multi-megabyte spec does not fit the agent's context in full.
- An internal API needs a skill, and writing MCP tools takes too long.
- Needed tags are selected from the spec and deprecated operations dropped.
- The API skill is rebuilt in a pipeline after every spec update.
Not a fit when
- You need a client with ready endpoint calls: the output is markdown documentation.
- The spec relies on external `$ref`: there is no warning for unresolved references yet.
- There is no OpenAPI description of the API at all.
Example request
Convert `./openapi.yaml` into a skill in `./output`, group operations by tag and exclude deprecated ones.Limitations
The output is markdown documentation, not an executable client. Unresolved external `$ref` entries are not detected yet: a warning is on the roadmap. It works only from the API description: the agent makes the actual requests to the service by other means. A big spec becomes thousands of files: a 7.2 MB public API collection produced 2,135 files. Review the result before connecting it: structure and grouping depend on the tags and path prefixes in the spec.
How to disable. Delete the generated skill directory from the agent folder and the `openapi-to-skills` package from dependencies if it was added to a project.
FAQ
Where does the spec come from?
From a local file or a URL: `npx openapi-to-skills https://example.com/openapi.yaml -o ./output`.
What is the output?
A directory in Agent Skills format: an overview, resource indexes, and separate files for operations and schemas.
Can the output format be changed?
Yes. Default Eta templates can be overridden, and tags, paths and deprecated methods are selected with filters.
Is there a programmatic API?
Yes. The package exports `convertOpenAPIToSkill`, plus `createParser`, `createRenderer` and `createWriter`.
What does it look like at scale?
On a public API collection one 7.2 MB file became 2,135 files: 588 operations and 1,468 schemas sit separately.
Discussion
No questions or reviews yet.
Related
CLI toolsskill-creator: skills from OpenAPI, GraphQL and MCP
@asnd/skill-creator
The /skill-creator command turns a link to an OpenAPI spec, GraphQL schema or MCP server into a ready skill with wrappers.
Over 1,100 ready-made skills for Claude Code, Codex, Gemini CLI and Cursor, plus an MCP server that picks a skill for the task
The author's personal set: shared agent rules and dozens of skills for GitHub, the browser, macOS, messaging and releases, plus a sync script
skills-npm links agent skills shipped in your dependencies in node_modules and listed in the skills field of package.json
Dozens of mizchi's agent skills: frontend audits, AWS, Cloudflare, SQL, Playwright and OpenTelemetry, installed one by one
A set of independent skills against drift in large codebases: hard-cut, root-cause tracing, lean testing and CI right-sizing.
README in short
The idea is that an agent reads OpenAPI docs in parts: overview first, then the operations and schemas it needs. Any agent can read files, so no special integration is required.