openapi-to-mcp-skill
Convert OpenAPI/Swagger APIs into Codex-friendly MCP/tool workflows and generated skills. Use when the user wants to expose an API to agents, create a skill from API docs, use toolcast-style conversio
SKILL.mdskills/openapi-to-mcp-skill/SKILL.md
GitHubOpenAPI To MCP Skill
Use this to turn an API into a narrow, safe agent tool surface.
Workflow
Prefer a local OpenAPI/Swagger spec file. If the spec must be fetched, record the URL and do not send credentials.
Run the read-only surface audit when a local spec is available:
python3 plugins/codex-supercharge/scripts/openapi_surface_audit.py path/to/openapi.jsonInspect auth, servers, paths, schemas, request bodies, response shapes, rate limits, and write methods.
Group endpoints into workflows, not raw endpoint dumps.
Mark each operation:
- read-only
- write
- destructive
- admin
- credential-sensitive
Generate a minimal MCP/tool plan or capability manifest.
Create a Codex skill that teaches when and how to use the API.
Add safety confirmations for write/destructive/admin operations.
Tool Plan Template
# API Tool Plan
## Auth
## Read Tools
## Write Tools
## Destructive Tools
## Admin And Credential-Sensitive Tools
## Rate Limits
## Error Handling
## Required Confirmations
## Example Prompts
Skill Rule
The skill should describe business workflows, not every endpoint. Keep endpoint details in a reference file.
References
references/openapi-tool-surface.mdreferences/mcp-server-catalog.md- Source inspiration only, code not executed:
sources/toolcast - Capability-manifest inspiration:
sources/roam-code/src/roam/capability.py
Skip When
- The API has no spec or stable docs to inspect.
- The user only needs a one-off HTTP call, not an agent/tool surface.
- The task is only MCP conformance/release gating; use
$auto-skill-build-mcp-conformance-harness.
Validation
- Auth, rate limits, write/destructive operations, and confirmations are explicit.
- Generated tool groups map to workflows rather than raw endpoint dumps.
- Credential-sensitive operations route through
$mcp-safety-review. openapi_surface_audit.pywas run or the reason it could not run is stated.