skills.rest
paultyng
paultyngCOMMUNITY
Explore all skills by this author →
GitHub

review-api-compat

Detect breaking changes in protobuf, OpenAPI, and GraphQL API contracts.

9|Updated Mar 22, 2026
Search Tags:#openapi#protobuf#breaking-changes#grpc#api-review#backwards-compatibility#api-compatibility
One-click install
npx skills add https://github.com/paultyng/skill-issue --skill review-api-compat
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: review-api-compat
Source: https://github.com/paultyng/skill-issue/tree/main/skills/review-api-compat
Command: npx skills add https://github.com/paultyng/skill-issue --skill review-api-compat

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill solves the risk of accidentally introducing breaking changes to APIs (protobuf, OpenAPI, GraphQL) that disrupt existing clients, cause service outages, and force unplanned, costly migrations for downstream consumers.

Core Features & Use Cases

  • Multi-surface breaking change detection: Scans protobuf services, OpenAPI specs, and GraphQL schemas for incompatible changes, classifying each as wire-breaking, behavior-breaking, policy-breaking, or non-breaking.
  • Policy-aware review: Aligns findings with your project's declared compatibility rules (e.g. buf WIRE_JSON policy, OpenAPI SemVer rules) to avoid false positives.
  • Actionable remediation guidance: Recommends safe fixes like deprecate-then-remove cycles, version bumps, or additive alternative fields to resolve breaking changes without disrupting users.
  • Use Case: A team updating a public gRPC payment service can use this Skill to flag removed proto fields or changed method signatures that would break 200+ internal client services, and get step-by-step guidance to deprecate fields safely before removal.

Quick Start

Use the review-api-compat skill to audit the API changes in your current pull request for backwards compatibility issues.

Frequently Asked Questions about review-api-compat

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I detect breaking changes in protobuf, OpenAPI, or GraphQL APIs?▼

To detect breaking changes in protobuf, OpenAPI, or GraphQL APIs, you can scan pull request diffs or compare tags to classify incompatible modifications by severity and receive actionable remediation guidance.

What is the best way to prevent backwards compatibility issues in a gRPC service?▼

Preventing backwards compatibility issues in a gRPC service involves auditing protobuf contract changes against project-specific policies to catch removed fields or altered signatures before they ship, ensuring safe deprecate-then-remove cycles.

Can I enforce custom compatibility policies when reviewing OpenAPI spec changes?▼

Yes, you can enforce custom compatibility policies when reviewing OpenAPI spec changes by aligning the audit with your declared project rules, such as OpenAPI SemVer rules, to avoid false positives and ensure safe API evolution.

How does an API review classify the severity of breaking changes?▼

An API review classifies the severity of breaking changes by categorizing each modification as wire-breaking, behavior-breaking, policy-breaking, or non-breaking to determine its impact on existing clients.

What should I do when an API audit finds removed fields in a public contract?▼

When an API audit finds removed fields in a public contract, you should apply the recommended remediation guidance to implement additive alternative fields or version bumps, resolving the breaking changes without disrupting downstream consumers.

Related Skills

Explore More Software Engineering Skills→
summarybotngsummarybotng
2

QE Contract Testing

Automate API contract testing with Pact, OpenAPI, and GraphQL schema validation.

Official
Advanced
fyndxfyndx
1

prisma-orm-v7-skills

Summarize Prisma ORM v7 breaking changes and migration steps for Node.js/TypeScript codebases.

Official
Advanced
ReefBytesReefBytes
1

database-migration-guard

Validate database migrations for breaking changes and backwards compatibility in CI pipelines.

Community
Advanced
anton-abyzovanton-abyzov
156

confluent-schema-registry

Manage Avro, Protobuf, and JSON Schema compatibility and evolution via Confluent Schema Registry.

Community
Advanced