bg-szy/TOP-SKILLS / skills/agent-skills/breaking-changes-management
breaking-changes-management
VerifiedManage breaking API changes, migration guides, deprecation notices, and semver versioning. Use when introducing breaking changes, writing migration paths, updating changelogs, or releasing major versions.
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 6.2 KB |
| LICENSE.txt | markdown | 1.1 KB |
| SKILL.md | skill md | 4.7 KB |
SKILL.md
View on GitHub---
name: breaking-changes-management
version: "2.0"
last_updated: 2026-09-08
tags: [breaking, changes, management, workflow, quality]
description: "Manage breaking API changes, migration guides, deprecation notices, and semver versioning. Use when introducing breaking changes, writing migration paths, updating changelogs, or releasing major versions."
---
# Breaking Changes Management
Use this skill when behavior, interfaces, configuration, or compatibility contracts change in a way that can break consumers.
- Leverage native parallel subagent dispatch and 200k+ context windows where available.
## Activation Conditions
Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.
- Releasing a major version
- Renaming or removing public APIs
- Changing request or response shapes
- Replacing config keys, env vars, CLI flags, or file formats
- Writing migration notes, deprecation notices, or upgrade checklists
## Workflow
1. Identify the exact consumer-visible break.
2. State who is affected and from which version.
3. Provide the replacement path or mitigation.
4. Add before/after examples.
5. Update `CHANGELOG.md` and any setup or usage docs that changed.
## Required Outputs
- Changelog entry with a clear `BREAKING` label
- Migration guide with old usage, new usage, and upgrade steps
- Deprecation timeline if removal is delayed
- Validation notes for any examples or scripts that changed
<!-- MCP:START -->
<!-- PORTABILITY:START -->
## Cross-Client Portability
This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.
- GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the
workflow in project instructions when folder discovery is unavailable.
- Claude Code: keep the folder in a local skills directory or a compatible plugin source.
- Codex: install or sync the folder into
`$CODEX_HOME/skills/breaking-changes-management` and restart Codex after major changes.
<!-- PORTABILITY:END -->
## MCP Availability And Fallback
Preferred MCP Server: None required
- Fallback prompt: "Use the Breaking Changes Management skill without MCP. Rely on its local instructions, bundled resources, standard shell or editor tools, and direct verification. Show the evidence used before concluding."
- Do not claim an MCP operation was used when the active host does not expose it.
- Treat local files, tests, rendered outputs, logs, or screenshots as the fallback evidence path.
<!-- MCP:END -->
## Anti-Patterns
- Starting work before the plan or gate is clear: Execution drifts when success criteria are implied instead of explicit.
- Treating verification as optional cleanup: The last mile is where regressions and missing updates are usually hiding.
- Mixing planning, implementation, and release work in one jump: You lose the causal chain that explains why a change is safe.
## Verification Protocol
Before claiming "skill applied successfully":
1. Pass/fail: The Breaking Changes Management workflow starts from explicit success criteria, constraints, and stop conditions.
2. Pass/fail: Required evidence is collected before any completion, approval, or readiness claim.
3. Pass/fail: The next action follows the documented gate order without skipping review or verification steps.
4. Pressure-test scenario: Apply the workflow under time pressure with one failing check and one tempting shortcut.
5. Success metric: Zero rationalizations; blocked, failed, or unverified work is reported as such.
## Migration Checklist
- [ ] Old behavior described precisely
- [ ] New behavior described precisely
- [ ] Replacement path documented
- [ ] Upgrade steps ordered and testable
- [ ] Rollback or compatibility notes included
- [ ] README/setup docs updated if user-facing behavior changed
## References & Resources
### Documentation
- [Deprecation Procedures](./references/deprecation.md) - Deprecation wording, timelines, and migration guidance patterns
### Scripts
- [Migration Guide Scaffold](./scripts/migration-guide-scaffold.py) - Generate a migration guide skeleton with version, impact, and step sections
## Related Skills
- [development-workflow](../development-workflow/SKILL.md): Use it when the workflow also needs planning, quality gates, and delivery tracking.
- [code-quality](../code-quality/SKILL.md): Use it when the workflow also needs two-stage review (spec compliance first, then code quality), maintainability, and refactoring guidance.
- [systematic-debugging](../systematic-debugging/SKILL.md): Use it when the workflow also needs root-cause debugging before proposing fixes.
- [test-driven-development](../test-driven-development/SKILL.md): Use it when the workflow also needs test-first implementation and regression safety.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |