Agent skill

Rails Upgrade Assistant

by ombulabs in ombulabs/claude-code_rails-upgrade-skill

Analyzes a Rails app and builds an upgrade report with breaking changes, deprecations and step-by-step migration guides, one version at a time from Rails 2.3 through 8.1.

MITAuto-check passedDevelopment

Install Rails Upgrade Assistant

skills CLI
$ npx skills add ombulabs/claude-code_rails-upgrade-skill --skill rails-upgrade -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ombulabs/claude-code_rails-upgrade-skill rails-upgrade --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/ombulabs/claude-code_rails-upgrade-skill.git skills-src && mkdir -p .claude/skills && cp -r skills-src/rails-upgrade .claude/skills/rails-upgrade && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
rails-upgrade
GitHub stars
391
Token cost
~2.7k tokens
SKILL.md length
1,063 words
Files
71 (incl. references)
Skills in repo
2
Repo updated
First seen
Licence
MIT

At a glance

Analyzes a Rails app and builds an upgrade report with breaking changes, deprecations and step-by-step migration guides, one version at a time from Rails 2.3 through 8.1.

  • Works in 7 steps: Incremental Upgrades - Always upgrade… → Assessment First - Understand scope… → Dual-Boot Testing - Test both versions… → …
  • Upgrading a Rails application to a newer version
  • SKILL.md covers Skill Identity, Terminology, Dependencies and Core Methodology (FastRuby.io…, plus 4 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

The skill follows the FastRuby.io methodology: upgrade sequentially with no version skipping, assess the scope first, test both versions side by side in a dual-boot setup using the next_rails gem, and make sure test coverage is adequate before starting, aiming for 80% or more. It is organized as numbered workflow files with examples and on-demand reference files, plus detection patterns for each Rails version.

Two companion skills are named as dependencies: a dual-boot skill, which must be installed for the dual-boot setup workflow, and a rails-load-defaults skill, used as the final step after the version upgrade to update load_defaults in tiers of risk. You can also use the skill to look up version-specific changes or to plan a multi-hop upgrade.

When your agent uses it

  • Upgrading a Rails application to a newer version
  • Planning a multi-hop upgrade across several Rails versions
  • Looking up breaking changes and deprecations for a specific Rails version
  • Setting up dual boot for a gradual upgrade

Example prompts

  • “Analyze our Rails app and produce an upgrade report for the next minor version.”
  • “Plan the upgrade path from our current Rails version to 8.1, one hop at a time.”
  • “What breaking changes should I expect when moving this app up one version?”
  • “Set up dual boot with next_rails for our upgrade.”

Requirements

  • A Rails application with adequate test coverage
  • The dual-boot skill for the dual-boot setup workflow

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

  1. Incremental Upgrades - Always upgrade one minor/major version at a time
  2. Assessment First - Understand scope before making changes
  3. Dual-Boot Testing - Test both versions during transition using next_rails gem
  4. Test Coverage - Ensure adequate test coverage before upgrading (aim for 80%+)
  5. Gem Compatibility - Check gem compatibility at each step using RailsBump
  6. Deprecation Warnings - Address deprecations before upgrading
  7. Backwards Compatible Changes - Deploy small changes to production before version bump

What it can do on your machine

Read from SKILL.md and the folder at commit 8d13113. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Rails Upgrade Assistant loads about 2.7k tokens when it runs, and up to ~18k if it reads all its reference files. Until then it costs about 93 tokens; SKILL.md has 1,063 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~93
When it runs · the whole SKILL.md, loaded when a task matches
~2.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~18k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from ombulabs/claude-code_rails-upgrade-skill at commit 8d13113, republished under its MIT licence (© ombulabs). 1,063 words, ~2,709 tokens.

Download SKILL.mdSave it as .claude/skills/rails-upgrade/SKILL.md (or your agent's skills folder). This skill also uses 70 other files; get the full folder from GitHub.
name
rails-upgrade
description
Analyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 2.3 through 8.1. Use when upgrading Rails applications, planning multi-hop upgrades, or querying version-specific changes. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook.

Rails Upgrade Assistant Skill

Skill Identity

  • Name: Rails Upgrade Assistant
  • Purpose: Intelligent Rails application upgrades from 2.3 through 8.1
  • Skill Type: Modular with external workflows and examples
  • Upgrade Strategy: Sequential only (no version skipping)
  • Methodology: Based on FastRuby.io upgrade best practices and "The Complete Guide to Upgrade Rails" ebook
  • Attribution: Content based on "The Complete Guide to Upgrade Rails" by FastRuby.io (OmbuLabs)

Terminology

TermMeaningWhere
WorkflowOne numbered unit of the upgrade flow, one fileworkflows/<NN>-<name>-workflow.md
StepA Step N header inside a workflow fileinside the workflow
ReferenceMaterial loaded on demand: lookup tables, playbooks, conditional branchesreferences/<name>-reference.md

No sub-steps: a "Step 4.1" is either two sequential steps or a conditional branch inside one step (### A. / ### B. headers). Refer to a whole workflow as Workflow NN; refer to a step as file path plus step, e.g. workflows/01-run-test-suite-workflow.md Step 4. Not used in headings: Stage, Phase, Sub-step, dotted step numbers.


Dependencies

  • dual-boot skill (github.com/ombulabs/claude-code_dual-boot-skill) — Sets up and manages dual-boot environments using the next_rails gem. Covers setup, NextRails.next? code patterns, CI configuration, and post-upgrade cleanup. Must be installed for Workflow 04.
    • Workflow 04 file: workflows/04-setup-next-rails-workflow.md
  • rails-load-defaults skill (github.com/ombulabs/claude-code_rails-load-defaults-skill) — Handles incremental load_defaults updates with tiered risk assessment (Tier 1: low-risk, Tier 2: needs codebase grep, Tier 3: requires human review). Used as the final step after the Rails version upgrade is complete.

Core Methodology (FastRuby.io Approach)

This skill follows the proven FastRuby.io upgrade methodology:

  1. Incremental Upgrades - Always upgrade one minor/major version at a time
  2. Assessment First - Understand scope before making changes
  3. Dual-Boot Testing - Test both versions during transition using next_rails gem
  4. Test Coverage - Ensure adequate test coverage before upgrading (aim for 80%+)
  5. Gem Compatibility - Check gem compatibility at each step using RailsBump
  6. Deprecation Warnings - Address deprecations before upgrading
  7. Backwards Compatible Changes - Deploy small changes to production before version bump

Key Resources:

  • DELEGATE to the dual-boot skill for dual-boot setup with next_rails (see Dependencies)
  • See references/deprecation-warnings-reference.md for managing deprecations
  • See references/staying-current-reference.md for maintaining upgrades over time

CRITICAL: Dual-Boot Code Pattern with NextRails.next?

When proposing code fixes that must work with both the current and target Rails versions (dual-boot), always use NextRails.next? from the next_rails gem — never use respond_to? or other feature-detection patterns.

DELEGATE to the dual-boot skill for:

  • Setup and initialization (next_rails --init, Gemfile.next)
  • NextRails.next? code patterns and examples
  • CI configuration for dual-boot testing
  • Post-upgrade cleanup (removing dual-boot branches)

DEPENDENCY: Requires the dual-boot skill


Available Resources

Core Documentation
  • SKILL.md - This file (entry point)
Version-Specific Guides (Load as needed)

Legacy Rails:

  • version-guides/upgrade-3.2-to-4.0.md - Rails 3.2 → 4.0 (Strong Parameters)
  • version-guides/upgrade-4.0-to-4.1.md - Rails 4.0 → 4.1 (Spring, secrets.yml, enums)
  • version-guides/upgrade-4.1-to-4.2.md - Rails 4.1 → 4.2 (ActiveJob, Web Console)
  • version-guides/upgrade-4.2-to-5.0.md - Rails 4.2 → 5.0 (ApplicationRecord)

Modern Rails:

  • version-guides/upgrade-5.0-to-5.1.md - Rails 5.0 → 5.1 (Encrypted secrets)
  • version-guides/upgrade-5.1-to-5.2.md - Rails 5.1 → 5.2 (Active Storage, Credentials)
  • version-guides/upgrade-5.2-to-6.0.md - Rails 5.2 → 6.0 (Zeitwerk)
  • version-guides/upgrade-6.0-to-6.1.md - Rails 6.0 → 6.1 (Horizontal sharding)
  • version-guides/upgrade-6.1-to-7.0.md - Rails 6.1 → 7.0 (Hotwire/Turbo)
  • version-guides/upgrade-7.0-to-7.1.md - Rails 7.0 → 7.1 (Composite keys)
  • version-guides/upgrade-7.1-to-7.2.md - Rails 7.1 → 7.2 (Transaction jobs)
  • version-guides/upgrade-7.2-to-8.0.md - Rails 7.2 → 8.0 (Propshaft)
  • version-guides/upgrade-8.0-to-8.1.md - Rails 8.0 → 8.1 (bundler-audit)
Examples (Load when user needs clarification)
  • examples/simple-upgrade.md - Single-hop upgrade example
  • examples/multi-hop-upgrade.md - Multi-hop upgrade example
External Dependencies
Reference Materials
  • references/sequential-strategy-reference.md - Sequential upgrade rule (no version skipping) and the supported upgrade paths tables. Load in Workflow 03.
  • references/request-patterns-reference.md - Which workflows run for each request shape (full upgrade, multi-hop, analysis only, reports only). Read at the start of a session.
  • references/no-test-suite-smoke-reference.md - Load from Workflow 01 when no runnable RSpec/Minitest suite exists - Rails boot, routes, migration-status, and build smoke baseline with partial-confidence reporting
  • references/deprecation-warnings-reference.md - Finding and fixing deprecations
  • references/staying-current-reference.md - Keeping up with Rails releases
  • references/breaking-changes-by-version-reference.md - Quick lookup
  • references/multi-hop-strategy-reference.md - Multi-version planning
  • references/testing-checklist-reference.md - Comprehensive testing
  • references/gem-compatibility-reference.md - Gem update order and the "no compatible version" playbook (fork / vendor / replace). Load only when Workflow 06's compatibility check produced blockers.
  • references/js-compressor-sprockets-mismatch-reference.md - Keeping terser / closure-compiler working when the target Rails pins Sprockets to the 2.x line. Load only when JS_COMPRESSOR_GEM_MISMATCH fires.
Show full SKILL.md (388 more words)Show less
Detection Pattern Resources
  • detection-scripts/patterns/rails-*.yml - Version-specific patterns for direct detection
  • detection-scripts/scan_patterns.rb - Runs every pattern for a hop against the app and prints a findings table. Run it in Workflow 05 instead of one Grep per pattern.
Report Templates
  • templates/upgrade-report-template.md - Main upgrade report structure
  • templates/app-update-preview-template.md - Configuration preview

Workflow index

When user requests an upgrade, follow this workflow. Sequential Process is Critical: run in order, read each file when you reach it. Gates block.

#NamePurposeFile
00Verify latest patchMANDATORY PRE-STEP. App on the latest patch of its current series before any minor/major hopworkflows/00-verify-latest-patch-workflow.md
01Run test suiteMANDATORY FIRST STEP. How to run and verify test suite; blocks on any failureworkflows/01-run-test-suite-workflow.md
02Resolve deprecation warningsMake warnings visible, collect what the current version emits, fix them on the current versionworkflows/02-resolve-deprecation-warnings-workflow.md
03Validate upgrade pathSingle-hop or multi-hop, individual hops plannedworkflows/03-validate-upgrade-path-workflow.md
04Set up next_railsEARLY SETUP. Delegated to the skill listed under External Dependenciesworkflows/04-setup-next-rails-workflow.md
05Detect breaking changesHow to run breaking change detection directlyworkflows/05-detect-breaking-changes-workflow.md
06Check gem compatibilityPer-lockfile gem compatibility check against the target Rails versionworkflows/06-check-gem-compatibility-workflow.md
07Boot smoke testBoot under Gemfile.next and run the models suite there, to catch what the resolver and the grep can't seeworkflows/07-boot-smoke-test-workflow.md
08Generate upgrade reportHow to generate upgrade reportsworkflows/08-generate-upgrade-report-workflow.md
09Generate app:update previewHow to generate app:update previewsworkflows/09-generate-app-update-preview-workflow.md
10Implement and upgradePresent reports, apply fix-before-bump changes, bump the Gemfile, run tests against both versionsworkflows/10-implement-and-upgrade-workflow.md
11Sync CI configMANDATORY before opening the upgrade PR. How to verify CI config matches the upgraded Gemfileworkflows/11-sync-ci-workflow.md
12Align load_defaultsAFTER THE UPGRADE IS COMPLETE. Delegates to the rails-load-defaults skillworkflows/12-align-load-defaults-workflow.md
13Mention cleanupUSER-TRIGGERED. Delegates to the upgrade-cleanup plugin only when the user explicitly asksworkflows/13-mention-cleanup-workflow.md

The Purpose column is a summary. Gates live only in each workflow's ## Gates section. Which workflows run depends on the request shape (full upgrade, multi-hop, analysis only, reports only): references/request-patterns-reference.md.


Key Principles

  1. Run Detection Directly (run detection-scripts/scan_patterns.rb, then Read the affected files; never generate a detection script for the user to run)
  2. Load Workflows as Needed (don't hold everything in memory)
  3. Follow FastRuby.io Methodology (incremental upgrades, assessment first)

Everything else that used to be listed here lives in the workflow it governs: see each workflow's Purpose and Gates.

© ombulabs, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 70 other files (references) in rails-upgrade of ombulabs/claude-code_rails-upgrade-skill.

  • SKILL.md
  • detection-scripts/patterns/rails-40-patterns.expectations.yml
  • detection-scripts/patterns/rails-40-patterns.yml
  • detection-scripts/patterns/rails-41-patterns.expectations.yml
  • detection-scripts/patterns/rails-41-patterns.yml
  • detection-scripts/patterns/rails-42-patterns.yml
  • detection-scripts/patterns/rails-50-patterns.expectations.yml
  • detection-scripts/patterns/rails-50-patterns.yml
  • detection-scripts/patterns/rails-51-patterns.expectations.yml
  • detection-scripts/patterns/rails-51-patterns.yml
  • detection-scripts/patterns/rails-52-patterns.expectations.yml
  • detection-scripts/patterns/rails-52-patterns.yml
  • detection-scripts/patterns/rails-60-patterns.expectations.yml
  • detection-scripts/patterns/rails-60-patterns.yml
  • detection-scripts/patterns/rails-70-patterns.expectations.yml
  • detection-scripts/patterns/rails-70-patterns.yml
  • detection-scripts/patterns/rails-71-patterns.expectations.yml
  • detection-scripts/patterns/rails-71-patterns.yml
  • detection-scripts/patterns/rails-72-patterns.expectations.yml
  • … and 52 more

Open the folder on GitHubat commit 8d13113

Compare with similar skills

Rails Upgrade Assistant next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Rails Upgrade Assistant compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Rails Upgrade Assistant this skillombulabs/claude-code_rails-upgrade-skill391—~2.7kAutomated safety check: PassMIT
Legacy ModernizerJeffallan/claude-skills12k—~1.6kAutomated safety check: PassMIT
Code Refactoring Workflowluongnv89/claude-howto42k—~3.1kAutomated safety check: PassMIT
Convert Internal Package to TypeScriptTryGhost/Ghost56k—~1.2kAutomated safety check: PassMIT
jscpd Code Migration Trackerkucherenko/jscpd6.4k—~5kAutomated safety check: PassMIT
OBS Plugin Dependency Upgradesorayuki/obs-multi-rtmp5.1k—~609Automated safety check: PassGPL-2.0

Similar skills

  • Legacy Modernizer

    Jeffallan/claude-skills

    Plans incremental migrations of aging systems with the strangler fig pattern, using dependency maps, rollback plans, characterization tests and gradual traffic shifts.

    12k GitHub stars~1.6k tokensUpdated 6 days ago
    DevelopmentAuto-check passed
  • Code Refactoring Workflow

    luongnv89/claude-howto

    Guides systematic, test-backed refactoring in the style of Martin Fowler, moving through research, planning and small incremental changes with your approval at each phase.

    42k GitHub stars~3.1k tokensUpdated 10 days ago
    DevelopmentAuto-check passed
  • Moves a legacy internal Ghost package from JavaScript and CommonJS to TypeScript and ESM in three focused commits that keep git file history intact.

    56k GitHub stars~1.2k tokensUpdated today
    DevelopmentAuto-check passed
  • Measures a code port between languages or frameworks with jscpd's function-level comparison, porting tests before code and tracking what is left unmatched.

    6.4k GitHub stars~5k tokensUpdated today
    DevelopmentAuto-check passed
  • OBS Plugin Dependency Upgrade

    sorayuki/obs-multi-rtmp

    Updates the obs-multi-rtmp plugin repo to the latest upstream plugin template and OBS Studio version, including dependency metadata, then rebuilds it with CMake.

    5.1k GitHub stars~609 tokensUpdated 8 days ago
    DevelopmentAuto-check passed
  • CLIProxy Core Sync

    caidaoli/ccLoad

    Syncs or audits ccLoad's CLIProxyAPI protocol-conversion core and registered provider adapters against one pinned upstream commit, then verifies the result.

    419 GitHub stars~1.5k tokensUpdated today
    DevelopmentAuto-check passed

More from ombulabs/claude-code_rails-upgrade-skill

  • Rails Upgrade Cleanup

    ombulabs/claude-code_rails-upgrade-skill

    Finishes or abandons a dual-boot Rails upgrade by removing NextRails branches and Gemfile.next scaffolding, keeping either the next or the current version.

    391 GitHub stars~826 tokensUpdated 9 days ago
    Auto-check passed

Works with

Categories

Questions about Rails Upgrade Assistant

What does Rails Upgrade Assistant do?

Analyzes a Rails app and builds an upgrade report with breaking changes, deprecations and step-by-step migration guides, one version at a time from Rails 2.3 through 8.1. io methodology: upgrade sequentially with no version skipping, assess the scope first, test both versions side by side in a dual-boot setup using the next_rails gem, and make sure test coverage is adequate before starting, aiming for 80% or more. It is organized as numbered workflow files with examples and on-demand reference files, plus detection patterns for each Rails version.

When should I use Rails Upgrade Assistant?

Rails Upgrade Assistant fits situations like: upgrading a Rails application to a newer version; planning a multi-hop upgrade across several Rails versions; looking up breaking changes and deprecations for a specific Rails version; setting up dual boot for a gradual upgrade.

How do I install Rails Upgrade Assistant in Claude Code?

Run `npx skills add ombulabs/claude-code_rails-upgrade-skill --skill rails-upgrade -a claude-code`. Or copy the skill folder (rails-upgrade in ombulabs/claude-code_rails-upgrade-skill) into .claude/skills/rails-upgrade in your project. Claude Code loads it when a task matches its description.

How do I install Rails Upgrade Assistant in Codex?

Run `npx skills add ombulabs/claude-code_rails-upgrade-skill --skill rails-upgrade -a codex`. Or copy the skill folder (rails-upgrade in ombulabs/claude-code_rails-upgrade-skill) into .agents/skills/rails-upgrade in your project. Codex loads it when a task matches its description.

Can I use Rails Upgrade Assistant in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ombulabs/claude-code_rails-upgrade-skill --skill rails-upgrade -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/rails-upgrade, .gemini/skills/rails-upgrade, .github/skills/rails-upgrade and .opencode/skills/rails-upgrade in your project.

What does Rails Upgrade Assistant need to run?

SKILL.md names no scripts, command-line tools or credentials: Rails Upgrade Assistant is instructions for the agent only. Our summary lists: A Rails application with adequate test coverage; The dual-boot skill for the dual-boot setup workflow.

Does Rails Upgrade Assistant access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is Rails Upgrade Assistant safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Rails Upgrade Assistant use?

Rails Upgrade Assistant is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Rails Upgrade Assistant use?

About 2.7k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 15k tokens, read only when the agent opens those files.

What are the alternatives to Rails Upgrade Assistant?

Skills that share tags, products or a category with Rails Upgrade Assistant: Legacy Modernizer (Jeffallan/claude-skills, 12k stars), Code Refactoring Workflow (luongnv89/claude-howto, 42k stars), Convert Internal Package to TypeScript (TryGhost/Ghost, 56k stars) and jscpd Code Migration Tracker (kucherenko/jscpd, 6.4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Rails Upgrade Assistant?

ombulabs (a GitHub organization) maintains it in ombulabs/claude-code_rails-upgrade-skill, which has 391 GitHub stars. The repository holds 2 skills in this directory. The repository was last updated on October 1, 2026.

Source: ombulabs/claude-code_rails-upgrade-skill on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.