Summary This project addresses the challenge of efficiently integrating large, complex OpenAPI specifications into AI agents, which often struggle with context window limitations. It converts OpenAPI documents into a structured "Agent Skills" format, comprising numerous small markdown files, enabling AI agents to access domain-specific API knowledge context-efficiently. This benefits developers and researchers by significantly reducing LLM context window usage, improving agent performance, and simplifying the process of leveraging existing APIs without custom prompts or tools.

How It Works The tool parses OpenAPI specifications and transforms them into a collection of markdown files organized semantically by resources, operations, and schemas. This granular structure allows AI agents to load only the necessary documentation sections on-demand—starting with an overview and drilling into specific operations or schemas as needed. This "drill-down" capability, facilitated by universal file-reading capabilities across agent frameworks, minimizes context window usage and enhances agent efficiency, making complex APIs more accessible to AI.

Quick Start & Requirements Install and run using npx openapi-to-skills ./openapi.yaml -o ./output or bunx openapi-to-skills ./openapi.yaml -o ./output. The tool can also process OpenAPI specs directly from URLs. External references ($ref) within OpenAPI specs must be bundled into a single file prior to processing using tools like npx swagger-cli bundle.

Highlighted Details

• Semantic Structure: Output is organized into SKILL.md (overview), references/resources/, references/operations/, and references/schemas/ for granular, on-demand agent access.
• Smart Grouping & Filtering: Operations can be grouped by tags or path prefixes, and schemas by naming prefixes. Users can filter inclusions/exclusions based on tags, paths, or deprecated status.
• Customizable Templates: Supports overriding default Eta templates for tailored output formats.
• Scalability: Demonstrates transformation of a 7.2 MB monolithic spec into 2,135 focused files, significantly improving agent navigability and reducing context load.

Maintenance & Community Development guidelines are documented in CLAUDE.md, welcoming AI-assisted contributions with an emphasis on author responsibility for reviewed changes. A roadmap item exists to add warnings for unresolved external $refs. No community links (e.g., Discord, Slack) are provided.

Licensing & Compatibility The project is licensed under the Apache-2.0 license. This license is permissive and generally compatible with commercial use and linking within closed-source projects.

Limitations & Caveats External $refs require pre-bundling into a single OpenAPI file. The feature to automatically detect and warn about unresolved external $refs is still under development.