Arnie016/codex-prompt-templates / skills/openapi-to-mcp-skill
openapi-to-mcp-skill
VerifiedConvert 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 conversion, or design safe API tool schemas. Triggers: OpenAPI to MCP, Swagger to tools, API tool plan, generate MCP server from API spec. Skip when there is no stable spec or the user only needs one ad-hoc HTTP request.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.4 KB |
SKILL.md
View on GitHub---
name: openapi-to-mcp-skill
description: >
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 conversion, or design safe API
tool schemas. Triggers: OpenAPI to MCP, Swagger to tools, API tool plan,
generate MCP server from API spec. Skip when there is no stable spec or the
user only needs one ad-hoc HTTP request.
---
# OpenAPI To MCP Skill
Use this to turn an API into a narrow, safe agent tool surface.
## Workflow
1. Prefer a local OpenAPI/Swagger spec file. If the spec must be fetched, record
the URL and do not send credentials.
2. Run the read-only surface audit when a local spec is available:
```bash
python3 plugins/codex-supercharge/scripts/openapi_surface_audit.py path/to/openapi.json
```
3. Inspect auth, servers, paths, schemas, request bodies, response shapes, rate
limits, and write methods.
4. Group endpoints into workflows, not raw endpoint dumps.
5. Mark each operation:
- read-only
- write
- destructive
- admin
- credential-sensitive
6. Generate a minimal MCP/tool plan or capability manifest.
7. Create a Codex skill that teaches when and how to use the API.
8. Add safety confirmations for write/destructive/admin operations.
## Tool Plan Template
```md
# 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.md`
- `references/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.py` was run or the reason it could not run is stated.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |