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