Menu
Auto-fix common OpenAPI spec issues with a preview-first workflow
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Prepare a release (phases 1-6). Usage: /prepare-release [version]. If version omitted, infers from conventional commits. Coordinates agents for review, runs prepare-release.sh, then enhances release notes with rich formatting.
Run corpus regression tests against real-world OpenAPI specs. Usage: /corpus-test [short]
Generate test scaffolding for a Go file following oastools conventions. Usage: /gen-test <file.go> [function names...]
Review unpushed commits before pushing for code quality, bugs, security issues, and error handling. Use when preparing to push commits, want pre-push code review, or need to validate changes before pushing. Runs comprehensive analysis using specialized review agents.
Publish a prepared release (phase 7). Usage: /publish-release <version>. Requires version argument. Wraps publish-release.sh for deterministic execution.
Run full validation suite (make check + gopls diagnostics) and report structured pass/fail. Usage: /quality-gate [package...]
| name | fix-spec |
| description | Auto-fix common OpenAPI spec issues with a preview-first workflow |
Always start with a dry run to see what would change:
{
"spec": {"file": "<path>"},
"dry_run": true
}
Include any specific fix flags the user requested:
fix_schema_names -- Rename generic names like Object1, Model2 to meaningful namesfix_duplicate_operationids -- Deduplicate operationId valuesprune -- Remove empty paths and unused schemasstub_missing_refs -- Create stub schemas for missing $ref targetsIf no specific flags are given, the tool applies the default fix (missing path parameters).
Show the user a clear summary of planned fixes:
Results are paginated (default limit: 100). When returned < fix_count, there are more fixes:
{"spec": {"file": "<path>"}, "dry_run": true, "offset": 100, "limit": 100}
✅ Page through all fixes so the user gets a complete picture before confirming. Group fixes by type for readability (e.g., "842 missing path parameters, 12 duplicate operationIds").
Ask the user to confirm before proceeding. If they want to exclude certain fixes, adjust the flags accordingly.
Run the fix tool without dry_run, using output to write the result to disk:
{
"spec": {"file": "<path>"},
"output": "<output-path>",
"fix_schema_names": true
}
⚠️ Important: The fix tool does not modify the input file. Without output, the fixed document only exists in the response (when include_document: true). Always use output to persist the result for subsequent steps.
For in-place updates, set output to the same path as the input file. Add "include_document": true if the user also wants to see the full corrected spec in the response.
Run the validate tool on the output file from step 3:
{"spec": {"file": "<output-path>"}}
Report the final validation status. If new issues were introduced, investigate and explain them.
Provide a final summary: