rails-upgrade

Rails Upgrade Assistant Skill

A Claude Code skill that helps you upgrade Ruby on Rails applications from version 2.3 through 8.1.

What Does This Skill Do?

The Rails Upgrade Assistant analyzes your Rails application and generates:

• Comprehensive Upgrade Reports - Detailed migration guides with OLD vs NEW code examples from your actual codebase
• app:update Previews - Shows exactly what configuration files will change when you run rails app:update

The skill follows a sequential upgrade strategy—you upgrade one minor/major version at a time (e.g., 5.2 → 6.0 → 6.1 → 7.0), never skipping versions.

Why Trust This Skill?

This skill is built on real-world experience, not just documentation:

• 60,000+ developer hours of Rails upgrade experience
• Upgrades from Rails 2.3 to Rails 8.1 for clients worldwide
• Based on the methodology documented in "The Complete Guide to Upgrade Rails" ebook
• Created by the team at FastRuby.io, specialists in Rails upgrades since 2017

We've encountered (and solved) edge cases that don't appear in any documentation. This skill encapsulates that hard-won knowledge.

How to Use This Skill

Installation

This skill depends on two companion skills: rails-load-defaults and dual-boot. A fourth sibling plugin, upgrade-cleanup, lives in this repo and runs the post-upgrade scaffolding teardown. The marketplace install handles all four.

From inside the Claude Code CLI prompt (recommended):

/plugin marketplace add ombulabs/claude-skills
/plugin install rails-upgrade@ombulabs-ai
/plugin install rails-load-defaults@ombulabs-ai
/plugin install dual-boot@ombulabs-ai
/plugin install upgrade-cleanup@ombulabs-ai

From your terminal:

claude plugin marketplace add https://github.com/ombulabs/claude-skills.git
claude plugin install rails-upgrade@ombulabs-ai
claude plugin install rails-load-defaults@ombulabs-ai
claude plugin install dual-boot@ombulabs-ai
claude plugin install upgrade-cleanup@ombulabs-ai

Manual install:

# 1. This skill
git clone https://github.com/ombulabs/claude-code_rails-upgrade-skill.git
cp -r claude-code_rails-upgrade-skill/rails-upgrade ~/.claude/skills/

# 2. upgrade-cleanup (sibling plugin, same repo)
cp -r claude-code_rails-upgrade-skill/upgrade-cleanup ~/.claude/skills/

# 3. rails-load-defaults (dependency)
git clone https://github.com/ombulabs/claude-code_rails-load-defaults-skill.git
cp -r claude-code_rails-load-defaults-skill/rails-load-defaults ~/.claude/skills/

# 4. dual-boot (dependency)
git clone https://github.com/ombulabs/claude-code_dual-boot-skill.git
cp -r claude-code_dual-boot-skill/dual-boot ~/.claude/skills/

Basic Usage

In Claude Code, navigate to your Rails application directory and use natural language:

"Upgrade my Rails app to 7.2"
"Help me upgrade from Rails 6.1 to 7.0"
"What breaking changes are in Rails 8.0?"

Workflow

1. Ask for an upgrade → Claude generates detailed reports based on your actual code
2. Implement the changes → Follow the step-by-step migration plan

Available Commands

Design Decisions & Best Practices

This skill implements the FastRuby.io upgrade methodology, which includes:

Dual-Boot Strategy

Run your application with two versions of Rails simultaneously using the next_rails gem. This allows you to test both versions during the transition and deploy backwards-compatible changes before the version bump.

See the dual-boot skill for setup, code patterns, and CI configuration.

Post-Upgrade Cleanup

Once a hop is finished (or abandoned), the upgrade-cleanup sibling plugin tears down the dual-boot scaffolding so the tree stops carrying two Rails versions in parallel. It is scoped tightly to scaffolding removal, not a kitchen-sink "finish the upgrade" pass.

Activate it with phrases like "finish the upgrade", "clean up dual-boot", or "abandon this upgrade". The workflow:

1. Phase 0 - Pre-flight. Detects Docker vs local, smoke-checks bundle / bin/rails runner on both sides, and asks whether to keep the next version (finishing) or the current version (abandoning / pausing the hop).
2. Phase 1 - Dual-boot removal. Drops NextRails.next? / NextRails.current? branches, strips the next? Gemfile method and conditional groups, sweeps for deprecation_tracker residue before removing next_rails (the gem ships DeprecationTracker; leftover requires break test boot), swaps lockfiles, and updates CI to drop the dual-boot job.
3. Phase 2 - Old-version code retirement. Monkey-patches, stale gem pins, docker-compose.yml / compose.yaml sister services (web-next, worker-next with BUNDLE_GEMFILE: Gemfile.next), and doc drift (README, bin/setup, .tool-versions, Dockerfile).
4. Phase 3 - Housekeeping. CI matrix entry, Dockerfile / .ruby-version / .tool-versions alignment for Ruby bumps.
5. Phase 4 - Final verification. Local or CI, with explicit fallback to CI when the local environment can't run tests.
6. Phase 5 - Commit and PR. Suggested commit messages, single-purpose PR.

Out of scope by design: load_defaults alignment (handled by rails-load-defaults), deprecation triage (next-hop work owned by rails-upgrade), and migration class suffix / db/schema.rb regen (upgrade artifacts, not cleanup).

Sequential Upgrades Only

We never skip versions. Each Rails minor/major version introduces changes that build on previous versions. Skipping creates compound issues that are nearly impossible to debug.

✅ Correct: 6.0 → 6.1 → 7.0 → 7.1
❌ Wrong:   6.0 → 7.1 (skipping 6.1 and 7.0)

Deprecation-First Approach

Before upgrading:

1. Enable deprecation warnings in your current version
2. Fix all deprecation warnings
3. Deploy those fixes to production
4. Then bump the Rails version

This reduces the upgrade to a single Gemfile change.

What This Skill Doesn't Do

Be aware of these limitations:

Contributing

We welcome contrib