New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Breaking Change Analysis

by ruby-git in ruby-git/ruby-git

Assesses what an API change would break before it is made, finds every usage, documents the impact and plans a deprecation or migration path.

MITAuto-check passedDevelopment

Install Breaking Change Analysis

skills CLI
$ npx skills add ruby-git/ruby-git --skill breaking-change-analysis -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ruby-git/ruby-git breaking-change-analysis --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/ruby-git/ruby-git.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.github/skills/breaking-change-analysis .claude/skills/breaking-change-analysis && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
breaking-change-analysis
GitHub stars
1.8k
Token cost
~1.7k tokens
SKILL.md length
803 words
Files
2
Skills in repo
30
Repo updated
First seen
Licence
MIT

At a glance

Assesses what an API change would break before it is made, finds every usage, documents the impact and plans a deprecation or migration path.

  • Works in 4 steps: Identify the Change Scope → Find All Usages → Assess and Document Impact → …
  • Planning to remove or rename a public method
  • SKILL.md covers Contents, How to use this skill, Related skills and Step 1: Identify the Change…, plus 3 more sections
  • Calls gh

What it does

Used before removing a method, changing a signature, altering a return type or value, changing an exception type or modifying default behavior, and meant to be attached to a Copilot Chat context and invoked with the specific change under consideration. The workflow has four steps: identify the change scope, find all usages, assess and document impact, and apply the deprecation policy. Scope means finding the affected classes and methods and checking whether they are public or private in the YARD docs and whether the `Git::Repository` facade layer is involved.

Usage search covers internal call sites with grep over `lib/` and `spec/`, external code with `gh search code`, and downstream gems through `reverse-dependencies.sql`. That query lists every gem depending on `git`, one row each, with its latest version and release date, the version requirement it declares and its source URL, newest release first. Its filter picks the requirements that a new major would hit, `~> 4.%` pins and open-ended `>=` requirements, and must be edited to match the series being changed. A section on proving the safety claim and a related development-workflow skill for TDD implementation round it out.

When your agent uses it

  • Planning to remove or rename a public method
  • Changing a method signature, return value or exception type
  • Finding which downstream gems would be affected by a major release
  • Writing a deprecation plan before a breaking release

Example prompts

  • “I want to remove the legacy checkout helper; assess what would break and how to deprecate it.”
  • “Check the impact of changing this method to return an array instead of a hash.”
  • “List the downstream gems that would be hit by a new major version.”
  • “Find every internal and external usage of the clone method before I change its arguments.”

Requirements

  • grep for searching the codebase
  • The `gh` CLI for external code search

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. Identify the Change Scope
  2. Find All Usages
  3. Assess and Document Impact
  4. Deprecation policy

What it can do on your machine

Read from SKILL.md and the folder at commit f3bf20f. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • gh

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • rubygems.org

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Breaking Change Analysis loads about 1.7k tokens when it runs. Until then it costs about 57 tokens; SKILL.md has 803 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~57
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from ruby-git/ruby-git at commit f3bf20f, republished under its MIT licence (© ruby-git). 803 words, ~1,730 tokens.

Download SKILL.mdSave it as .claude/skills/breaking-change-analysis/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
breaking-change-analysis
description
Assesses the impact of API changes before implementation to understand what code would break and plan appropriate migration paths. Use when removing methods, changing interfaces, or planning deprecations.

Breaking Change Analysis Workflow

Assess the impact of API changes before implementation. Use when removing methods, changing method signatures, altering return types/values, changing exception types, or modifying default behavior.

Contents

How to use this skill

Attach this file to your Copilot Chat context, then invoke it with the specific API/method change you are considering. Use this workflow before coding to assess impact and plan migration.

Step 1: Identify the Change Scope

  1. Determine which classes and methods are affected.
  2. Check API visibility (@api public vs @api private in YARD docs).
  3. Check if the change affects Git::Repository (the current facade layer, modules under lib/git/repository/).

Step 2: Find All Usages

  1. Internal usages:

    bash
    grep -rn "method_name" lib/ spec/

  2. External usage (if applicable):

    bash
    gh search code "Git::Repository#method_name language:ruby"

  3. Downstream gems: reverse-dependencies.sql in this directory lists every gem that depends on git, one row per gem, showing only its most recent version.

    Code search finds call sites; this finds the projects that would have to react to a release. Each row gives the dependent gem's name, its latest version and release date, the version requirement it declares against git, and its source or homepage URL. The results are ordered newest release first, so gems still under active maintenance — the ones a deprecation notice can actually reach — sort to the top.

    The WHERE clause selects the requirements that a new major would affect: ~> 4.% pins, which stop receiving updates, and open-ended >= requirements, which pick up the new major immediately whether or not the gem is ready for it. Edit those patterns to match the series you are changing — they are pinned to the v4.x analysis they were written for.

    Run it against a restored copy of the public RubyGems.org database dump (https://rubygems.org/pages/data); the table names are that schema's.

Step 3: Assess and Document Impact

Produce an impact assessment:

markdown
## Breaking Change Impact Assessment

### Change Description
[What is being changed]

### Affected API
- Class: `Git::SomeClass`
- Method: `#some_method`
- Current signature: `def some_method(arg, opts = {})`
- Proposed signature: `def some_method(arg, force: false)`

### Internal Impact
- Files affected: X
- Tests to update: Y

### External Impact
- Severity: [High/Medium/Low]
- Migration difficulty: [Easy/Medium/Hard]

### Safety Proof
[The single fact each "safe" verdict rests on, and the code that was run to prove it]

### Migration Path
[How users should update their code]
Prove the safety claim

Every "this looks risky but is actually safe" verdict in the assessment rests on some single fact — an option no caller passes, output no parser depends on, behavior identical across the supported git range. Isolate that fact, then prove it by running real code: a spec exercising the old and new behavior, a console session against a fixture repository, or a query against the RubyGems dump showing no dependent gem is affected. Record the fact and its proof in the Safety Proof section of the assessment. A safety claim backed only by reasoning is an open question, not a finding — the step is complete when every such claim names its fact and the code that proved it. This proof applies to hard breaks and behavior changes that have no deprecation path. A change to the class of a raised exception is such a behavior change unless it passes the rescue-compatibility test in Branch & PR Strategy. The deprecation policy in Step 4 governs removal of a deprecated API.

Show full SKILL.md (293 more words)Show less

Step 4: Deprecation policy

Removal gate. A removal PR merges to main only when its deprecation warning and UPGRADING.md entry are contained in a previous normal release. Once any removal has merged to main, main becomes the release line for the next major version. If another release of the previous major is needed, it is cut from a branch created for that major (e.g. 4.x or 5.x). "Normal release" is semver's term for a non-pre-release version.

The gate sets the earliest major a removal may land in, not the one it must land in. A removal may land in any major after the gate is met; which one is a roadmap decision recorded on the API's issue.

What a deprecation ships. All of the following land in the same minor release:

  • A runtime warning via Git::Deprecation.warn that names the replacement. A YARD tag alone does not count. Do not use ActiveSupport's deprecate_methods; it bakes the horizon into the message.
  • The replacement API.
  • An UPGRADING.md entry that agrees with the warning.
  • A @deprecated YARD tag with migration guidance.

Warning wording. When the removing major is decided:

ruby
Git::Deprecation.warn(
  'Git::Author is deprecated and will be removed in v6.0.0. Use Git::AuthorInfo instead.'
)

When it is not yet decided:

ruby
Git::Deprecation.warn(
  'Git::Author is deprecated and will be removed in a future major release. ' \
  'Use Git::AuthorInfo instead.'
)

Deciding or changing the named major later is a documentation change that ships in a minor. Update the warning, the YARD tag, and the UPGRADING.md entry together.

When to deprecate. Add a warning only when removal in a future major is intended. An API that will be kept but discouraged is documented as legacy with no warning; the hollow shells in ADR-0002 are the precedent. Removing a warning (un-deprecating) is a non-breaking change.

ADR-0007 records the decision and its rationale.

Commit requirements:

  • Mark removal commits with ! and include a BREAKING CHANGE: footer
  • DO NOT update CHANGELOG.md — it is auto-generated from commit messages

© ruby-git, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in .github/skills/breaking-change-analysis of ruby-git/ruby-git.

  • SKILL.md
  • reverse-dependencies.sql

Open the folder on GitHubat commit f3bf20f

Compare with similar skills

Breaking Change Analysis next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Breaking Change Analysis compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Breaking Change Analysis this skillruby-git/ruby-git1.8k—~1.7kAutomated safety check: PassMIT
OBS Plugin Dependency Upgradesorayuki/obs-multi-rtmp5.1k—~609Automated safety check: PassGPL-2.0
CLIProxy Core Synccaidaoli/ccLoad417—~1.5kAutomated safety check: PassMIT
ONNX Opset Bump Checklistmicrosoft/onnxruntime22k—~12kAutomated safety check: PassMIT
Rigor Add Referencerigortype/rigor106—~2.1kAutomated safety check: PassMPL-2.0
PR Bumpakitaonrails/my-skills211—~2.7kAutomated safety check: PassNone

Similar skills

  • OBS Plugin Dependency Upgrade

    sorayuki/obs-multi-rtmp

    Updates the obs-multi-rtmp plugin repo to the latest upstream plugin template and OBS Studio version, including dependency metadata, then rebuilds it with CMake.

    5.1k GitHub stars~609 tokensUpdated 5 days ago
    DevelopmentAuto-check passed

  • CLIProxy Core Sync

    caidaoli/ccLoad

    Syncs or audits ccLoad's CLIProxyAPI protocol-conversion core and registered provider adapters against one pinned upstream commit, then verifies the result.

    417 GitHub stars~1.5k tokensUpdated today
    DevelopmentAuto-check passed

  • ONNX Opset Bump Checklist

    microsoft/onnxruntime

    Official

    A checklist for upgrading the pinned ONNX version and opset in ONNX Runtime, covering the files to change, archive hashes, patch rebasing and release-candidate handling.

    22k GitHub stars~12k tokensUpdated today
    DevelopmentAuto-check passed

  • Rigor Add Reference

    rigortype/rigor

    Add or repair a read-only upstream submodule under references/.

    106 GitHub stars~2.1k tokensUpdated 5 days ago
    DevelopmentAuto-check passed

  • PR Bump

    akitaonrails/my-skills

    Merge Dependabot / dependency-bot bump PRs quickly and safely.

    211 GitHub stars~2.7k tokensUpdated 14 days ago
    DevelopmentAuto-check passed

  • Laravel Package Major Upgrade

    mailcarrierapp/mailcarrier

    Adds support for a new Laravel major to a package by extending composer.json constraints for illuminate, Testbench and Pest and the CI test matrix.

    164 GitHub stars~1.1k tokensUpdated 2 mo ago
    DevelopmentAuto-check passed

More from ruby-git/ruby-git

All 30 skills in this repo

  • Address PR Feedback for ruby-git

    ruby-git/ruby-git

    Addresses unresolved pull request review threads and suppressed (low-confidence) Copilot review comments on the current branch, folds each fix into the…

    1.8k GitHub stars~657 tokensUpdated 5 days ago
    Auto-check passed

  • CI/CD Failure Troubleshooting

    ruby-git/ruby-git

    Diagnoses and fixes failing GitHub Actions runs by identifying the failure, fetching only the relevant logs, finding the root cause and reproducing it locally.

    1.8k GitHub stars~1.9k tokensUpdated 5 days ago
    Auto-check passed

  • Git Command Class Implementation

    ruby-git/ruby-git

    Scaffolds and reviews `Git::Commands::*` classes in the ruby-git library, with unit tests, integration tests and YARD docs, using the Base command architecture.

    1.8k GitHub stars~3k tokensUpdated 5 days ago
    Auto-check passed

  • Gem Dependency Management

    ruby-git/ruby-git

    Workflow for updating gem dependencies and fixing CVEs in the ruby-git project: assess with bundle outdated and audit, edit the gemspec, test, then commit with conventional messages.

    1.8k GitHub stars~806 tokensUpdated 5 days ago
    Auto-check passed

  • Extract Command from Git::Lib

    ruby-git/ruby-git

    Migrates a direct command call in Ruby Git's Git::Lib to a Git::Commands class, as part of a Strangler Fig redesign, with a plan, legacy tests and a pull request.

    1.8k GitHub stars~4.4k tokensUpdated 5 days ago
    Auto-check passed

  • Git::Repository Facade Methods

    ruby-git/ruby-git

    Scaffolds and reviews facade methods on Git::Repository in ruby-git, with unit tests, integration tests and YARD documentation.

    1.8k GitHub stars~3.4k tokensUpdated 5 days ago
    Auto-check passed

Works with

Categories

Questions about Breaking Change Analysis

What does Breaking Change Analysis do?

Assesses what an API change would break before it is made, finds every usage, documents the impact and plans a deprecation or migration path. Used before removing a method, changing a signature, altering a return type or value, changing an exception type or modifying default behavior, and meant to be attached to a Copilot Chat context and invoked with the specific change under consideration. The workflow has four steps: identify the change scope, find all usages, assess and document impact, and apply the deprecation policy.

When should I use Breaking Change Analysis?

Breaking Change Analysis fits situations like: planning to remove or rename a public method; changing a method signature, return value or exception type; finding which downstream gems would be affected by a major release; writing a deprecation plan before a breaking release.

How do I install Breaking Change Analysis in Claude Code?

Run `npx skills add ruby-git/ruby-git --skill breaking-change-analysis -a claude-code`. Or copy the skill folder (.github/skills/breaking-change-analysis in ruby-git/ruby-git) into .claude/skills/breaking-change-analysis in your project. Claude Code loads it when a task matches its description.

How do I install Breaking Change Analysis in Codex?

Run `npx skills add ruby-git/ruby-git --skill breaking-change-analysis -a codex`. Or copy the skill folder (.github/skills/breaking-change-analysis in ruby-git/ruby-git) into .agents/skills/breaking-change-analysis in your project. Codex loads it when a task matches its description.

Can I use Breaking Change Analysis in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ruby-git/ruby-git --skill breaking-change-analysis -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/breaking-change-analysis, .gemini/skills/breaking-change-analysis, .github/skills/breaking-change-analysis and .opencode/skills/breaking-change-analysis in your project.

What does Breaking Change Analysis need to run?

Going by SKILL.md and its folder, Breaking Change Analysis needs the command-line tools its instructions call (gh). Our summary lists: grep for searching the codebase; The `gh` CLI for external code search.

Does Breaking Change Analysis access the network?

SKILL.md names 1 domain. As links in the text: rubygems.org. This is read from the text; nothing was executed.

Is Breaking Change Analysis safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Breaking Change Analysis use?

Breaking Change Analysis is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Breaking Change Analysis use?

About 1.7k tokens (SKILL.md is roughly 6.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Breaking Change Analysis?

Skills that share tags, products or a category with Breaking Change Analysis: OBS Plugin Dependency Upgrade (sorayuki/obs-multi-rtmp, 5.1k stars), CLIProxy Core Sync (caidaoli/ccLoad, 417 stars), ONNX Opset Bump Checklist (microsoft/onnxruntime, 22k stars) and Rigor Add Reference (rigortype/rigor, 106 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Breaking Change Analysis?

ruby-git (a GitHub organization) maintains it in ruby-git/ruby-git, which has 1,799 GitHub stars. The repository holds 30 skills in this directory. The repository was last updated on October 2, 2026.

Source: ruby-git/ruby-git on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.