Rails Upgrade Skill — Maquina

A comprehensive Claude skill that helps you upgrade Ruby on Rails applications through any version from 7.0 to 8.1.1. Built on official Rails CHANGELOGs and integrated with MCP tools for automatic project analysis.

What Is This?

A Claude skill that:

• Analyzes your Rails project automatically using Rails MCP tools
• 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
• Updates files interactively via Neovim (optional)
• Based on official Rails CHANGELOGs from GitHub

Quick Start

1. Install the Skill

Upload to your Claude Project:

1. Open your Claude Project
2. Go to Project Settings → Knowledge
3. Upload the rails-upgrade-assistant/ folder
4. Or upload just SKILL.md for minimal setup

2. Connect MCP Servers

Required: Rails MCP Server

gem install rails-mcp-server

The Rails MCP Server analyzes your models, routes, schemas, and executes read-only Ruby code in your Rails context. Installation guide

Optional: Neovim MCP Server

gem install nvim-mcp-server

Enables interactive file updates directly in your editor. Installation guide

3. Start Upgrading

Say to Claude:

"Upgrade my Rails app to 8.1"

Claude will:

1. Detect your current Rails version
2. Plan the upgrade path (single or multi-hop)
3. Analyze your project for custom code
4. Generate comprehensive upgrade report
5. Provide step-by-step instructions
6. Optionally update files interactively

Supported Upgrade Paths

Sequential Upgrades Required

Rails upgrades must be sequential:

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

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

Operating Modes

Mode 1: Report-Only (Recommended)

Best for understanding what needs to change before making edits.

"Upgrade my Rails app from 7.2 to 8.0"

Claude will:

1. Call railsMcpServer:project_info to detect 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.

Mode 2: Interactive with Neovim

Best for experienced users who want live file updates.

Requirements:

• Files open in Neovim
• Neovim socket at /tmp/nvim-{project_name}.sock
• Neovim MCP server connected

"Upgrade to Rails 8.1 in interactive mode with project 'myapp'"

Claude will:

1. Generate full upgrade report
2. Check which files are open in Neovim
3. For each file needing changes:
   • Show current code (OLD)
   • Show proposed code (NEW)
   • Ask for approval before updating
4. Verify each change applied successfully
5. Summarize all changes made

Mode 3: 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?"

MCP Tools Integration

The skill uses these Rails MCP tools to understand your project:

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/

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:

• Rails MCP server connected
• Current version confirmed
• Dependencies reviewed for compatibility
• Custom code documented

Package Contents

rails-upgrade-assistant/
├── SKILL.md                    Entry point
├── 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-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