Rails Upgrade Assistant Skill

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

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.

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.

This is the bootboot fork. The plugins published on the ombulabs-ai marketplace are the upstream versions, which use next_rails for dual-boot. Installing rails-upgrade or upgrade-cleanup from that marketplace will not give you the bootboot workflow this README describes. Install those two from this repository using one of the methods below.

This repo ships two skills — rails-upgrade and its sibling upgrade-cleanup, which runs the post-upgrade scaffolding teardown. There is one external companion skill, rails-load-defaults, which is not forked and installs normally from the upstream marketplace.

Dual-boot is handled inline using the bootboot Bundler plugin — no separate skill required.

Symlink install (recommended):

Best if you expect to edit the skills or track this fork. Edits in the clone take effect immediately, with no re-install step.

git clone https://github.com/Kajabi/claude-code_rails-upgrade-skill.git
cd claude-code_rails-upgrade-skill

mkdir -p ~/.claude/skills
ln -s "$PWD/rails-upgrade" ~/.claude/skills/rails-upgrade
ln -s "$PWD/upgrade-cleanup/upgrade-cleanup" ~/.claude/skills/upgrade-cleanup

Copy install:

Best if you just want to use the skills and do not intend to change them. You will need to re-copy to pick up updates.

git clone https://github.com/Kajabi/claude-code_rails-upgrade-skill.git
mkdir -p ~/.claude/skills
cp -r claude-code_rails-upgrade-skill/rails-upgrade ~/.claude/skills/
cp -r claude-code_rails-upgrade-skill/upgrade-cleanup/upgrade-cleanup ~/.claude/skills/

Note the nested path on the second command. upgrade-cleanup/ is a plugin wrapper directory; the skill itself — the directory holding SKILL.md — is upgrade-cleanup/upgrade-cleanup/. Copying the wrapper puts SKILL.md one level too deep and Claude Code will not discover it.

The companion skill (unforked, upstream):

From inside the Claude Code CLI prompt:

/plugin marketplace add ombulabs/claude-skills
/plugin install rails-load-defaults@ombulabs-ai

Or from your terminal:

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

Verifying the install:

ls ~/.claude/skills/rails-upgrade/SKILL.md ~/.claude/skills/upgrade-cleanup/SKILL.md

Both paths must exist. In a new Claude Code session, /rails-upgrade should then be available.

The bootboot Bundler plugin gets installed inside your Rails app during Step 2 of the upgrade workflow (plugin "bootboot" plus the enable_dual_booting block in the Gemfile, then bundle install, cp Gemfile.lock Gemfile_next.lock, and DEPENDENCIES_NEXT=1 bundle install). It is not a Claude Code skill and does not need to be installed at the ~/.claude level.

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?"

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

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

Run your application with two versions of Rails simultaneously using the bootboot Bundler plugin. Bootboot keeps a single Gemfile with conditional blocks plus two lockfiles (Gemfile.lock and Gemfile_next.lock) and lets the app boot under either set by prefixing commands with DEPENDENCIES_NEXT=1. This lets you test both versions during the transition and deploy backwards-compatible changes before the version bump.

Step 2 of the upgrade workflow wires bootboot into the Gemfile inline (see rails-upgrade/SKILL.md → "CRITICAL: Dual-Boot Setup with bootboot" for the snippet). Application code that has to branch on the active dependency set uses if ENV["DEPENDENCIES_NEXT"] — the same env var bootboot reads, so the boot-time gate and the code-time gate stay aligned.

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 if ENV["DEPENDENCIES_NEXT"] branches (and any project-specific wrapper helpers), removes the bootboot plugin loader and enable_dual_booting activation from the Gemfile, swaps lockfiles, and updates CI to drop the dual-boot job. If the project previously ran on next_rails, the workflow notes how to sweep its residue (Gemfile.next*, NextRails.next?, deprecation_tracker) in the same pass.
3. Phase 2 - Old-version code retirement. Monkey-patches, stale gem pins, docker-compose.yml / compose.yaml sister services (web-next, worker-next that set DEPENDENCIES_NEXT=1), 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).

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)

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.

Be aware of these limitations:

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a branch: git checkout -b add-rails-X-Y-guide
3. Add/update files in version-guides/
4. Follow the existing format and structure
5. Submit a pull request

• Found incorrect information? Open an issue
• Have a suggestion? We'd love to hear it
• Encountered an edge case? Share your experience

• Keep content factual and based on official Rails documentation
• Include code examples with BEFORE/AFTER patterns
• Test detection patterns against real codebases when possible
• New detection pattern? Add a match/no_match fixture to its *.expectations.yml file and run bin/test-patterns before opening a PR
• Attribute sources appropriately

This project is licensed under the MIT License. See LICENSE for details.

This is a fork of OmbuLabs.ai's claude-code_rails-upgrade-skill, updated to support the bootboot Bundler plugin as the dual-boot mechanism instead of next_rails. The original methodology is from FastRuby.io's "The Complete Guide to Upgrade Rails" and the OmbuLabs team's Rails upgrade work since 2017 — all credit for the underlying skill design goes to them.