api-contract
/api-contract
This skill should be used when the user edits or reviews an API contract or anything that shapes one (OpenAPI or Swagger files, GraphQL schemas or resolvers, serializers such as ActiveModel::Serializer, jbuilder, Blueprinter, Django REST Framework serializers, Laravel API Resources, request validation, route files), or mentions "breaking change", "API compatibility", "backwards compatible", "remove field", "rename field", "deprecate endpoint", "API versioning", "sunset", "oasdiff" or "graphql-inspector". Classifies changes as breaking or safe and gives a safe evolution path.
- Author
- a-abdellatif98 ↗
- Repository
- api-contract-guard ↗
- Licence
- MIT
- Last repository change
- 05.11.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 05.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
This skill should be used when the user edits or reviews an API contract or anything that shapes one (OpenAPI or Swagger files, GraphQL schemas or resolvers, serializers such as ActiveModel::Serializer, jbuilder, Blueprinter, Django REST Framework serializers, Laravel API Resources, request validation, route files), or mentions "breaking change", "API compatibility", "backwards compatible", "remove field", "rename field", "deprecate endpoint", "API versioning", "sunset", "oasdiff" or "graphql-inspector". Classifies changes as breaking or safe and gives a safe evolution path.
Triggers from the description
Original author description
This skill should be used when the user edits or reviews an API contract or anything that shapes one (OpenAPI or Swagger files, GraphQL schemas or resolvers, serializers such as ActiveModel::Serializer, jbuilder, Blueprinter, Django REST Framework serializers, Laravel API Resources, request validation, route files), or mentions "breaking change", "API compatibility", "backwards compatible", "remove field", "rename field", "deprecate endpoint", "API versioning", "sunset", "oasdiff" or "graphql-inspector". Classifies changes as breaking or safe and gives a safe evolution path.
How it works
- When This Skill Applies
- Workflow
- Report Format
- Escape Hatch for the Hook
- Safety
- References
SKILL.md preview
--- name: api-contract description: This skill should be used when the user edits or reviews an API contract or anything that shapes one (OpenAPI or Swagger files, GraphQL schemas or resolvers, serializers such as ActiveModel::Serializer, jbuilder, Blueprinter, Django REST Framework serializers, Laravel API Resources, request validation, route files), or mentions "breaking change", "API compatibility", "backwards compatible", "remove field", "rename field", "deprecate endpoint", "API versioning", "sunset", "oasdiff" or "graphql-inspector". Classifies changes as breaking or safe and gives a safe evolution path. version: 1.0.0 --- # API Contract Guard Catch changes that break existing API clients before they ship, and offer a safe way to make the same change. ## When This Skill Applies - A contract file changes: OpenAPI or Swagger (`openapi.yaml`, `swagger.json`, `docs/api/*.yaml`), GraphQL SDL (`*.graphql`, `*.graphqls`, `*.gql`). - Code that defines the wire format changes: serializers, API resources, GraphQL type classes, request validation (FormRequest, DTOs, DRF fields), route files. - The user plans to remove, rename or retype a field, endpoint, argument or enum value, or to change auth. ## Workflow 1. **Find the contract sources.** Glob for spec files and the per-framework files listed in `references/sources.md`. Prefer a checked-in spec over inferring from code; if the spec is generated from code, review the code too. 2. **Get the old version.** Use what the user points to (an older file copy, a worktree, a pasted diff). Without shell access, do not try to read git objects; ask the user for an exported copy such as `git show origin/main:openapi.yaml > /tmp/openapi.base.yaml`. 3. **Classify every change** with `references/breaking-changes.md`. Remember the direction rule: what the server returns (responses, GraphQL output types) may only grow; what the server accepts (parameters, request bodies, arguments, input types) may only get looser. 4. **For each breaking change, propose a safe path** from `references/evolution-patterns.md` (add then deprecate then remove, expand and contract, a new version, Deprecation and Sunset headers). 5. **Recommend a CI check** from `references/tools.md` (oasdiff for OpenAPI, graphql-inspector for GraphQL) so the check does not depend on review alone. `scripts/openapi_diff.py` in this plugin is a small dependency free fallback for OpenAPI 3. ## Report Format ``` ## API Contract Report BREAKING - [file:line] <change>: <which clients break and how> Safe path: <steps> RISKY (not strictly breaking) - [file:line] <change>: <why it may still hurt, e.g. new response enum value> SAFE - <additive changes, one line each> ``` If nothing is breaking, say so in one line and list the safe changes briefly. ## Escape Hatch for the Hook The plugin's PreToolUse prompt hook blocks clearly breaking edits to OpenAPI and GraphQL schema files. When the user has explicitly approved a breaking change (for example in a new major version, or after the sunset date), add `# api-contract: breaking-approved` to the YAML or GraphQL file. JSON has no comments, so add `"x-api-contract-note": "api-contract: breaking-approved"` (OpenAPI allows `x-` extension keys on most objects, including the root). Never add the marker on your own initiative. ## Safety Read files only. Never open `.env`, credential files, tokens, or `~/.claude`. Do not call live APIs to compare schemas unless the user asks and supplies the endpoint. ## References - `references/breaking-changes.md`: what counts as breaking vs safe, for REST and GraphQL - `references/evolution-patterns.md`: deprecate then remove, versioning, expand and contract, sunset headers - `references/sources.md`: per-source detection notes (OpenAPI, GraphQL, Rails, Django REST Framework, Laravel, Node) - `references/tools.md`: oasdiff, graphql-inspector and the bundled script, with verified commands
Files in this package (5)
- SKILL.md 4 KB
- references/breaking-changes.md 5 KB
- references/evolution-patterns.md 4 KB
- references/sources.md 8 KB
- references/tools.md 4 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · a-abdellatif98/api-contract-guard | 100 | MIT |
| jeremylongshore/tons-of-skills-marketplace | 100 | MIT |
| Rene-Roscher/skills | 100 | Apache-2.0 |
| baibesh/devkit-skills | 100 | MIT |
| AmirAzy/HoNspot | 100 | MIT |
Database snapshot: 13.11.2026 · package version 2ad50f91689d (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90api-contract-design
REST and GraphQL API design patterns, OpenAPI/Swagger specifications, versioning strategies, and authentication patterns. Use when designing APIs, reviewing API contracts, evaluating API technologies, or implementing API endpoints. - 100api-design
Design REST/GraphQL/OpenAPI contracts before implementation — API-first approach. Use when: API, endpoint, REST, GraphQL, OpenAPI, API contract, API design, HTTP endpoint, grpc, soap. - 100openapi-breaking-change-report
Compares two versions of an OpenAPI 3.x spec and reports breaking, risky and safe changes for API consumers, with a semver bump suggestion and migration notes. Use when asked to diff OpenAPI or Swagger specs, check for breaking changes, review an API PR, compare openapi.yaml files, or run oasdiff. - 90dev-api-contract-review
Use to design or review API contracts, auth, pagination, versioning, errors, compatibility, and OpenAPI/GraphQL shape. - 100review-api-compat
Use when the user asks for an API compatibility review, breaking change review, proto breaking change review, buf breaking review, OpenAPI compatibility check, gRPC backwards compatibility audit, "are these API changes breaking", "did we break the wire", contract evolution… - 100design-api
Design REST and GraphQL APIs: naming, versioning, error shapes, auth. Use when "design an API", "create endpoints", "REST vs GraphQL", or "API contract".