openapi-to-agent-skills 0.3.2

Convert OpenAPI specifications to Agent Skills format

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

Option	Description	Default
-o, --output	Output directory	./output
-n, --name	Skill name (derived from API title if omitted)
--include-tags	Only include these tags (comma-separated)
--exclude-tags	Exclude these tags (comma-separated)
--exclude-deprecated	Exclude deprecated operations	False
-t, --templates	Custom templates directory
-a, --assets	Static assets directory overlaid onto output
--exclude-paths	Exclude paths matching prefixes (comma-separated)
-g, --group-by	Grouping strategy: tags, path, auto	auto
--case-strategy	lowercase for case-insensitive filesystem safety
-f, --force	Overwrite existing output directory	False
-q, --quiet	Suppress output except errors	False

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