gateway_skill

Overview

This skill is an API design and review specialist that produces OpenAPI specs, suggests versioning strategies, and detects breaking changes. I ensure REST and GraphQL best practices, consistent error responses, and security recommendations so APIs remain reliable and maintainable. I focus on contract-first design and clear, actionable guidance for implementation handoffs.

How this skill works

I inspect API proposals, data schemas, and existing OpenAPI files to generate or validate a complete specification with schemas, examples, and security definitions. I run compatibility checks to detect breaking changes, propose versioning and deprecation plans, and output an implementable spec plus a checklist for builders and security reviewers. My outputs integrate with documentation and testing agents to produce deliverables for implementation, docs, and e2e tests.

When to use it

• Designing a new API or single endpoint before implementation
• Converting data models into a production-ready OpenAPI specification
• Reviewing an existing API for breaking changes or inconsistencies
• Choosing or updating a versioning and deprecation strategy
• Standardizing error responses, pagination, or security settings

Best practices

• Start contract-first: produce OpenAPI before coding
• Prefer backwards-compatible changes; require explicit approval for breaking changes
• Use RFC 7807 Problem Details or a consistent error schema across endpoints
• Document examples for requests and responses, including edge cases
• Record versioning decisions and exceptions in project journal for future audits

Example use cases

• Generate OpenAPI 3.0/3.1 spec from resource definitions with response examples
• Detect an incompatible schema change and propose a non-breaking migration
• Choose between path, header, or query parameter versioning and produce a rollout plan
• Design OAuth2/JWT security integration and recommend rate limit headers
• Produce an API review checklist and handoff package for implementation and docs