openapi-to-agent-skills

Convert OpenAPI specifications to Agent Skills format — structured markdown documentation optimized for AI agents.

Installation

pip install openapi-to-agent-skills

Usage

openapi-to-agent-skills <path-or-url-to-openapi-spec> [OPTIONS]

Options

Examples

# From a local file
openapi-to-agent-skills api.yaml -o ./skills

# From a URL
openapi-to-agent-skills https://petstore3.swagger.io/api/v3/openapi.json -o ./skills

# Filter by tags
openapi-to-agent-skills api.yaml --include-tags users,orders

# Case-safe output for Windows/macOS
openapi-to-agent-skills api.yaml --case-strategy lowercase

Output Structure

<skill-name>/
├── SKILL.md                          # Entry point with YAML frontmatter
└── references/
    ├── authentication.md             # Auth schemes (if any)
    ├── resources/
    │   └── <tag>.md                  # One per resource group
    ├── operations/
    │   └── <operationId>.md          # One per operation
    └── schemas/
        └── <prefix>/
            ├── _index.md
            └── <SchemaName>.md       # One per schema

Programmatic Usage

from openapi_to_skills import convert_openapi_to_skill
from openapi_to_skills.types import ConvertOptions

import yaml

with open("api.yaml") as f:
    spec = yaml.safe_load(f)

convert_openapi_to_skill(spec, ConvertOptions(output_dir="./output"))

License

MIT