Skip to content
Back to search

claude-code_rails-upgrade-skill

🤖 The one and only Claude Code Skill to Upgrade Rails by FastRuby.io -- Based on 60,000 dev/hours of experience upgrading Rails from 2.3 all the way to 8.1. Dual boot your Rails application and gradually upgrade one minor version at a time. 🚀

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ombulabs--claude-code-rails-upgrade-skill/badge.svg)](/listings/ombulabs--claude-code-rails-upgrade-skill)

HTML

<a href="/listings/ombulabs--claude-code-rails-upgrade-skill"><img src="/api/listings/ombulabs--claude-code-rails-upgrade-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

This skill depends on two companion skills: [rails-load-defaults](https://github.com/ombulabs/claude-code_rails-load-defaults-skill) and [dual-boot](https://github.com/ombulabs/claude-code_dual-boot-skill). 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/

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 24 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "rails-upgrade",
  3. "version": "4.1.0",
  4. "description": "Plan and execute Rails version upgrades following FastRuby.io methodology",
  5. "skills": "./rails-upgrade/",
  6. "author": {
  7. "name": "OmbuLabs",
  8. "url": "https://github.com/ombulabs"
  9. },
  10. "repository": "https://github.com/ombulabs/claude-code_rails-upgrade-skill",
  11. "license": "MIT",
  12. "keywords": [
  13. "ruby",
  14. "rails",
  15. "upgrade",
  16. "migration",
  17. "fastruby",
  18. "breaking-changes",
  19. "tech-debt",
  20. "deprecations",
  21. "legacy-code",
  22. "ruby-on-rails"
  23. ]
  24. }
README.md · README · 196 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Rails Upgrade Assistant Skill
  2. A Claude Code skill that helps you upgrade Ruby on Rails applications from version 2.3 through 8.1.
  3. ## What Does This Skill Do?
  4. The Rails Upgrade Assistant analyzes your Rails application and generates:
  5. - **Comprehensive Upgrade Reports** - Detailed migration guides with OLD vs NEW code examples from your actual codebase
  6. - **app:update Previews** - Shows exactly what configuration files will change when you run `rails app:update`
  7. 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.
  8. ## Why Trust This Skill?
  9. This skill is built on real-world experience, not just documentation:
  10. - **60,000+ developer hours** of Rails upgrade experience
  11. - **Upgrades from Rails 2.3 to Rails 8.1** for clients worldwide
  12. - Based on the methodology documented in ["The Complete Guide to Upgrade Rails"](https://www.fastruby.io/upgrade) ebook
  13. - Created by the team at [FastRuby.io](https://fastruby.io), specialists in Rails upgrades since 2017
  14. We've encountered (and solved) edge cases that don't appear in any documentation. This skill encapsulates that hard-won knowledge.
  15. ## How to Use This Skill
  16. ### Installation
  17. This skill depends on two companion skills: [rails-load-defaults](https://github.com/ombulabs/claude-code_rails-load-defaults-skill) and [dual-boot](https://github.com/ombulabs/claude-code_dual-boot-skill). A fourth sibling plugin, `upgrade-cleanup`, lives in this repo and runs the post-upgrade scaffolding teardown. The marketplace install handles all four.
  18. **From inside the Claude Code CLI prompt (recommended):**
  19. ```
  20. /plugin marketplace add ombulabs/claude-skills
  21. /plugin install rails-upgrade@ombulabs-ai
  22. /plugin install rails-load-defaults@ombulabs-ai
  23. /plugin install dual-boot@ombulabs-ai
  24. /plugin install upgrade-cleanup@ombulabs-ai
  25. ```
  26. **From your terminal:**
  27. ```bash
  28. claude plugin marketplace add https://github.com/ombulabs/claude-skills.git
  29. claude plugin install rails-upgrade@ombulabs-ai
  30. claude plugin install rails-load-defaults@ombulabs-ai
  31. claude plugin install dual-boot@ombulabs-ai
  32. claude plugin install upgrade-cleanup@ombulabs-ai
  33. ```
  34. **Manual install:**
  35. ```bash
  36. # 1. This skill
  37. git clone https://github.com/ombulabs/claude-code_rails-upgrade-skill.git
  38. cp -r claude-code_rails-upgrade-skill/rails-upgrade ~/.claude/skills/
  39. # 2. upgrade-cleanup (sibling plugin, same repo)
  40. cp -r claude-code_rails-upgrade-skill/upgrade-cleanup ~/.claude/skills/
  41. # 3. rails-load-defaults (dependency)
  42. git clone https://github.com/ombulabs/claude-code_rails-load-defaults-skill.git
  43. cp -r claude-code_rails-load-defaults-skill/rails-load-defaults ~/.claude/skills/
  44. # 4. dual-boot (dependency)
  45. git clone https://github.com/ombulabs/claude-code_dual-boot-skill.git
  46. cp -r claude-code_dual-boot-skill/dual-boot ~/.claude/skills/
  47. ```
  48. ### Basic Usage
  49. In Claude Code, navigate to your Rails application directory and use natural language:
  50. ```
  51. "Upgrade my Rails app to 7.2"
  52. "Help me upgrade from Rails 6.1 to 7.0"
  53. "What breaking changes are in Rails 8.0?"
  54. ```
  55. ### Workflow
  56. 1. **Ask for an upgrade** → Claude generates detailed reports based on your actual code
  57. 2. **Implement the changes** → Follow the step-by-step migration plan
  58. ## Available Commands
  59. | Command | Description |
  60. |---------|-------------|
  61. | `/rails-upgrade` | Start the upgrade assistant |
  62. | "Finish the upgrade" / "Clean up dual-boot" / "Abandon this upgrade" | Trigger the `upgrade-cleanup` plugin. Asks whether to keep the next or current version, then drops `NextRails.next?` / `NextRails.current?` branches and retires dual-boot scaffolding. |
  63. | "Upgrade to Rails X.Y" | Generate reports from detection results |
  64. | "Show app:update changes" | Preview configuration file changes |
  65. | "Plan upgrade from X to Y" | Get multi-hop upgrade strategy |
  66. ## Design Decisions & Best Practices
  67. This skill implements the **FastRuby.io upgrade methodology**, which includes:
  68. ### Dual-Boot Strategy
  69. Run your application with two versions of Rails simultaneously using the [`next_rails`](https://github.com/fastruby/next_rails) gem. This allows you to test both versions during the transition and deploy backwards-compatible changes before the version bump.
  70. See the [dual-boot skill](https://github.com/ombulabs/claude-code_dual-boot-skill) for setup, code patterns, and CI configuration.
  71. ### Post-Upgrade Cleanup
  72. 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.
  73. Activate it with phrases like "finish the upgrade", "clean up dual-boot", or "abandon this upgrade". The workflow:
  74. 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).
  75. 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 `require`s break test boot), swaps lockfiles, and updates CI to drop the dual-boot job.
  76. 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`).
  77. 4. **Phase 3 - Housekeeping.** CI matrix entry, `Dockerfile` / `.ruby-version` / `.tool-versions` alignment for Ruby bumps.
  78. 5. **Phase 4 - Final verification.** Local or CI, with explicit fallback to CI when the local environment can't run tests.
  79. 6. **Phase 5 - Commit and PR.** Suggested commit messages, single-purpose PR.
  80. 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).
  81. ### Sequential Upgrades Only
  82. 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.
  83. ```
  84. ✅ Correct: 6.0 → 6.1 → 7.0 → 7.1
  85. ❌ Wrong: 6.0 → 7.1 (skipping 6.1 and 7.0)
  86. ```
  87. ### Deprecation-First Approach
  88. Before upgrading:
  89. 1. Enable deprecation warnings in your current version
  90. 2. Fix all deprecation warnings
  91. 3. Deploy those fixes to production
  92. 4. Then bump the Rails version
  93. This reduces the upgrade to a single Gemfile change.
  94. ## What This Skill Doesn't Do
  95. Be aware of these limitations:
  96. | Limitation | Explanation |
  97. |------------|-------------|
  98. | **Gradual deployments** | This skill focuses on code changes, not deployment strategies. Rolling deployments, canary releases, and feature flags are outside its scope. |
  99. | **Debugging monkeypatching issues** | If gems or your code monkeypatch Rails internals, you may encounter weird issues that require manual investigation. |
  100. | **Accurate time estimates** | The difficulty ratings and time estimates are rough guidelines based on typical applications. Your mileage will vary based on codebase size, test coverage, and custom code complexity. |
  101. | **Automated code changes** | The skill provides guidance and examples, but you implement the changes. It won't automatically refactor your code. |
  102. | **Gem compatibility resolution** | While we note common gem version requirements, resolving complex dependency conflicts requires manual intervention. |
  103. | **Rails LTS upgrades** | While many of the things this Skill can do will work to upgrade Rails LTS, the strategy for those apps will be different and the Rails source code is not the same as the main Rails repository |
  104. ## Contributing
  105. We welcome contributions! Here's how you can help:
  106. ### Adding or Updating Version Guides
  107. 1. Fork the repository
  108. 2. Create a branch: `git checkout -b add-rails-X-Y-guide`
  109. 3. Add/update files in `version-guides/`
  110. 4. Follow the existing format and structure
  111. 5. Submit a pull request
  112. ### Reporting Issues
  113. - Found incorrect information? [Open an issue](https://github.com/ombulabs/claude-code_rails-upgrade-skill/issues)
  114. - Have a suggestion? We'd love to hear it
  115. - Encountered an edge case? Share your experience
  116. ### Guidelines
  117. - Keep content factual and based on official Rails documentation
  118. - Include code examples with BEFORE/AFTER patterns
  119. - Test detection patterns against real codebases when possible
  120. - New detection pattern? Add a `match`/`no_match` fixture to its `*.expectations.yml` file and run `bin/test-patterns` before opening a PR
  121. - Attribute sources appropriately
  122. ## License
  123. This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
  124. ## Sponsors
  125. This project is sponsored by:
  126. ### [OmbuLabs.ai](https://ombulabs.ai) | Custom AI Solutions
  127. We build custom AI solutions that integrate with your existing workflows. From Claude Code skills to full AI agent systems.
  128. ### [FastRuby.io](https://fastruby.io) | Ruby Maintenance, Done Right
  129. The Rails upgrade experts. We've been upgrading Rails applications professionally since 2017, helping companies stay current and secure.
  130. ---
  131. **Questions?** Open an issue or reach out to us at [hello@ombulabs.com](mailto:hello@ombulabs.com)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.