openapi-to-skill

Convert OpenAPI specs into chunked Markdown docs that are easier for LLMs to browse.

Instead of handing one giant OpenAPI file to a model, this CLI produces:

• a top-level SKILL.md for fast route discovery
• one markdown file per route (input + output schema details)

Routes without a title (summary or title) are skipped.

Why?

When working with LLMs, it's important to be context-efficient. Simply dumping an entire OpenAPI spec into a prompt is expensive and inefficient. This tool provides a discovery-first approach to providing OpenAPI docs to your agents. When using openapi-to-skill, your agents workflow is:

• First, it's provided with the basic skill info in it's system prompt
• If necessary, your agent can read SKILL.md to see the list of available routes with a short description
• If the agent wants to use the route, they can fetch a route-specific markdown file to see all input and output schema details

CLI Usage

Generate Skills

bunx openapi-to-skill skill ./openapi.yaml --name example-api --description "OpenAPI docs for Example API"

This will generate a skill at .agents/skills/example-api/SKILL.md with neighboring markdown files for each route.

If you want to write to the global skills directory, you can use the --global flag. This will add the skill to ~/.agents/skills/*.

Generate Markdown Docs

You can also generate markdown docs for a given OpenAPI spec.

bunx openapi-to-skill generate ./openapi.yaml --out ./llm-docs

Generate docs from a URL:

bunx openapi-to-skill generate https://api.example.com/openapi.json --out ./llm-docs

Optional flags:

• --index <name>: index filename (default: README.md)
• --routes-dir <name>: route docs directory name (default: routes)

Output Structure

llm-docs/
  README.md
  routes/
    get-users-list-users.md
    post-users-create-user.md
    ...

What Goes Into README.md

• API title/version/description (from info)
• base URLs (from servers)
• concise route table with:
  • path
  • title
  • description
  • link to route markdown file

Programmatic API

import { Effect } from "effect";
import { BunContext } from "@effect/platform-bun";
import { generateOpenApiMarkdown } from "openapi-to-skill";

const result = await Effect.runPromise(
  generateOpenApiMarkdown({
    source: "./openapi.yaml",
    outputDir: "./llm-docs",
  }).pipe(Effect.provide(BunContext.layer)),
);

console.log(result.indexPath);

Development

bun test
bun run typecheck