Rails Upgrade Assistant skill
A FastRuby.io skill for Claude Code: Rails 2.3 to 8.1 upgrade reports with examples from your code and a version-by-version plan
- 405 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Detection scripts read the application code, and the upgrade-cleanup plugin edits files, the Gemfile, CI and Docker configuration
- Reports give rough time estimates, and the Rails version in production changes only through your own team
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/rails-upgrade-assistantDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Detection scripts read the application code, and the upgrade-cleanup plugin edits files, the Gemfile, CI and Docker configuration
- Reports give rough time estimates, and the Rails version in production changes only through your own team
This is third-party code. Review the repository files before installing.
What it does
Rails Upgrade Assistant is a Claude Code skill from FastRuby.io (OmbuLabs) that guides a Ruby on Rails application upgrade from any version between 2.3 and 8.1. The skill reads the application code and builds a detailed upgrade report: what breaks, which calls are deprecated, and how the code looks before and after on examples from your project. A separate report shows which configuration files `rails app:update` will change. The method is sequential: one minor or major version at a time, for example 5.2, 6.0, 6.1, 7.0, with no skipping. First you enable deprecation warnings in the current version, fix them and ship to production, and only then change the Rails version in the Gemfile. The `next_rails` gem and a dual-boot setup test two versions at once. The skill itself gives guidance and examples, and you make the edits. It depends on the dual-boot and rails-load-defaults skills. The same repository holds an upgrade-cleanup plugin: on phrases like "finish the upgrade" it tears down the dual-boot scaffolding after a finished or abandoned hop.
Who it is for. Rails teams and contractors raising an application from 5.x, 6.x or 7.x to a current version who want to follow the FastRuby.io method.
Good fit when
- The application is on Rails 6.1, the target is 7.0, and you need a report on breakage and deprecated calls
- A chain of versions from 5.2 to 7.1 is ahead and you need a plan of sequential hops
- Before `rails app:update` you want to see which configuration files will change
- In the current version you need to collect deprecation warnings and work through them before changing versions
- The hop is finished or abandoned and it is time to remove the `NextRails.next?` branches and the second set of dependencies
Not a fit when
- You need automatic code edits: the skill shows examples and you change the code
- The application runs Rails LTS: the strategy is different there and the source differs from the main Rails repository
- You need a rollout strategy: canary releases and feature flags are outside the skill's scope
Example request
Help me upgrade from Rails 6.1 to 7.0 and show what rails app:update will changeLimitations
The skill does not debug monkeypatch problems: if gems or your code override Rails internals, you hunt the cause by hand. It leaves dependency conflicts between gems to you as well: it only names the known version requirements.
Difficulty and time estimates in the reports are rough: they depend on code size, test coverage and the amount of custom code.
The dual-boot skill is needed for the dual-boot setup and rails-load-defaults for the final `load_defaults` step. Installing from the plugin marketplace installs all four.
How to disable. Remove the plugins through `/plugin` in Claude Code or the rails-upgrade, upgrade-cleanup, rails-load-defaults and dual-boot folders from `~/.claude/skills/`. Dual-boot files in your application, such as `Gemfile.next`, are removed by the upgrade-cleanup plugin or by you by hand.
FAQ
How do I install the skill in Claude Code?
Run `/plugin marketplace add ombulabs/claude-skills`, then `/plugin install rails-upgrade@ombulabs-ai`, plus `rails-load-defaults`, `dual-boot` and `upgrade-cleanup` with the same suffix. From a terminal the `claude plugin marketplace add` and `claude plugin install` commands do the same. The manual route copies the folders into `~/.claude/skills/`.
Can I skip intermediate versions?
No. The skill always goes one version at a time, for example 6.0, 6.1, 7.0, because skipping piles up problems that are nearly impossible to debug. For a chain there is the request "Plan upgrade from X to Y".
What is dual-boot and why use it?
The application runs with two Rails versions at once through the `next_rails` gem. Both versions get tested, and compatible edits ship before the version changes. A separate dual-boot skill runs the setup.
What does the upgrade-cleanup plugin do?
After a finished or abandoned hop it tears down the dual-boot scaffolding: it removes the `NextRails.next?` and `NextRails.current?` branches, extra Gemfile groups, `deprecation_tracker` leftovers and the second CI job. First it asks which version to keep, the next or the current. It starts on phrases like "Finish the upgrade", "Clean up dual-boot" or "Abandon this upgrade".
Which Rails versions are supported?
Upgrades from version 2.3 to 8.1. Version guides live in the `version-guides/` folder, and the pattern-based problem detection scripts exist separately for each version starting at 4.0.
Discussion
No questions or reviews yet.
Related
SkillsA skill and a collection of 200-plus production Rails apps where an agent studies how real projects solve architecture problems
iuhoay/skills collects agent skills: Vanilla Rails, Linear, stacked pull requests, plan challenging and tidy changes.
Catalog of 46 versioned skills for code review, releases, CI and landing pages, installed as the lstack plugin or through npx.
Over 200 skills by stack and practice: React, Next.js, Rails, Rust, Python, debugging, TDD and UI review
A Claude Code skill acting as reviewer, pair programmer, debugger and mentor, driving work from spec to verification.
A skill that moves a customized standard 1C configuration to a new vendor release through a three-way git merge
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Rails Upgrade Assistant (this card) | no | 405 | ||
| Layered Rails Skills | no | 479 | guards the layers of a Rails app by the Layered Design book and does not run upgrades | |
| rails-ai-context | no | not required | 186 | an MCP server that gives the agent the app schema, models and routes |
README in short
The README explains what the skill does and rests on FastRuby.io experience and the ebook "The Complete Guide to Upgrade Rails". Three ways to install follow, example requests, a command table, the method principles (dual-boot, post-hop cleanup, strictly sequential versions, deprecations first), the limits and rules for contributing to the version guides.
README badge
Original SKILL.md
--- name: rails-upgrade description: Analyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 2.3 through 8.1. Use when upgrading Rails applications, planning multi-hop upgrades, querying version-specific changes, or answering what stands between the app and the next Rails version. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook. --- # Rails Upgrade Assistant Skill ## Skill Identity - **Name:** Rails Upgrade Assistant - **Purpose:** Intelligent Rails application upgrades from 2.3 through 8.1 - **Skill Type:** Modular with external workflows and examples - **Upgrade Strategy:** Sequential only (no version skipping) - **Methodology:** Based on FastRuby.io upgrade best practices and "The Complete Guide to Upgrade Rails" ebook - **Attribution:** Content based on "The Complete Guide to Upgrade Rails" by FastRuby.io (OmbuLabs) --- ## Terminology | Term | Meaning | Where | |------|---------|-------| | **Workflow** | One numbered unit of the upgrade flow, one file | `workflows/<NN>-<name>-workflow.md` | | **Step** | A `Step N` header inside a workflow file | inside the workflow | | **Reference** | Material loaded on demand: lookup tables, playbooks, conditional branches | `references/<name>-reference.md` | No sub-steps: a "Step 4.1" is either two sequential steps or a conditional branch inside one step (`### A.` / `### B.` headers). Refer to a whole workflow as Workflow NN; refer to a step as file path plus step, e.g. `workflows/01-run-test-suite-workflow.md` Step 4. Not used in headings: Stage, Phase, Sub-step, dotted step numbers. --- ## Dependencies - **dual-boot skill** ([github.com/ombulabs/claude-code_dual-boot-skill](https://github.com/ombulabs/claude-code_dual-boot-skill)) — Sets up and manages dual-boot environments using the `next_rails` gem. Covers setup, `NextRails.next?` code patterns, CI configuration, and post-upgrade cleanup. Must be installed for Workflow 04. - Workflow 04 file: `workflows/04-setup-next-rails-workflow.md` - **rails-load-defaults skill** ([github.com/ombulabs/claude-code_rails-load-defaults-skill](https://github.com/ombulabs/claude-code_rails-load-defaults-skill)) — Handles incremental `load_defaults` updates with tiered risk assessment (Tier 1: low-risk, Tier 2: needs codebase grep, Tier 3: requires human review). Used as the final step after the Rails version upgrade is complete. --- ## Core Methodology (FastRuby.io Approach) This skill follows the proven FastRuby.io upgrade methodology: 1. **Incremental Upgrades** - Always upgrade one minor/major version at a time 2. **Assessment First** - Understand scope before making changes 3. **Dual-Boot Testing** - Test both versions during transition using `next_rails` gem 4. **Test Coverage** - Ensure adequate test coverage before upgrading (aim for 80%+) 5. **Gem Compatibility** - Check gem compatibility at each step using RailsBump 6. **Deprecation Warnings** - Address deprecations before upgrading 7. **Backwards Compatible Changes** - Deploy small changes to production before version bump **Key Resources:**