Rails Upgrade Skill

A comprehensive Claude skill that helps you upgrade Ruby on Rails applications through any version from 6.0 to 8.1.1. Built on official Rails CHANGELOGs. It analyzes your project with Claude Code’s built-in file tools — no external services required.

What Is This?

A Claude skill that:

• Analyzes your Rails project automatically by reading its files
• Detects your current version and target version
• Plans single-hop or multi-hop upgrade paths
• Identifies breaking changes specific to your code
• Preserves custom configurations with warnings
• Generates comprehensive upgrade reports
• Applies the fixes for you, editing the files directly
• Based on official Rails CHANGELOGs from GitHub

Quick Start

1. Install the Plugin

/plugin marketplace add maquina-app/rails-claude-code
/plugin install rails-upgrade-assistant@maquina

2. Start Upgrading

Say to Claude:

"Upgrade my Rails app to 8.1"

Claude will:

1. Detect your current version from Gemfile.lock and plan the path (single or multi-hop)
2. Generate a breaking-changes detection script and run it
3. Evaluate the findings against your actual code
4. Produce a comprehensive upgrade report with OLD → NEW examples
5. Offer to apply the fixes directly

Supported Upgrade Paths

Sequential Upgrades Required

Rails upgrades must be sequential:

Correct: 6.0 → 6.1 → 7.0 → 7.1 → 7.2 → 8.0 → 8.1
Wrong:   6.0 → 7.0 (skips 6.1)

For multi-hop upgrades, Claude will:

• Explain the sequential requirement
• Plan all intermediate hops
• Generate separate reports for each hop
• Guide you through completing each hop before moving to next

How It Works

Full upgrade (the default)

Best for understanding what needs to change before making edits.

"Upgrade my Rails app from 7.2 to 8.0"

Claude will:

1. Read Gemfile.lock to detect the current version
2. Load appropriate version guide(s)
3. Analyze your project files for custom code
4. Identify breaking changes affecting your code
5. Generate comprehensive upgrade report

You remain in control and apply changes manually.

Query-specific

Best for specific questions about changes.

"What ActiveRecord changes are in Rails 8.0?"
"How do I handle the SSL configuration change?"
"What breaking changes affect my models?"
"Will my Redis cache work after upgrading to 8.0?"

Key Breaking Changes by Version

Rails 8.0 → 8.1

High impact:

• SSL configuration now commented out (affects non-Kamal deploys)
• Database pool: renamed to max_connections:
• bundler-audit script required

Rails 7.2 → 8.0

High impact:

• Asset pipeline: Sprockets → Propshaft
• Solid gems: New defaults for cache/queue/cable
• Multi-database config required for Solid gems

Rails 7.1 → 7.2

High impact:

• Transaction-aware job enqueuing (behavior change)
• ActiveRecord::Base.connection deprecated
• show_exceptions changed from boolean to symbol
• Rails.application.secrets removed

Rails 7.0 → 7.1

High impact:

• cache_classes → enable_reloading (inverted logic)
• Force SSL now default in production
• SQLite database moved to storage/

Rails 6.1 → 7.0

High impact:

• Zeitwerk autoloader required (Classic removed)
• rails command replaces rake for most tasks
• Spring removed from default Gemfile
• ActiveSupport::Dependencies autoloading deprecated

Rails 6.0 → 6.1

High impact:

• Per-database connection handling changes
• ActiveRecord::Base#connection pool behavior updated
• Hotwire (Turbo + Stimulus) introduced as default frontend
• rails db:prepare added as preferred setup command

Custom Code Detection

The skill automatically detects and warns about customizations:

Database Configuration

# Custom SQLite path detected in config/database.yml
# Current: database: db/development.sqlite3
# Rails 7.1+: database: storage/development.sqlite3
# Action: Review and update path

SSL Middleware

# Custom SSL middleware detected in config/application.rb
# Line 23: middleware.use CustomSSLMiddleware
# Rails 7.1+: May conflict with config.force_ssl = true
# Action: Review compatibility

Autoload Paths

# Custom autoload_paths in config/application.rb
# Line 15: config.autoload_paths << Rails.root.join('lib')
# Rails 7.1+: lib/ autoloaded by default (config.autoload_lib)
# Action: Remove manual path to avoid conflicts

Asset Pipeline

# Custom Sprockets processors detected
# Files: lib/assets/processors/custom_minifier.rb
# Rails 8.0+: Propshaft doesn't support processors
# Action: Migrate to different approach or keep Sprockets

What You Get

Every upgrade request generates a detailed report:

1. Executive Summary

• Current and target versions
• Number of breaking changes
• Estimated time and risk assessment

2. Project Analysis

• Your Rails version and structure
• Files that need updating
• Custom configurations detected

3. Breaking Changes (Prioritized)

• HIGH Priority: Will cause app to fail
• MEDIUM Priority: Should address soon
• LOW Priority: Optional improvements

4. Code Examples (OLD vs NEW)

# OLD (Rails 7.2)
config.action_dispatch.show_exceptions = true

# NEW (Rails 7.2+)
config.action_dispatch.show_exceptions = :all

5. Step-by-Step Migration Guide

• Phase-by-phase breakdown
• Time estimates per phase
• Testing checkpoints

6. Testing Checklist

• Unit test guidance
• Integration test scenarios
• Manual testing checklist

Pre-Upgrade Checklist

Before starting any upgrade:

Critical:

• All tests currently passing
• Database backed up
• Application under version control
• Staging environment available
• Rollback plan documented

Important:

• Current version confirmed
• Dependencies reviewed for compatibility
• Custom code documented

Package Contents

rails-upgrade-assistant/
├── agents/rails-upgrade-assistant.md   Main agent
├── workflows/                  How to generate deliverables
├── examples/                   Real usage scenarios
├── reference/                  Quick reference
├── version-guides/             Rails version details
├── templates/                  Report templates
└── detection-scripts/          Pattern definitions

Version Guides

• upgrade-6.0-to-6.1.md - 18 breaking changes
• upgrade-6.1-to-7.0.md - 17 breaking changes
• upgrade-7.0-to-7.1.md - 12 breaking changes
• upgrade-7.1-to-7.2.md - 38 breaking changes
• upgrade-7.2-to-8.0.md - 13 breaking changes
• upgrade-8.0-to-8.1.md - 8 breaking changes

Usage Examples

Simple Upgrade

"Upgrade my Rails app to 8.1"

With Specific Details

"Upgrade my Rails app from 7.2 to 8.0"

Risk Assessment Only

"Assess upgrade impact from 7.2 to 8.0"

Component-Specific Questions

"What ActiveRecord changes are in Rails 8.0?"
"Show me all configuration file changes for 7.2"

Next Steps