Analyze a Ruby on Rails app and produce a comprehensive upgrade assessment with version detection, gem-compatibility checks, and selective config file merging. USE WHEN assessing how to upgrade an existing Rails application to a newer Rails version, auditing gem compatibility, or planning a framework-config migration.
Analyze a Ruby on Rails app and produce a comprehensive upgrade assessment with version detection, gem-compatibility checks, and selective config file merging. USE WHEN assessing how to upgrade an existing Rails application to a newer Rails version, auditing gem compatibility, or planning a framework-config migration.
cluster
python-backend
version
1.0.0
origin
antigravity-awesome-skills (MIT)
risk
safe
source
https://github.com/robzolkos/skill-rails-upgrade
date_added
2026-02-27
When to Use This Skill
Analyze Rails apps and provide upgrade assessments
Use this skill when working with analyze rails apps and provide upgrade assessments.
Rails Upgrade Analyzer
Analyze the current Rails application and provide a comprehensive upgrade assessment with selective file merging.
Step 1: Verify Rails Application
Check that we're in a Rails application by looking for these files:
Gemfile (must exist and contain 'rails')
config/application.rb (Rails application config)
config/environment.rb (Rails environment)
If any of these are missing or don't indicate a Rails app, stop and inform the user this doesn't appear to be a Rails application.
Step 2: Get Current Rails Version
Extract the current Rails version from:
First, check Gemfile.lock for the exact installed version (look for rails (x.y.z))
If not found, check Gemfile for the version constraint
Report the exact current version (e.g., 7.1.3).
Step 3: Find Latest Rails Version
Use the GitHub CLI to fetch the latest Rails release:
gh api repos/rails/rails/releases/latest --jq '.tag_name'
This returns the latest stable version tag (e.g., v8.0.1). Strip the 'v' prefix for comparison.
Also check recent tags to understand the release landscape:
gh api repos/rails/rails/tags --jq '.[0:10] | .[].name'
Step 4: Determine Upgrade Type
Compare current and latest versions to classify the upgrade:
Patch upgrade: Same major.minor, different patch (e.g., 7.1.3 → 7.1.5)
Minor upgrade: Same major, different minor (e.g., 7.1.3 → 7.2.0)
Major upgrade: Different major version (e.g., 7.1.3 → 8.0.0)
Step 5: Fetch Upgrade Guide
Use WebFetch to get the official Rails upgrade guide:
IMPORTANT: Do NOT run rails app:update as it overwrites files without considering local customizations. Instead, follow this selective merge process:
9.1: Detect Local Customizations
Before any upgrade, identify files with local customizations:
# Check for uncommitted changes
git status
# List config files that differ from a fresh Rails app# These are the files we need to be careful with
git diff HEAD --name-only -- config/ bin/ public/
Create a mental list of files in these categories:
Custom config files: Files with project-specific settings (i18n, mailer, etc.)
Modified bin scripts: Scripts with custom behavior (bin/dev with foreman, etc.)
Standard files: Files that haven't been customized
9.2: Analyze Required Changes from Railsdiff
Based on the railsdiff output from Step 6, categorize each changed file:
Category
Action
Example
New files
Create directly
config/initializers/new_framework_defaults_X_Y.rb
Unchanged locally
Safe to overwrite
public/404.html (if not customized)
Customized locally
Manual merge needed
config/application.rb, bin/dev
Comment-only changes
Usually skip
Minor comment updates in config files
9.3: Create Upgrade Plan
Present the user with a clear upgrade plan:
## Upgrade Plan: Rails X.Y.Z → A.B.C
### New Files (will be created):
- config/initializers/new_framework_defaults_A_B.rb
- bin/ci (new CI script)
### Safe to Update (no local customizations):
- public/400.html
- public/404.html
- public/500.html
### Needs Manual Merge (local customizations detected):
- config/application.rb
└─ Local: i18n configuration
└─ Rails: [describe new Rails changes if any]
- config/environments/development.rb
└─ Local: letter_opener mailer config
└─ Rails: [describe new Rails changes]
- bin/dev
└─ Local: foreman + Procfile.dev setup
└─ Rails: changed to simple ruby script
### Skip (comment-only or irrelevant changes):
- config/puma.rb (only comment changes)
9.4: Execute Upgrade Plan
After user confirms the plan:
For New Files:
Create them directly using the content from railsdiff or by extracting from a fresh Rails app:
# Generate a temporary fresh Rails app to extract new filescd /tmp && rails new rails_template --skip-git --skip-bundle
# Then copy needed files
Or use the Rails generator for specific files:
bin/rails app:update:configs # Only updates config files, still interactive
For Safe Updates:
Overwrite these files as they have no local customizations.
For Manual Merges:
For each file needing merge, show the user:
Current local version (their customizations)
New Rails default (from railsdiff)
Suggested merged version that:
Keeps all local customizations
Adds only essential new Rails functionality
Removes deprecated settings
Example merge for config/application.rb:
# KEEP local customizations:
config.i18n.available_locales = [:de, :en]
config.i18n.default_locale = :de
config.i18n.fallbacks = [:en]
# ADD new Rails 8.1 settings if needed:# (usually none required - new defaults come via new_framework_defaults file)
