056-design-avoid-breaking-changes — Claude Code skill
056-design-avoid-breaking-changes reviews plans, OpenSpec changes, and APIs for breaking changes and migration risks before release.
Apache-2.0 172 installs ★ 465 updated 2026-10-21
npx skills add jabrena/plinth --skill 056-design-avoid-breaking-changes -a claude-codeWhat 056-design-avoid-breaking-changes does
Part of the Plinth Toolkit, this interactive skill evaluates proposed repository modifications before they ship. It scans command definitions, skill routing triggers, generated files, XML sources, data schemas, and CI expectations. By default, the workflow remains strictly read-only, preventing unexpected file mutations during analysis.
The review workflow mandates reading references/056-design-avoid-breaking-changes.md before processing any surfaces. Each flagged issue receives a concrete classification: BREAKING, POTENTIALLY BREAKING, NON-BREAKING, or UNKNOWN. Missing the reference document stalls execution, so keep that path accessible.
At the end of the run, the agent delivers a structured summary with severity-ordered findings. If changes inherently break existing contracts, the report includes guidance for deprecation periods, release notes, and targeted validation checks.
What it helps with
- detect breaking changes across specifications and OpenSpec plans
- audit command and skill routing compatibility before deployment
- evaluate migration risks in API schemas and runtime configuration
- generate deprecation and release guidance for intentional breaking changes
Example prompts for the agent
- Review breaking changes in this spec
- Check compatibility risks in this OpenSpec change
- Assess command and skill compatibility before release
How to install 056-design-avoid-breaking-changes
1Skills CLI (Vercel)
npx skills add jabrena/plinth --skill 056-design-avoid-breaking-changes -a claude-code2Manually: put the files in place
~/.claude/skills/056-design-avoid-breaking-changes/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/056-design-avoid-breaking-changes/
1Skills CLI (Vercel)
npx skills add jabrena/plinth --skill 056-design-avoid-breaking-changes -a codex2Manually: put the files in place
.agents/skills/056-design-avoid-breaking-changes/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add jabrena/plinth --skill 056-design-avoid-breaking-changes -a cursor2Manually: put the files in place
.cursor/skills/056-design-avoid-breaking-changes/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install jabrena/plinth skills/056-design-avoid-breaking-changes2Manually: put the files in place
.github/skills/056-design-avoid-breaking-changes/SKILL.md1Skills CLI (Vercel)
npx skills add jabrena/plinth --skill 056-design-avoid-breaking-changes -a gemini-cli2Platform CLI
gemini skills install https://github.com/jabrena/plinth --path skills/056-design-avoid-breaking-changesManually: put the files in place
.devin/skills/056-design-avoid-breaking-changes/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add jabrena/plinth --skill 056-design-avoid-breaking-changes -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about 056-design-avoid-breaking-changes
How to install 056-design-avoid-breaking-changes in Claude Code?
Run npx skills add jabrena/plinth --skill 056-design-avoid-breaking-changes -a claude-code in your terminal.
What does 056-design-avoid-breaking-changes do?
It performs a read-only compatibility review across commands, skills, APIs, schemas, and generated files to highlight breaking risks before releases.
Will this skill modify my source code?
No, it operates purely in read-only mode and avoids editing plans or files unless you specifically ask for implementation.
Source text
SKILL.md · Apache-2.0
--- name: 056-design-avoid-breaking-changes description: Use when you need to review a plan, OpenSpec change, specification, or implementation proposal for breaking-change risk across commands, skills, generated outputs, XML sources, README/docs, tests, CI, APIs, schemas, configuration, data, migration, and release guidance. This should trigger for requests such as Review breaking changes in this spec; Check compatibility risks; Avoid breaking changes in this OpenSpec change; Review migration impact before release; Assess command and skill compatibility. Part of Plinth Toolkit license: Apache-2.0 metadata: author: Juan Antonio Breña Moral version: 0.19.0 --- # Avoid Breaking Changes Review planned repository changes for breaking-change and compatibility risk before implementation or release promotion. **This is an interactive SKILL**. **What is covered in this Skill?** - Command contract compatibility: names, inputs, owning agents, outputs, safeguards, installer registration, and command inventories - Skill routing compatibility: identifiers, metadata, descriptions, triggers, references, generated local output, and acceptance coverage - Generated-output ownership: XML/source files versus `.agents/skills`, public `skills/`, `.cursor/commands`, `.cursor/rules`, and `docs/` - Source and generator contracts: XML, XInclude, XSLT, Maven modules, schema expectations, and module validation - README, localized README, changelog, migration, and deprecation guidance - External and runtime contracts: APIs, schemas, data formats, configuration keys, persistence, CLI behavior, and CI expectations - Structured compatibility reports with severity-ranked findings and validation guidance ## Constraints Keep the review evidence-based, read-only, and scoped to compatibility risk unless the user explicitly asks for implementation. - **MUST** read `references/056-design-avoid-breaking-changes.md` before producing compatibility guidance - **MUST** identify the source artifacts reviewed and the compatibility surfaces considered - **MUST** distinguish confirmed breaking changes, potential risks, non-breaking changes, and unknowns that need maintainer decision - **MUST** include migration, deprecation, validation, or release-note guidance for intentional breaking changes - **MUST** respect repository source ownership: edit XML and source docs, regenerate generated output through documented workflows, and avoid direct generated-output edits unless the repository explicitly owns that file - **MUST NOT** modify plans, specs, source files, generated outputs, or issue descriptions during review unless the user explicitly requests implementation ## When to use this skill - Review breaking changes in this spec - Check compatibility risks - Avoid breaking changes in this OpenSpec change - Review migration impact before release - Assess command and skill compatibility - Find generated output compatibility risks - Review API schema configuration or data contract changes ## Workflow 1. **Read the compatibility reference** Read `references/056-design-avoid-breaking-changes.md`, then identify the source artifacts to review, their authority, and whether the request is read-only review or approved implementation. 2. **Inventory compatibility surfaces** Check commands, skills, generated outputs, XML/source ownership, README/docs, tests, CI/build gates, external contracts, runtime behavior, data/configuration contracts, and release or migration guidance relevant to the proposed change. 3. **Classify findings** Classify each finding as `BREAKING`, `POTENTIALLY BREAKING`, `NON-BREAKING`, or `UNKNOWN`. Include the affected users, artifacts, contracts, and validation evidence or missing evidence. 4. **Recommend migration and validation** For each confirmed or potential risk, recommend deprecation, compatibility windows, migration notes, release-note updates, generator checks, focused tests, or owner decisions. 5. **Report the review outcome** Produce a concise compatibility report with reviewed sources, risk summary by surface, severity-ranked findings, recommended validation, and a clear no-risk statement when no breaking-change risks are found. ## Reference For detailed guidance, examples, and constraints, see [references/056-design-avoid-breaking-changes.md](references/056-design-avoid-breaking-changes.md).
© Juan Antonio Breña Moral · Apache-2.0 · jabrena/plinth