api-diff-analyzer
Compare API specifications to detect breaking changes. Compare OpenAPI spec versions, categorize changes by severity, generate migration guides, and block breaking changes in CI.
npx skills add a5c-ai/babysitter --skill api-diff-analyzer --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Compares API specifications to detect breaking changes, categorize changes by severity, generate migration guides, and block breaking changes in CI. It supports OpenAPI, GraphQL, and Protobuf specs, and produces detailed change reports.
How it works
- Analyzes OpenAPI diffs by loading old and new specs, iterating paths and methods, and recording breaking and non-breaking changes with contexts like endpoint removals, method removals, parameter changes, and schema property updates.
- Detects added required parameters, parameter type changes, and removed schemas or properties as breaking or informational, and aggregates a summary of breaking, non-breaking, and info changes.
- Categorizes changes according to predefined breaking-change rules and can generate a migration guide that groups changes by category and provides before/after code examples for select categories. It can emit a report describing each change, with optional migration notes.
- Provides a CI/CD integration example that blocks PRs if breaking changes exist, using a diff tool (oasdiff) to determine breaking changes and produce a markdown report for PR comments.
When to use it
- Use when you need to detect breaking changes between API spec versions (OpenAPI, GraphQL, Protobuf).
- Use to generate migration guides for developers and to enforce compatibility in CI by blocking breaking changes.
What it can touch
- Tools referenced include: oasdiff (for OpenAPI analysis), and code examples show usage patterns in TypeScript and shell scripts for diff and report generation.
- The CI snippet interacts with GitHub Actions to fetch base specs, run breaking-change checks, and post PR comments.
Caveats
- The provided logic relies on the existence of old and new specs and the presence of a diff tool like oasdiff for breaking-change detection.
- Migration code examples are supplied for a subset of change categories (e.g., required-parameter-added, endpoint-removed); other categories may not have code examples.
- Licensing and usage are described within the skill material; no additional licensing constraints are stated beyond listed license in the repository metadata.
# api-diff-analyzer You are **api-diff-analyzer** - a specialized skill for comparing API specifications and detecting breaking changes, ensuring SDK compatibility and safe API evolution. ## Overview This skill enables AI-powered API diff analysis including: - Comparing OpenAPI spec versions - Categorizing changes by severity - Detecting breaking changes automatically - Generating migration guides - Blocking breaking changes in CI - Supporting multiple spec formats (OpenAPI, GraphQL, gRPC) - Creating detailed change reports ## Prerequisites - OpenAPI, GraphQL, or Protobuf specifications - Version control with spec history - oasdiff, openapi-diff, or similar tools - CI/CD pipeline for automated checks ## Capabilities ### 1. OpenAPI Diff Analysis Compare OpenAPI specifications: ```typescript // src/analyzer/openapi-diff.ts import { parseSpec, diffSpecs } from './parser'; interface ApiChange { type: 'breaking' | 'non-breaking' | 'info'; category: string; path: string; method?: string; description: string; oldValue?: unknown; newValue?: unknown; migration?: string; } interface DiffResult { hasBreakingChanges: boolean; changes: ApiChange[]; summary: { breaking: number; nonBreaking: numb
- Overview
- Prerequisites
- Capabilities
- 1. OpenAPI Diff Analysis
- 2. Breaking Change Categories
- 3. Migration Guide Generation
- 4. CI/CD Integration
- 5. oasdiff CLI Integration
- 6. GraphQL Schema Diff
- 7. Protobuf/gRPC Diff
- MCP Server Integration
- Best Practices
- Process Integration
- Output Format
What does the api-diff-analyzer skill do?
Compare API specifications to detect breaking changes. Compare OpenAPI spec versions, categorize changes by severity, generate migration guides, and block breaking changes in CI.
How do I install it?
Run `npx skills add a5c-ai/babysitter --skill api-diff-analyzer --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From a5c-ai/babysitter, a repository with 1,642 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.