Openapi
DevelopmentopenapiOpenapi is an Agent Skill for development published in the flexprice/flexprice repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Swagger + Speakeasy SDK/MCP pipeline (make swagger, sdk-all), api/custom merge. Trigger: openapi, swagger, sdk-all, MCP.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/flexprice/flexprice/blob/HEAD/.cursor/skills/openapi/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/openapi, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
openapi — OpenAPI & SDKs
Source of truth
- Handlers: Swagger comments in
internal/api/**. - Generated specs:
docs/swagger/(run generation — do not hand-edit JSON as primary source).
Standard sequence
After route or Swagger annotation changes:
make swagger
make sdk-all
make sdk-all (per AGENTS.md) validates, generates SDKs/MCP, merges api/custom/**.
OpenAPI-only validation:
make speakeasy-validate
Custom vs generated
- Do not put long-lived custom logic only in generated trees under
api/go,api/typescript,api/python,api/mcp. - Put custom code in
api/custom/<lang>/and rely onmake merge-custom(often part ofsdk-all).
MCP tooling
Filtered spec and allowed tags live under .speakeasy/mcp/ — changing exposed tools requires config update + regenerate flow documented in AGENTS.md.
When to skip full sdk-all
Small internal-only HTTP tweak with no exported contract change: make swagger alone may suffice; coordinate with reviewers if public SDK repos are consumers.
Related
- Tests after API change: expand handler tests or
api/testsif behavior is user-facing SDK contract.