Skip to content
Skills Library
Programming · Review & audit

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.

Licence
MIT
Last repository change
05.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 05.11.2026, without references to retired models or APIs.

Licence

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

breaking changeAPI compatibilitybackwards compatibleremove fieldrename fielddeprecate endpointAPI versioningsunset
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

  1. When This Skill Applies
  2. Workflow
  3. Report Format
  4. Escape Hatch for the Hook
  5. Safety
  6. References
Original SKILL.md headings · 52 lines, 482 words
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

RepositoryScoreLicence
This page · a-abdellatif98/api-contract-guard100MIT
jeremylongshore/tons-of-skills-marketplace100MIT
Rene-Roscher/skills100Apache-2.0
baibesh/devkit-skills100MIT
AmirAzy/HoNspot100MIT

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".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.