Skip to content
Back to search

openapi-to-skills

OpenAPI to Agent Skill for context-efficient AI agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/neutree-ai--openapi-to-skills/badge.svg)](/listings/neutree-ai--openapi-to-skills)

HTML

<a href="/listings/neutree-ai--openapi-to-skills"><img src="/api/listings/neutree-ai--openapi-to-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 89 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # openapi-to-skills
  2. [![codecov](https://codecov.io/gh/neutree-ai/openapi-to-skills/graph/badge.svg?branch=main)](https://codecov.io/gh/neutree-ai/openapi-to-skills)
  3. [![npm version](https://img.shields.io/npm/v/openapi-to-skills?logo=npm)](https://www.npmjs.com/package/openapi-to-skills)
  4. Convert OpenAPI specifications into [Agent Skills](https://agentskills.io/) format - structured markdown documentation that minimizes context size for AI agents.
  5. AI agents often need domain-specific knowledge to complete tasks. Rather than writing custom prompts or building MCP tools from scratch, leveraging existing API documentation is a practical approach - and OpenAPI is the de facto standard with battle-tested specifications maintained over years.
  6. However, feeding raw OpenAPI specs to agents has limitations. Complex specifications can exceed LLM context limits, and even when they fit, loading the entire document for every request wastes valuable context.
  7. Agent Skills solves this by structuring documentation for on-demand reading. Agents load only what they need - starting with an overview, then drilling into specific operations or schemas. Since file reading is a universal capability across agent frameworks, this approach works everywhere without special integrations.
  8. ## Features
  9. - **Semantic structure** - Output organized by resources, operations, and schemas, enabling agents to load only relevant sections
  10. - **Smart grouping** - Operations grouped by tags or path prefix (auto-detected), schemas grouped by naming prefix
  11. - **Filtering** - Include/exclude by tags, paths, or deprecated status
  12. - **Customizable templates** - Override default Eta templates for custom output format
  13. ## Usage
  14. ```bash
  15. npx openapi-to-skills ./openapi.yaml -o ./output
  16. # or
  17. bunx openapi-to-skills ./openapi.yaml -o ./output
  18. # or from URL
  19. npx openapi-to-skills https://example.com/openapi.yaml -o ./output
  20. ```
  21. For agent-guided generation, use the [openapi-to-skills skill](./skills/openapi-to-skills/SKILL.md).
  22. See its [CLI reference](./skills/openapi-to-skills/references/cli.md) for all options, layouts, overlays, validation, and regeneration behavior.
  23. ## Programmatic API
  24. The package exports `convertOpenAPIToSkill` for integration into build pipelines or custom tooling:
  25. ```typescript
  26. import { convertOpenAPIToSkill } from 'openapi-to-skills';
  27. const spec = { /* OpenAPI spec object */ };
  28. await convertOpenAPIToSkill(spec, {
  29. outputDir: './output',
  30. parser: {
  31. skillName: 'my-api',
  32. filter: {
  33. includeTags: ['users', 'orders'],
  34. excludeDeprecated: true,
  35. },
  36. },
  37. });
  38. ```
  39. For advanced use cases, individual components (`createParser`, `createRenderer`, `createWriter`) are also exported.
  40. ## Examples
  41. ### Petstore (simple)
  42. See [examples/](./examples) for a simple demo with the classic Petstore spec (3 resources, 19 operations).
  43. ### Public APIs Collection (production-scale)
  44. [public-api-skills](https://github.com/Yuyz0112/public-api-skills) demonstrates real-world usage across a large collection of public APIs:
  45. | Metric | Original | Agent Skills |
  46. |--------|----------|--------------|
  47. | Source | 1 file (7.2 MB) | 2,135 files |
  48. | Resources | - | 77 index files |
  49. | Operations | 588 (all in one) | 588 individual files |
  50. | Schemas | 1,315 (all in one) | 1,468 individual files |
  51. A 7.2 MB monolithic spec becomes 2,135 focused files that agents can navigate on-demand.
  52. ## Roadmap
  53. - [ ] Detect unresolved external `$ref` and warn users
  54. - [x] Support fetching OpenAPI specs from URL
  55. ## Contributing
  56. Development guidelines are maintained in [CLAUDE.md](./CLAUDE.md), designed as a shared reference for both human contributors and AI agents.
  57. We welcome AI-assisted development. However, whether a patch is written manually or with AI collaboration, the author must fully review all changes before submission and take responsibility for the content.
  58. ## License
  59. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.