When to use this
- Reviewing a diff to a library, public API, CLI, or shared config schema before release.
- Deciding whether a change needs a major version bump under semver.
- Not needed for changes fully internal to an application with no external consumers of the changed surface.
The skill file
Copy this verbatim. It's written in the SKILL.md format (YAML frontmatter + markdown instructions) that Claude Code, and increasingly other agent tools, read directly.
--- name: breaking-change-detector description: Check a diff against a package or service's actual public surface (exported functions/types, HTTP/wire contract, CLI flags, config schema) to identify breaking changes, including ones the author didn't flag. Use before releasing a library, API, or CLI change. --- # Breaking Change Detector The dangerous breaking changes are the ones nobody flagged as one. Check the actual public surface mechanically, don't rely on the PR description's self-assessment. ## What counts as breaking - Removing or renaming an exported function, class, type, or public field. - Changing a function's parameter order, adding a required parameter, or changing a parameter/return type in an incompatible way. - Changing an HTTP endpoint's request/response shape, status codes, or removing/renaming a field a client could depend on. - Renaming/removing a CLI flag, or changing its default value's behavior. - Changing a config file's schema in a way that makes previously-valid config invalid, or changes its meaning silently. - Changing behavior that, while not a type-level break, users could reasonably have depended on (e.g. sort order, rounding behavior, error message format that's parsed programmatically). ## What's NOT breaking - Adding a new optional parameter/field with a sensible default. - Adding a new exported symbol. - Internal refactors with no change to the public surface. ## Process 1. Diff the public surface specifically: exported symbols, API routes, CLI flag definitions, config schema -- not the whole file. 2. For each change to that surface, classify: breaking / additive / internal-only. 3. For each breaking change, state exactly what a consumer's code would need to change to keep working. ## Output List of breaking changes with consumer-facing impact and required semver bump (major, per standard semver, for any breaking change); confirm explicitly if none were found.
Installing it elsewhere
The frontmatter/body split above is Claude Code's convention. Here's how to carry the same instructions into other tools:
Save the file below verbatim (frontmatter included) at that path, project-local or in ~/.claude/skills/ for a user-level skill. Claude Code loads the name/description pair to decide when to pull it in, or you invoke it directly as /breaking-change-detector.
Convert the YAML frontmatter to Cursor's rule format (description, globs, alwaysApply: false) and keep the markdown body as the rule content. Cursor surfaces it by description match, same idea as Claude Code's auto-load.
Codex CLI (and increasingly other agentic CLIs) read AGENTS.md at the repo root as always-on instructions. Paste the markdown body under a heading like ## {title}; for GitHub Copilot's coding agent, the equivalent file is .github/copilot-instructions.md.
Append the markdown body to .windsurfrules at the repo root. Windsurf treats the whole file as always-on context, so keep only the instructions you want applied on every request.
- Trusting the PR description's claim of "no breaking changes" without checking the actual public-surface diff.
- Missing a behavioral break that isn't a type signature change (e.g. a changed default, a changed sort order).
- Flagging an additive, backward-compatible change (new optional field) as breaking.