From rails-agent-skills
Stabilizes Rails engines across Ruby and Rails versions: configures Zeitwerk autoloading, gemspec dependency bounds, feature detection over version branching, and CI matrices for cross-version testing.
npx claudepluginhub igmarin/rails-agent-skills --plugin rails-agent-skillsThis skill uses the workspace's default tool permissions.
**Core principle:** Every claimed Rails/Ruby version must be in the CI matrix. Prefer explicit support targets over accidental compatibility.
Reviews Rails engines, mountable engines, and Railties for namespace boundaries, host-app integration, safe initialization, migrations, generators, and dummy app test coverage. Prioritizes architectural risks.
Analyzes Rails applications and generates upgrade reports with breaking changes, deprecations, and step-by-step migration guides from 2.3 to 8.1. Use for incremental upgrades and version queries.
Analyzes Rails apps to assess upgrades to latest version, summarizing official guides, railsdiff.org file changes, upgrade types, and JS dependencies.
Share bugs, ideas, or general feedback.
Core principle: Every claimed Rails/Ruby version must be in the CI matrix. Prefer explicit support targets over accidental compatibility.
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.
| Compatibility Aspect | Check |
|---|---|
| Zeitwerk | File paths match constant names; no anonymous or root-level constants |
| Gemspec bounds | add_dependency and required_ruby_version match tested versions |
| Feature detection | Use respond_to?, defined?, or adapter seams instead of Rails.version |
| Test matrix | CI runs against each claimed Rails/Ruby combination |
bundle exec rake zeitwerk:check — file paths must match constant names exactly.config.to_prepare for reload-sensitive hooks.spec.add_dependency "rails", ">= 7.0", "< 8.0" — bounds must match what CI actually tests.strategy:
matrix:
include:
- { ruby: "3.2", rails: "7.1" }
- { ruby: "3.3", rails: "7.2" }
| Problem | Correct approach |
|---|---|
Rails.version branching | Use respond_to?, defined?, or adapter seams — version checks are brittle |
| Zeitwerk file/constant mismatch | File path must mirror constant name exactly — my_engine/widget_policy.rb → MyEngine::WidgetPolicy |
| Broad gemspec constraints without CI | Claiming >= 5.2 without testing 5.2/6.x is silent incompatibility |
| No version bounds in gemspec | Unbounded constraints allow breaking upgrades into the engine |
| Reload-unsafe hooks at load time | Move to config.to_prepare — it runs on each reload in development |
| Tests only on one Rails version | CI matrix required before claiming multi-version support |
# ❌ 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
If an EXAMPLES.md is present in the repository, consult it for additional patterns covering gemspec bounds, Zeitwerk file/constant naming, reload-safe hooks, and CI matrix YAML. If not, the Pitfalls table and Key Example above cover the most common cases.
When asked to improve compatibility:
| Skill | When to chain |
|---|---|
| rails-engine-testing | Test matrix setup, CI configuration, multi-version tests |
| rails-engine-author | Engine structure, host contract, namespace design |
| rails-engine-release | Versioning, changelog, upgrade notes for compatibility changes |
The following supplementary files may be present in the repository. Consult them if available; the skill body above is self-contained if they are not.