About

Imported from practicalswan/agent-skills (breaking-changes-management/SKILL.md). Install upstream with npx skills add practicalswan/agent-skills --skill breaking-changes-management. Copyright stays with the author.

Breaking Changes Management

Name: breaking-changes-management
Author: practicalswan

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

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

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, 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 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.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/practicalswan-agent-skills-breaking-changes-management/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

practicalswan-agent-skills-breaking-changes-management.ocm.jsonjson

{
  "ocm": "1",
  "id": "practicalswan-agent-skills-breaking-changes-management",
  "kind": "skill",
  "name": "breaking-changes-management",
  "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.",
  "publisher": "practicalswan",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "breaking",
      "changes",
      "management",
      "workflow",
      "quality",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "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."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/practicalswan/agent-skills",
      "path": "breaking-changes-management/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/practicalswan/agent-skills/blob/HEAD/breaking-changes-management/SKILL.md",
      "key": "practicalswan/agent-skills/breaking-changes-management/SKILL.md"
    }
  },
  "instructions": "# Breaking Changes Management\n\nUse this skill when behavior, interfaces, configuration, or compatibility contracts change in a way that can break consumers.\n\n- Leverage native parallel subagent dispatch and 200k+ context windows where available.\n\n\n## Activation Conditions\n\nUse symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.\n\n- Releasing a major version\n- Renaming or removing public APIs\n- Changing request or response shapes\n- Replacing config keys, env vars, CLI flags, or file formats\n- Writing migration notes, deprecation notices, or upgrade ",
  "cost": {
    "context_tokens": 1139
  }
}

Fetch it by URL: GET /api/v1/registry/practicalswan-agent-skills-breaking-changes-management/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.