maquina-app/rails-upgrade-skill
Overview
This skill automates Rails application upgrades by generating targeted detection scripts and producing step-by-step upgrade reports for Rails 7.0 through 8.1.1. It detects breaking changes and deprecations in your codebase, then creates migration guides and an app:update preview based on actual findings. The workflow enforces sequential upgrades and produces file:line references for every issue.
How this skill works
I generate a version-specific bash detection script that scans your project for known breaking-change patterns and outputs a findings file with file:line references. After you run the script and share the findings, I parse the results, read relevant config and source files, and produce two deliverables: a Comprehensive Upgrade Report (with OLD vs NEW examples, flagged custom-code warnings, migration steps, tests and rollback plan) and an app:update Preview (exact config diffs, new files, and impact assessment).
When to use it
- Before starting any Rails upgrade to identify concrete issues in your codebase
- When planning multi-hop upgrades (enforced sequential hops only)
- To generate a detection script for a specific target Rails version
- After running a detection script to get precise migration steps and config diffs
- When you need Neovim-ready file lists or line-accurate guidance for fixes
Best practices
- Always follow the required sequential upgrade path (7.0 → 7.1 → 7.2 → 8.0 → 8.1)
- Run the generated detection script in your project root and share the findings.txt
- Complete each hop fully before moving to the next hop in multi-hop upgrades
- Review flagged ⚠️ custom-code items first—these usually require manual attention
- Use the app:update Preview to validate config changes in a branch before merging
Example use cases
- Create a detection script for upgrading from Rails 7.1 to 7.2 and run it to locate breaking calls
- Share rails_8.1_upgrade_findings.txt and receive a Comprehensive Upgrade Report with code-level fixes
- Plan a multi-hop upgrade from 7.0 to 8.1: generate scripts and reports per hop
- Request only the app:update Preview after running the detection script to view exact config diffs
- Obtain a Neovim buffer-ready list of affected files for quick in-editor fixes
FAQ
No. Upgrades must be sequential. I will break multi-hop upgrades into individual hops and generate separate scripts and reports for each.
Do reports use my real code?
Yes. Reports are generated from the actual findings file and read your project files to include real code examples, file:line references, and custom-code warnings.
