Breaking Changes Management

Name: Breaking Changes Management
Author: practicalswan

practicalswan/agent-skills

13 installs
7 repo stars
Updated August 2, 2026
practicalswan/agent-skills

breaking-changes-management is a Claude Code skill for ai & agent building.

About

breaking-changes-management is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted development.

breaking-changes-management
AI & Agent Building
AI-coding skill

Breaking Changes Management by the numbers

13 all-time installs (skills.sh)
Ranked #11,409 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
Data as of Aug 4, 2026 (Skillselion catalog sync)

npx skills add https://github.com/practicalswan/agent-skills --skill breaking-changes-management

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/practicalswan/agent-skills/breaking-changes-management.svg)](https://skillselion.com/skills/practicalswan/agent-skills/breaking-changes-management)

Installs	13
repo stars	★ 7
Last updated	August 2, 2026
Repository	practicalswan/agent-skills ↗

How do I helps with ai & agent building tasks.?

Helps with ai & agent building tasks.

Who is it for?

Best when you're working on ai & agent building and need structured help with breaking changes management.

Skip if: Teams with no ai & agent building needs, or anyone wanting a generic chat assistant without this specific workflow.

When should I use this skill?

When you need to helps with ai & agent building tasks., or when breaking-changes-management is a claude code skill for ai & agent building.

What you get

Structured output aligned to breaking-changes-management: breaking-changes-management, AI & Agent Building.

Files

SKILL.mdMarkdownGitHub ↗

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

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 - Deprecation wording, timelines, and migration guidance patterns

Scripts

Migration Guide Scaffold - Generate a migration guide skeleton with version, impact, and step sections

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, Codex, and Gemini CLI.

GitHub Copilot: keep the folder in a Copilot-visible skill or plugin path, or wrap the workflow as project instructions if the host does not support portable skill folders directly.
Claude Code: keep the folder in a local skills directory or a compatible plugin or marketplace source.
Codex: install or sync the folder into $CODEX_HOME/skills/<skill-name> and restart Codex after major changes.
Gemini CLI: this repository generates a project command named /skills:breaking-changes-management from this skill. Rebuild commands with python scripts/export-gemini-skill.py breaking-changes-management and then run /commands reload inside Gemini CLI.

MCP Availability And Fallback

Preferred MCP Server: None required

Fallback prompt: "Use the Breaking Changes Management skill without MCP. Rely on the local SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
If the current host does not expose a matching server, use the bundled references, scripts, native toolchain, and manual workflow already described in this skill.
Treat direct local verification, rendered output, logs, tests, or screenshots as the fallback evidence path before completion.

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.

Changelog

[2026-04-25] - Version 1.2 Verification Protocol Refresh

Added

Added a Verification Protocol section with skill-specific pass/fail checks, one pressure-test scenario, and a measurable success metric.
Added guidance to leverage native parallel subagent dispatch and 200k+ context windows where available.

Changed

Updated SKILL.md frontmatter to version: "1.2" and last_updated: 2026-04-25.
Reframed activation guidance toward symptom -> action triggers and standardized two-stage review wording where applicable.

[2026-04-24] - Version 1.1 Refresh

Changed

Updated the SKILL frontmatter version to 1.1 for the 2026-04-24 catalog refresh.

All notable changes to this skill will be documented in this file.

[2026-04-24] - Skill Refresh

Changed

Standardized the SKILL frontmatter with version metadata, last-updated date, tags, and a concise catalog description.
Reformatted the portability and MCP guidance with a preferred server line, a copy-paste fallback prompt, and consistent bullet lists.
Added a catalog-standard Anti-Patterns section and refreshed the Related Skills links at the end of the skill.

[2026-04-04] - Cross-Client Portability Refresh

Changed

Added a standard portability note covering GitHub Copilot, Claude Code, Codex, and Gemini CLI.
Clarified that the core workflow does not require a dedicated MCP server and can run with local tools alone.

Tested

Validated SKILL.md frontmatter, portability sections, and Gemini export readiness with python scripts/validate-skills.py.

[2026-03-09] - Workspace Modernization

Changed

Rewrote the skill into a tighter breaking-change workflow focused on migration impact, replacement paths, and release notes

Added

scripts/migration-guide-scaffold.py to generate migration-guide templates for breaking releases

[2026-02-28] — Description Rewrite & Cross-References

Changed

Rewrote skill description to ~200 characters with clear, specific activation keywords
Improved keyword specificity to reduce overlap with related skills

Added

## Related Skills cross-reference table with 2-4 related skills and "Use When" guidance

MIT License

Copyright (c) 2026 Sithu Win San

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Deprecation Procedures

Deprecation Process

When deprecating features:

1. Add deprecation notice to documentation 2. Update examples to use recommended alternatives 3. Create migration guide if alternative is non-trivial 4. Update CHANGELOG with deprecation notice 5. Set timeline for removal (e.g., "Will be removed in v3.0") 6. In next major version, remove deprecated feature and docs

Deprecation Notice Format

> **⚠️ Deprecated**
>
> This feature is deprecated and will be removed in version X.Y.Z.
> Please use [Alternative Feature](link-to-alt) instead.

Migration Guide Template

## Migration Guide: Change Name

Change introduced in v2.0.0. This guide helps you migrate from v1.x to v2.x.

### What Changed

[Description of what changed and why]

### Before vs After

**Before (v1.x):**
\`\`\`language
oldFunctionCall();
\`\`\`

**After (v2.x):**
\`\`\`language
newFunctionCall();
\`\`\`

### Migration Steps

1. Step one: Description
2. Step two: Description
3. Step three: Description

### Common Issues

**Issue:** Description
**Solution:** How to fix it

### Additional Resources

- [Link to full documentation](url)
- [Link to discussion](url)

Version Management

Deprecation Timeline:

Announce: Document in minor version (e.g., v2.1.0 - "Will be removed in v3.0")
Feature Freeze: In next minor version (e.g., v2.2.0 - stop recommending, encourage migration)
Removal: In major version (e.g., v3.0.0 - remove feature and docs)

Semver Rules:

PATCH (x.Y.Z): Bug fixes, no deprecations
MINOR (x.Y.Z): New features, deprecations allowed
MAJOR (X.Y.Z): Breaking changes, removal of deprecated features

#!/usr/bin/env python3
"""Generate a migration guide skeleton for breaking changes."""

from __future__ import annotations

import argparse
from pathlib import Path


def build_markdown(version: str, title: str, changes: list[str]) -> str:
    bullets = "\n".join(f"- {item}" for item in changes) if changes else "- Describe the breaking change"
    return f"""# {title}

## Summary

- Target version: `{version}`
- Audience: Consumers upgrading from the previous major or minor release

## Breaking Changes

{bullets}

## Before

```text
Document the previous API, configuration, or workflow here.
```

## After

```text
Document the replacement API, configuration, or workflow here.
```

## Upgrade Steps

1. Update dependencies or package versions.
2. Replace removed or renamed APIs.
3. Update configuration keys, environment variables, and scripts.
4. Run tests and smoke checks.

## Validation

- List commands or checks the upgrader should run.

## Rollback Notes

- Describe how to revert if the migration fails.
"""


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--version", required=True, help="Target release version, for example 3.0.0")
    parser.add_argument("--title", default="Migration Guide", help="Document title")
    parser.add_argument(
        "--change",
        action="append",
        default=[],
        help="Breaking change summary. Repeat for multiple items.",
    )
    parser.add_argument("-o", "--output", type=Path, help="Write output to a file instead of stdout")
    args = parser.parse_args()

    markdown = build_markdown(args.version, args.title, args.change)
    if args.output:
        args.output.parent.mkdir(parents=True, exist_ok=True)
        args.output.write_text(markdown, encoding="utf-8")
        print(f"Wrote {args.output}")
    else:
        print(markdown)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())