From versioning
OpenAPI diff tools, schema comparison, and migration guide templates for detecting breaking changes in APIs, databases, and contracts. Use when analyzing API changes, comparing OpenAPI specs, detecting breaking changes, validating backward compatibility, creating migration guides, analyzing database schema changes, or when user mentions breaking changes, API diff, schema comparison, migration guide, backward compatibility, contract validation, or API versioning.
How this skill is triggered — by the user, by Claude, or both
Slash command
/versioning:breaking-change-detectionThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Comprehensive patterns, scripts, and templates for detecting and documenting breaking changes across APIs, databases, and contracts during version bumps.
examples/api-contract-analysis.mdexamples/database-migration-detection.mdexamples/versioning-strategy.mdscripts/analyze-breaking.shscripts/graphql-diff.shscripts/openapi-diff.shscripts/proto-diff.shscripts/schema-compare.shtemplates/breaking-change-report.mdtemplates/ci-cd-breaking-check.yamltemplates/deprecation-notice.mdtemplates/migration-guide-api.mdtemplates/migration-guide-database.mdtemplates/migration-guide.mdComprehensive patterns, scripts, and templates for detecting and documenting breaking changes across APIs, databases, and contracts during version bumps.
This skill provides functional tools for detecting breaking changes in:
All scripts include proper error handling, diff algorithms, and detailed reporting.
Analyze OpenAPI Specification Changes:
scripts/openapi-diff.sh to compare two OpenAPI spec versionstemplates/breaking-change-report.md for documentationCommon Breaking Changes Detected:
Detect Database Migration Issues:
scripts/schema-compare.sh to compare database schemasBreaking Changes in Databases:
Analyze All Changes Across Systems:
scripts/analyze-breaking.sh as orchestrator scriptAnalysis Process:
# Run comprehensive analysis
bash scripts/analyze-breaking.sh \
--old-api old-spec.yaml \
--new-api new-spec.yaml \
--old-schema old-schema.sql \
--new-schema new-schema.sql \
--output breaking-changes-report.md
Document Breaking Changes for Users:
templates/migration-guide.md as starting templatetemplates/migration-guide-api.md for API-specific changestemplates/migration-guide-database.md for schema changesMigration Guide Structure:
Integrate Breaking Change Detection:
templates/ci-cd-breaking-check.yaml for GitHub Actions/GitLab CICI/CD Integration Pattern:
# Detect breaking changes before merge
- name: Check for breaking changes
run: bash scripts/analyze-breaking.sh --old $BASE_BRANCH --new $HEAD_BRANCH
- name: Fail if breaking changes without major version bump
if: breaking_detected && !major_version_bump
run: exit 1
Classify Breaking Changes by Impact:
CRITICAL (Immediate user impact):
HIGH (Requires code changes):
MEDIUM (Behavior changes):
LOW (Documentation updates):
Minimize Breaking Changes:
Non-Breaking Alternatives:
openapi-diff.sh: Compare two OpenAPI/Swagger specifications and identify breaking changes
schema-compare.sh: Compare database schemas (SQL, migrations, Prisma, etc.)
analyze-breaking.sh: Orchestrator script that runs all detection tools
graphql-diff.sh: Compare GraphQL schemas for breaking changes
proto-diff.sh: Compare Protobuf definitions for gRPC services
Core Requirements:
jq - JSON parsing and manipulationyq - YAML parsing (for OpenAPI specs)diff - File comparison utilitygit - Version control for diff contextOptional Requirements:
openapi-diff - Enhanced OpenAPI comparison (npm package)oasdiff - Alternative OpenAPI diff toolschemacrawler - Database schema analysisprotoc - Protocol buffer compiler (for gRPC)rover - GraphQL schema tooling (Apollo)Installation Commands:
# Core tools (usually pre-installed)
apt-get install jq diffutils git
# YAML parsing
pip install yq
# Optional OpenAPI tools
npm install -g openapi-diff oasdiff
# Database tools
brew install schemacrawler # macOS
apt-get install schemacrawler # Linux
All scripts follow standard exit code conventions:
0 - No breaking changes detected1 - Breaking changes detected (see report)2 - Invalid arguments or missing dependencies3 - File read/parse errors4 - Comparison failed (incompatible formats)This skill is used by versioning plugin commands:
For additional reference material:
examples/api-contract-analysis.md for OpenAPI diff examplesexamples/database-migration-detection.md for schema change patternsexamples/ci-cd-integration.md for pipeline integrationexamples/versioning-strategy.md for complete workflowSkill Location: plugins/versioning/skills/breaking-change-detection/SKILL.md Version: 1.0.0
npx claudepluginhub vanman2024/dev-lifecycle-marketplace --plugin versioningDetects breaking changes in REST, GraphQL, and gRPC API contracts. Compares OpenAPI schemas and protobuf defs to baselines, classifies severity, validates semver, runs Pact tests, generates reports.
Detects breaking, dangerous, and non-breaking changes between GraphQL schema versions using GraphQL Inspector diff command. Compares files, git branches/tags/commits, and remote endpoints.
Validates OpenAPI, Swagger, GraphQL schemas against backends like Express, FastAPI, Django. Detects breaking changes, generates TypeScript clients from .yaml, .json, .graphql specs.