A Claude Code skill that drives a legacy Ruby on Rails application through a safe, incremental, one-version-at-a-time upgrade — pairing each Rails target with a compatible Ruby version and systematically clearing deprecations at every hop.
It behaves like an experienced upgrade engineer: it never jumps multiple releases at once, leans on your test suite as a safety net, fixes deprecations before they become hard errors in the next version, and pauses for human review and commit after each hop.
Supported range: Rails 3.0 → 8.0 (and the Ruby versions each release needs).
The upgrade follows a fixed chain of single-version hops:
3.0 → 3.1 → 3.2 → 4.0 → 4.1 → 4.2 → 5.0 → 5.1 → 5.2 → 6.0 → 6.1 → 7.0 → 7.1 → 7.2 → 8.0
For each hop the skill runs the same loop:
- Pre-flight — detect current Ruby/Rails (from
Gemfile.lock), test framework, coverage, and whether the suite is green right now. - Resolve & plan — map your app's exact version onto a node in the chain and present the ordered hop plan (with the required Ruby bump per hop) for approval.
- Execute ONE hop — bump Ruby (if required) → bump Rails →
bin/rails app:update→ adopt new framework defaults one at a time → work through that hop's breaking-change checklist → get the suite green. - Stop for review — summarize what changed and pause so you can review the diff and commit before the next hop.
- One hop at a time. No skipping minors. Each hop is reviewed in isolation.
- Green suite required to advance. If coverage is thin, it offers to add characterization tests rather than upgrading blind.
- Trusts
Gemfile.lock, not theGemfilefor the resolved truth. - Dual-boot (running two Rails versions side by side via Bundler) is offered for the heavy major hops: 3.2→4.0, 4.2→5.0, 5.2→6.0, 6.1→7.0, 7.2→8.0.
Clone the repo into your Claude Code skills directory (or clone elsewhere and symlink it):
# Option A — clone directly into the skills directory
git clone https://github.com/jcuervo/rails-upgrade.git \
~/.claude/skills/rails-upgrade
# Option B — clone anywhere, then symlink
git clone https://github.com/jcuervo/rails-upgrade.git
ln -s "$(pwd)/rails-upgrade" ~/.claude/skills/rails-upgradeThe skill becomes invocable as /rails-upgrade in any Claude Code session.
From within the Rails project you want to upgrade, run:
/rails-upgrade
…to target the latest supported Rails (8.0), or name a target:
/rails-upgrade 6.1
The skill will assess the app, present a hop plan for your approval, and then execute and pause one hop at a time. Review and commit each hop before continuing.
Tip: Start with a clean working tree and a passing test suite. The skill uses the suite as the gate between hops — a red suite blocks advancement by design.
rails-upgrade/
├── SKILL.md # entry point: frontmatter + workflow
├── references/
│ ├── compatibility-matrix.md # hop chain + Ruby↔Rails pairings (source of truth)
│ ├── starting-version-resolution.md # map any start version → a node in the chain
│ ├── per-hop-workflow.md # mechanics shared by every hop + dual-boot
│ ├── gem-compatibility.md # live gem resolution + common blocking gems
│ └── hops/ # one checklist per hop (14 files)
│ ├── 3.0-to-3.1.md
│ ├── ...
│ └── 7.2-to-8.0.md
├── project-brief.md # design record & rationale
├── CLAUDE.md # guidance for Claude Code instances editing this repo
├── CONTRIBUTING.md
└── LICENSE
SKILL.md stays small and loads the reference files on demand; the heavy
version-specific knowledge lives in references/hops/.
This skill is self-sufficient and does not depend on any other skill. If you
also use the separate rails-audit skill, rails-upgrade will read an existing
audit deck as optional human context — but it derives everything it needs for the
upgrade on its own.
Contributions are welcome — especially keeping the per-hop breaking-change checklists accurate and current. See CONTRIBUTING.md.
MIT © 2026 jcuervo