Upgrade engine

Skill igmarin/rails-agent-skills/skills/engines/upgrade-engine

This is my personal configuration of skills as a Ruby on Rails Dev

Install

npx -y skills add igmarin/rails-agent-skills --skill upgrade-engine

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

22 stars22 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when making a Rails engine stable across Rails and Ruby versions, performing a Rails upgrade, verifying gem compatibility, adding version support, or setting up cross-version testing — must ensure every claimed version is in the CI matrix and passes, run bundle exec rake zeitwerk:check verifying that file paths match constant names exactly, verify gemspec dependency bounds match what CI actually tests, check initializer reloading safety using config.to_prepare, and check and state the status of optional integrations per version even if they are absent. Zeitwerk autoloading, gemspec dependency bounds, CI matrix, Rails upgrade, gem compatibility, version support.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.7 KB, as published. Nobody here has run it

Upgrade Engine

Core principle: Every claimed Rails/Ruby version must be in the CI matrix. Prefer explicit support targets over accidental compatibility.

HARD-GATE

Before claiming support for a Rails/Ruby version:
  1. bundle exec rake zeitwerk:check        # verify autoloading on each version
  2. bundle exec rspec                       # full suite per matrix version
  3. CI matrix must pass — not just main Rails version

DO NOT ship compatibility changes without verifying both autoloading and full suite.

Core Process

Define supported Ruby and Rails versions — state them in gemspec and README.
Run bundle exec rake zeitwerk:check — file paths must match constant names exactly (e.g. my_engine/widget_policy.rb → MyEngine::WidgetPolicy).
Check initializer behavior across boot and reload — use config.to_prepare for reload-sensitive hooks; hooks placed at load time are reload-unsafe in development.
Verify gemspec dependency bounds match tested versions: spec.add_dependency "rails", ">= 7.0", "< 8.0" — bounds must reflect what CI actually tests. Unbounded or overclaiming constraints (>= 5.2 without testing 5.2/6.x) are silent incompatibilities.
Replace Rails.version branching with feature detection — version checks are brittle across patch releases:

# ❌ Bad — brittle, wrong for patch versions
if Rails.version >= "7.0"
  config.active_support.cache_format_version = 7.0
end

# ✅ Good — detect the capability directly
if ActiveSupport::Cache.respond_to?(:format_version=)
  config.active_support.cache_format_version = 7.0
end

Check optional integrations (jobs, mailers, assets, routes, install generators, dummy-app mounts) per version. State the check even if an integration is absent.
CI matrix must run against each claimed Rails/Ruby combination:

strategy:
  matrix:
    include:
      - { ruby: "3.2", rails: "7.1" }
      - { ruby: "3.3", rails: "7.2" }

Extended Resources

Output Style

State the support matrix being targeted.
List the most likely breakpoints.
Make compatibility changes in isolated, testable seams.
Recommend matrix coverage if it does not exist.
Include an Optional integration matrix with rows for jobs, mailers, assets, routes, generators, and dummy app mount. For each row, state present/absent, the file path checked, and the per-version verification command.
Language — Must be in English unless explicitly requested otherwise.

Integration

Skill	When to chain
test-engine	Test matrix setup, CI configuration, multi-version tests
create-engine	Engine structure, host contract, namespace design
release-engine	Versioning, changelog, upgrade notes for compatibility changes