rails-upgrade — Claude Code skill: what it does, how to install
Evaluates Rails version bumps, checks JS assets, and guides selective configuration merging without wiping custom code.
npx skills add robzolkos/skill-rails-upgrade --skill rails-upgrade -a claude-codeWhat rails-upgrade does
The skill validates your project by looking for Gemfile, config/application.rb, and config/environment.rb, then extracts the installed version from Gemfile.lock. It queries the Rails repository using GitHub CLI to find the newest release tag and categorizes the jump as patch, minor, or major.
Next, it pulls relevant upgrade guides and fetches boilerplate changes from railsdiff.org. The workflow also audits frontend packages across package.json or config/importmap.rb, targeting libraries like @hotwired/turbo-rails and @rails/actioncable. Without GitHub CLI configured in your shell, fetching remote tags will fail.
Instead of invoking rails app:update blindly, the skill emphasizes careful file updates. This preserves custom initializers and local modifications while bringing default configs and migrations up to date.
What it helps with
- Assess Rails upgrade difficulty between current and target releases
- Inspect config differences via railsdiff.org without overwriting customizations
- Check version alignment for npm and importmap JavaScript dependencies
- Outline required migrations and deprecation cleanup steps
Example prompts for the agent
- Check my Rails version and generate an upgrade roadmap to the latest release
- Inspect package.json and config/importmap.rb for outdated Rails JavaScript packages
- Show the diff for default Rails configuration files without overwriting local changes
How to install rails-upgrade
1Skills CLI (Vercel)
npx skills add robzolkos/skill-rails-upgrade --skill rails-upgrade -a claude-code2Manually: put the files in place
~/.claude/skills/rails-upgrade/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/rails-upgrade/
1Skills CLI (Vercel)
npx skills add robzolkos/skill-rails-upgrade --skill rails-upgrade -a codex2Manually: put the files in place
.agents/skills/rails-upgrade/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add robzolkos/skill-rails-upgrade --skill rails-upgrade -a cursor2Manually: put the files in place
.cursor/skills/rails-upgrade/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install robzolkos/skill-rails-upgrade rails-upgrade2Manually: put the files in place
.github/skills/rails-upgrade/SKILL.md1Skills CLI (Vercel)
npx skills add robzolkos/skill-rails-upgrade --skill rails-upgrade -a gemini-cli2Platform CLI
gemini skills install https://github.com/robzolkos/skill-rails-upgradeManually: put the files in place
.devin/skills/rails-upgrade/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add robzolkos/skill-rails-upgrade --skill rails-upgrade -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about rails-upgrade
How to install rails-upgrade in Claude Code?
Run npx skills add robzolkos/skill-rails-upgrade --skill rails-upgrade -a claude-code. The skill will be placed in ~/.claude/skills/rails-upgrade/SKILL.md.
What does the rails-upgrade skill do?
It inspects installed gem versions, queries releases, reviews official upgrade guides, and inspects file diffs alongside JavaScript packages.
Why does this skill avoid running rails app:update?
Default app update tasks overwrite customized configuration files, whereas this skill promotes selective merging to preserve project-specific edits.
