claude-code_rails-upgrade-skill

Why use it

Key features

Version-aware playbooks (Rails 6 → 7, 7 → 7.1, 7.1 → 7.2, 7.2 → 8)
Deprecation warning sweep + fix suggestions
Framework defaults migration (rails app:update)
Gem compatibility checks against target Rails version
Spring cleaning (Spring removal in newer Rails)
Test-first upgrade: fix tests before cutover

Live Demo

What it looks like in practice

claude-code-rails-upgrade-skill.replay ▶ ready

0/0

Install

Author repository · Claude Skills documentation

Use Cases

Real-world ways to use claude-code_rails-upgrade-skill

How to plan a Rails upgrade before touching code

👤 Rails devs facing a multi-version jump ⏱ ~60 min intermediate

When to use: You're on Rails 6.1 and need to get to 7.2. You want a plan, not a prayer.

Flow

Audit current state

Audit this Rails app: current version, Ruby version, gems, deprecation warnings from a test run.✓ Copied

→ Baseline report
Build the path

Plan the upgrade to Rails 7.2. Go version-by-version (6.1 → 7.0 → 7.1 → 7.2), each with milestone criteria.✓ Copied

→ Multi-stage plan
Identify blockers

Which gems don't have a 7.2-compatible version? Proposals for each (upgrade/replace/fork).✓ Copied

→ Per-gem blocker list

Outcome: A realistic upgrade plan with staged milestones.

Pitfalls

Jumping two major versions at once — Skill enforces one minor/major at a time — don't override

Sweep and fix deprecation warnings

👤 Rails devs mid-upgrade ⏱ ~90 min intermediate

When to use: You're between versions and the test run is a wall of deprecation warnings.

Flow

Collect

Run tests, collect all unique deprecation warnings.✓ Copied

→ Deduped list with file:line occurrences
Group + fix

Group by cause. Propose minimal fixes with diffs for each group.✓ Copied

→ Grouped fix diffs

Outcome: A clean test run ready for the next version bump.

Apply new framework defaults safely

👤 Rails devs navigating rails app:update ⏱ ~60 min advanced

When to use: You've bumped the Gemfile and ran rails app:update; now you have a bunch of new initializers.

Flow

Review diff

Review the diff from rails app:update. Flag any default change that could break our app (strict_loading, zeitwerk mode, etc.).✓ Copied

→ Per-change risk annotation
Staged enable

For each risky default, produce a staged rollout: enable behind env flag, validate on staging, then flip.✓ Copied

→ Staged plan per default

Outcome: Defaults enabled without surprise regressions.

Pitfalls

Enabling all load_defaults at once — Use new_framework_defaults_X.Y.rb to ramp individually

Combinations

Pair with other MCPs for X10 leverage

claude-code-rails-upgrade-skill + claude-code-owasp-skill

Security review on the upgraded code

After upgrade to Rails 7.2, run OWASP review on the auth and params handling.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
Audit	repo	Start of every upgrade	Claude tokens
Plan upgrade path	current, target	After audit	Claude tokens
Gem compat check	Gemfile, target Rails	Before bumping	Claude tokens + RubyGems API
Deprecation sweep	test log	Between versions	Claude tokens
Framework defaults migration	diff from rails app:update	After rails app:update	Claude tokens

Cost & Limits

What this costs to run

API quota: None
Tokens per call: 20-80k across an upgrade
Monetary: Free
Tip: Run deprecation sweeps on specific directories rather than the whole app at once.

Security

Permissions, secrets, blast radius

Credential storage: No credentials

Data egress: Code sent to Claude for inference

Always upgrade on a branch. Don't let Claude run destructive commands (db:migrate, bundle update) without explicit confirmation.

Troubleshooting

Common errors and fixes

rails app:update produces uncommitted binary files

These are usually system files. Gitignore them and regenerate cleanly.

Tests pass locally, fail in CI after upgrade

Likely autoloading differences or eager_load in production mode. Run with RAILS_ENV=production locally.

Gem bundle resolution fails

Skill will suggest alternative gem versions; sometimes a fork or replacement is required.

Verify: bundle update --conservative

Alternatives