Rails Upgrade Analyzer
Analyzes your Rails app's upgrade path: detects the current version, fetches the latest release and official guides, and upgrades files via selective merging that preserves local customizations.
SKILL.md requires detecting local customizations, presenting a plan, and explicit user confirmation before writes; emphasizes no overwriting and git-based reversibility—good safety posture. However, it executes shell commands directly (rails new, file overwrites, db:migrate) and relies on gh CLI auth state; confirmation and isolation rest on prose only, with no automated backup or explicit permission boundary—9 deducted.
Steps are clearly sequenced with error handling (gh not authenticated, missing railsdiff versions falling back to major.minor.0, already-latest case) and verification steps, giving diagnosable failure feedback; but this is static review with no tests or reproduction of key paths (WebFetch fetches, selective merge)—10 deducted.
Trigger scenario is clear (inside a Rails project, /rails-upgrade), name matches capability, and upgrade-type/complexity criteria are explicit; but it depends on gh CLI plus guides.rubyonrails.org and railsdiff.org with no disclosure of reachability from mainland-China networks—6 deducted.
README covers installation (Claude Code/OpenCode), prerequisites, example output, and declares MIT; but there is no version number, changelog, or stated maintenance/update path, license metadata is absent at the skill level, and some steps rely on vague notions like a 'mental list'—6 deducted.
The selective-merge process offers clear marginal value over running rails app:update directly, and outputs (summary tables, upgrade plans) appear directly usable; but with zero execution evidence, correctness and completeness of representative outputs are unverified—9 deducted.
Claims cite traceable primary sources (official upgrade guide, railsdiff, GitHub releases) and facts vs. recommendations are reasonably separated; but there are no tests, CI, or third-party execution evidence, and example output is author-written—6 deducted.
- The skill executes shell commands and overwrites files; run it only in a clean git working tree so changes are revertible.
- Depends on gh CLI auth and overseas sites (guides.rubyonrails.org, railsdiff.org); may be unreachable from mainland-China networks.
- No version number or changelog; update tracking relies on repo history. Publisher is not verified by FollowSkills.
- All upgrade guidance is unverified by execution; review generated merge plans manually before applying.
What does this skill do, and when should you use it?
This Agent Skill analyzes the upgrade path for Rails applications from the current version to the latest release. It verifies project structure, reads the version from Gemfile.lock, fetches the latest Rails release via the GitHub CLI, retrieves the official upgrade guide and railsdiff.org diffs, and produces an upgrade summary with a Small/Medium/Large complexity rating. Its standout feature is a selective merge process that replaces `rails app:update`, categorizing each changed file as new, safe to overwrite, or needing manual merge so local customizations are never clobbered. It suits developers using Claude Code or OpenCode with an authenticated GitHub CLI.
Checks for Gemfile, config/application.rb and config/environment.rb to confirm a Rails app; extracts the current Rails version from Gemfile.lock; queries gh api repos/rails/rails/releases/latest for the latest version and classifies the upgrade as patch/minor/major; fetches the official upgrade guide from guides.rubyonrails.org and version diffs from railsdiff.org; audits Rails-related JS dependencies (@hotwired, @rails) across npm, yarn or importmap; generates a summary with complexity rating and recommended steps; builds an upgrade plan sorting files into new, safe-to-overwrite, manual-merge and skip categories; performs merges that keep local settings and drop deprecated ones; finally helps enable new framework defaults and update config.load_defaults.
- Ruby developers maintaining a long-lived Rails project that needs to move from 7.1 to 8.x.
- Team leads worried that `rails app:update` would overwrite customizations in i18n, mailer or bin/dev files.
- Tech leads sizing an upgrade and needing a Small/Medium/Large complexity verdict.
- Frontend maintainers who must keep Turbo, Stimulus and ActionCable packages aligned with the Rails version.
- Developers tracking which migrations and framework-default flips remain after a merge.
What are this skill's strengths and limitations?
- Replaces `rails app:update` with a selective merge that classifies files per-file and preserves local customizations.
- Draws on authoritative sources: the official Rails upgrade guide and railsdiff.org diffs.
- Checks Rails-related JS packages (Turbo, Stimulus, ActionCable) in addition to Ruby dependencies.
- Provides a Small/Medium/Large complexity rating useful for planning.
- Emphasizes transparency and reversibility: shows the plan first, and changes can be restored via git checkout.
- Requires an authenticated GitHub CLI; you must run `gh auth login` first if it isn't.
- railsdiff.org may lack an exact version pair; the skill only falls back to major.minor.0.
- No test suite or CI evidence in the repo; just an MIT license claim and no documented user feedback beyond the README.
- File operations and migrations depend on the hosting agent's shell execution permissions.
- Analysis quality is bounded by the skill's scripted flow — the final upgrade decision and merge quality rest with the user.
How do you install this skill?
Prerequisite: install and authenticate the GitHub CLI (gh auth login). Claude Code: run mkdir -p ~/.claude/skills, then git clone https://github.com/robzolkos/skill-rails-upgrade.git ~/.claude/skills/rails-upgrade, and restart Claude Code. OpenCode: run mkdir -p ~/.config/opencode/skill, clone into ~/.config/opencode/skill/rails-upgrade, and restart OpenCode.
How do you use this skill?
Navigate to a Rails project directory and invoke /rails-upgrade. The skill verifies your project, detects the current version, fetches the latest release and diffs, then reports version info, a complexity rating, key changes and recommended steps. File-modifying upgrade plans require your confirmation before execution; it will run commands such as gh, npm/bin/importmap, bin/rails db:migrate and bin/rails test along the way.