robzolkos/skill-rails-upgrade
Overview
This skill analyzes a Rails application and produces a safe, actionable upgrade plan that preserves local customizations. It detects the app and current Rails version, compares it to the latest Rails release, fetches upgrade notes and diffs, and produces a selective merge plan instead of running a blind app update. The output is a prioritized checklist with file-level actions, JS dependency checks, and verification steps.
How this skill works
The skill inspects the repository for Rails indicators (Gemfile, config/application.rb, config/environment.rb) and extracts the current Rails version from Gemfile.lock or Gemfile. It queries the latest Rails release via the GitHub CLI and fetches upgrade guidance from the official Rails upgrade guide and railsdiff.org to summarize file and config changes. Finally it analyzes local git changes to detect customizations and builds a selective upgrade plan that lists new files, safe overwrites, and files requiring manual merges.
When to use it
- Preparing to bump Rails in an application repository
- Assessing upgrade risk before a major or minor Rails release
- Planning an upgrade while preserving customized config or bin scripts
- Auditing JS packages compatibility when upgrading Rails
- Creating a step-by-step, reviewable upgrade plan for a team
Best practices
- Never run rails app:update blindly — use the selective merge plan produced here
- Ensure the repo is clean and committed before starting (git status) to detect local customizations
- Generate a fresh Rails template to copy new defaults rather than overwriting customized files
- Address JavaScript packages in lockstep with Rails (check package.json or importmap pins)
- Enable new framework defaults one at a time and run tests after each change
Example use cases
- Upgrade from Rails 7.1.3 to 8.0.0: get diff, list breaking changes, and produce manual merge instructions for config/application.rb and bin/dev
- Patch upgrade (7.1.3 → 7.1.5): verify minimal changes and recommend safe overwrites for public/ files
- Minor upgrade planning (7.1.3 → 7.2.0): identify required config changes and JS package updates
- Audit a repo before CI runs to produce a checklist of files that would be overwritten by rails app:update
FAQ
The skill will stop after verification and tell you which Rails indicators are missing (Gemfile, config/application.rb, config/environment.rb).
Will this run rails app:update?
No. The skill explicitly avoids running rails app:update and instead produces a selective merge plan that preserves local customizations.
How does it detect local customizations?
It checks git status and diffs (git diff HEAD --name-only) to list modified config, bin, and public files and flags them for manual merge.
