rails-cto-upgrade

The Rails upgrade skill. Analyzes the current Rails version, compares it to the latest release, and performs a selective upgrade that preserves your local customizations.

What it does

Rails upgrades are famously tricky — the hard part isn't bumping the version in Gemfile, it's the dozens of small config changes and deprecation fixes that ride along with a major release. This skill walks through the upgrade deliberately:

1. Verify the project is a Rails app by checking for Gemfile, config/application.rb, and config/environment.rb
2. Detect the current version from Gemfile.lock
3. Find the latest release on GitHub (or whichever target version you specify)
4. Fetch upgrade notes and diffs — both the official Rails upgrade guide and the rails/rails repo's railties/RAILS_VERSION diffs
5. Run bin/rails app:update to generate the config changes Rails wants
6. Review each generated change against your current config files
7. Merge selectively — accept framework changes, preserve project customizations, and flag anything that needs a human decision
8. Run the test suite and the QA skill to verify nothing broke
9. Report what was changed, what was skipped, and what needs manual follow-up

The skill does not blindly run rails app:update and commit everything. That's how upgrade PRs end up with 500 lines of noise that overwrite local customizations. Instead, it's a guided, file-by-file merge.

When it triggers

• When you say upgrade Rails, bump Rails, update Rails version, or Rails 8 upgrade
• When you mention a specific target version (upgrade to 8.1, upgrade to 7.2)

Does not handle Ruby version upgrades, gem upgrades unrelated to Rails, or non-Rails framework upgrades.

Example

You: Upgrade this app from Rails 7.1 to Rails 8.0

Agent: [invokes /rails-cto-upgrade]
       [verifies Rails app → ✓]
       [current version: 7.1.3.4]
       [target: 8.0.1 (latest stable)]
       [fetches Rails 8 upgrade guide]
       [runs bin/rails app:update]

       23 files touched. Reviewing each:

       ✓ config/application.rb — accept `load_defaults 8.0`
       ✓ config/initializers/new_framework_defaults_8_0.rb — new file, accept
       ⚠ config/environments/production.rb — CONFLICT
         Rails wants: config.assume_ssl = true
         You have:   config.assume_ssl = false (local override)
         → Keeping your override. Flagged for manual review.
       ✓ config/initializers/content_security_policy.rb — merge
       ⚠ test/test_helper.rb — your SimpleCov patch conflicts with
         the new default — preserving the patch.
       [… continues for 23 files …]

       [bumps Gemfile rails to ~> 8.0.1]
       [runs bundle update rails]
       [runs /rails-cto-qa → 4 test failures from deprecated
        `ActiveRecord::Base.connection` calls]
       [fixes the deprecations]
       [re-runs /rails-cto-qa → clean]

       ✓ Upgrade complete. Manual review needed on:
         - config/environments/production.rb (assume_ssl override)
         - One deprecated config.i18n fallback in fr.yml

View source

skills/rails-cto-upgrade/SKILL.md on GitHub →