Analyze Rails Apps and Generate Upgrade Roadmaps

Rails Upgrade Analyzer examines your Ruby on Rails application to determine the current version, identify the latest stable Rails release, and generate a comprehensive upgrade assessment. It fetches official upgrade guides, analyzes configuration file changes via railsdiff.org, checks JavaScript dependencies, and provides a selective file-merge strategy that avoids the pitfalls of rails app:update.

Use this skill when you need to upgrade a Rails application and want a detailed roadmap of breaking changes, configuration updates, and dependency requirements. It is especially valuable for major version jumps (e.g., Rails 7.1 to 8.0) where breaking changes are significant. Use it before starting any upgrade work to understand complexity and plan your migration steps.

Do NOT use this skill if you are not working in a Rails application - it verifies the presence of Gemfile, config/application.rb, and config/environment.rb before proceeding. Do NOT use it as a substitute for running your test suite or for applications with heavily customized Rails internals that diverge from standard Rails conventions.

You provide access to a Rails application directory. The skill reads Gemfile, Gemfile.lock, config/importmap.rb, and other configuration files to extract version information and detect customizations.

You receive a comprehensive upgrade summary including current and target Rails versions, upgrade complexity rating (Small/Medium/Large), key breaking changes, JavaScript dependency updates, and step-by-step upgrade instructions. The output includes links to official Rails guides, railsdiff.org comparisons, and GitHub release notes.

The skill integrates with:

• GitHub CLI to fetch the latest Rails releases and tags:

gh api repos/rails/rails/releases/latest --jq '.tag_name'

• WebFetch to retrieve the official Rails upgrade guide from https://guides.rubyonrails.org/upgrading_ruby_on_rails.html and railsdiff.org comparisons like https://railsdiff.org/7.1.3/8.0.0

• npm/yarn package managers to check for updates to Rails-related JavaScript packages:

npm outdated @hotwired/turbo-rails @hotwired/stimulus @rails/actioncable @rails/activestorage 2>/dev/null

• importmap-rails for applications using import maps instead of npm:

cat config/importmap.rb | grep -E 'pin.*turbo|pin.*stimulus|pin.*@rails' || echo "No importmap pins found"

• Git to detect local customizations and uncommitted changes before file merges

Rails developers and DevOps engineers responsible for maintaining and upgrading Ruby on Rails applications. It is particularly useful for teams managing legacy Rails apps that need to jump multiple versions, or for developers who want to understand the full scope of an upgrade before committing to the work. The skill helps avoid the common mistake of blindly running rails app:update, which overwrites customized configuration files without preserving local changes.