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
- Identify the exact consumer-visible break.
- State who is affected and from which version.
- Provide the replacement path or mitigation.
- Add before/after examples.
- 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
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.
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.
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":
- Pass/fail: The Breaking Changes Management workflow starts from explicit success criteria, constraints, and stop conditions.
- Pass/fail: Required evidence is collected before any completion, approval, or readiness claim.
- Pass/fail: The next action follows the documented gate order without skipping review or verification steps.
- Pressure-test scenario: Apply the workflow under time pressure with one failing check and one tempting shortcut.
- Success metric: Zero rationalizations; blocked, failed, or unverified work is reported as such.
Migration Checklist
References & Resources
Documentation
Scripts
Related Skills
- development-workflow: Use it when the workflow also needs planning, quality gates, and delivery tracking.
- code-quality: Use it when the workflow also needs two-stage review (spec compliance first, then code quality), maintainability, and refactoring guidance.
- systematic-debugging: Use it when the workflow also needs root-cause debugging before proposing fixes.
- test-driven-development: Use it when the workflow also needs test-first implementation and regression safety.
1---
2name: breaking-changes-management
3version: "2.0"
4last_updated: 2026-09-08
5tags: [breaking, changes, management, workflow, quality]
6description: "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."
7metadata:
8 source: https://skillmd.com/skills/practicalswan/breaking-changes-management
9---
10
11# Breaking Changes Management
12
13Use this skill when behavior, interfaces, configuration, or compatibility contracts change in a way that can break consumers.
14
15- Leverage native parallel subagent dispatch and 200k+ context windows where available.
16
17
18## Activation Conditions
19
20Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.
21
22- Releasing a major version
23- Renaming or removing public APIs
24- Changing request or response shapes
25- Replacing config keys, env vars, CLI flags, or file formats
26- Writing migration notes, deprecation notices, or upgrade checklists
27
28## Workflow
29
301. Identify the exact consumer-visible break.
312. State who is affected and from which version.
323. Provide the replacement path or mitigation.
334. Add before/after examples.
345. Update `CHANGELOG.md` and any setup or usage docs that changed.
35
36## Required Outputs
37
38- Changelog entry with a clear `BREAKING` label
39- Migration guide with old usage, new usage, and upgrade steps
40- Deprecation timeline if removal is delayed
41- Validation notes for any examples or scripts that changed
42
43<!-- MCP:START -->
44
45<!-- PORTABILITY:START -->
46## Cross-Client Portability
47
48This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.
49
50- GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the
51 workflow in project instructions when folder discovery is unavailable.
52- Claude Code: keep the folder in a local skills directory or a compatible plugin source.
53- Codex: install or sync the folder into
54 `$CODEX_HOME/skills/breaking-changes-management` and restart Codex after major changes.
55
56<!-- PORTABILITY:END -->
57
58## MCP Availability And Fallback
59
60Preferred MCP Server: None required
61
62- 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."
63- Do not claim an MCP operation was used when the active host does not expose it.
64- Treat local files, tests, rendered outputs, logs, or screenshots as the fallback evidence path.
65
66<!-- MCP:END -->
67
68## Anti-Patterns
69
70- Starting work before the plan or gate is clear: Execution drifts when success criteria are implied instead of explicit.
71- Treating verification as optional cleanup: The last mile is where regressions and missing updates are usually hiding.
72- Mixing planning, implementation, and release work in one jump: You lose the causal chain that explains why a change is safe.
73
74## Verification Protocol
75
76Before claiming "skill applied successfully":
77
781. Pass/fail: The Breaking Changes Management workflow starts from explicit success criteria, constraints, and stop conditions.
792. Pass/fail: Required evidence is collected before any completion, approval, or readiness claim.
803. Pass/fail: The next action follows the documented gate order without skipping review or verification steps.
814. Pressure-test scenario: Apply the workflow under time pressure with one failing check and one tempting shortcut.
825. Success metric: Zero rationalizations; blocked, failed, or unverified work is reported as such.
83
84## Migration Checklist
85
86- [ ] Old behavior described precisely
87- [ ] New behavior described precisely
88- [ ] Replacement path documented
89- [ ] Upgrade steps ordered and testable
90- [ ] Rollback or compatibility notes included
91- [ ] README/setup docs updated if user-facing behavior changed
92
93## References & Resources
94
95### Documentation
96- [Deprecation Procedures](./references/deprecation.md) - Deprecation wording, timelines, and migration guidance patterns
97
98### Scripts
99- [Migration Guide Scaffold](./scripts/migration-guide-scaffold.py) - Generate a migration guide skeleton with version, impact, and step sections
100
101## Related Skills
102
103- [development-workflow](../development-workflow/SKILL.md): Use it when the workflow also needs planning, quality gates, and delivery tracking.
104- [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.
105- [systematic-debugging](../systematic-debugging/SKILL.md): Use it when the workflow also needs root-cause debugging before proposing fixes.
106- [test-driven-development](../test-driven-development/SKILL.md): Use it when the workflow also needs test-first implementation and regression safety.