igmarin/upgrade-engine
skills/engines/upgrade-engine/SKILL.md
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.
$ install --global
skillsauthnpx skillsauth add igmarin/rails-agent-skills upgrade-engineInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jun 5, 2026, 2:36 AM20.1s5 files scanned
SKILL.md
- name:
- upgrade-engine
- type:
- atomic
- license:
- MIT
- description:
- >
- 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.
- version:
- 1.0.0
- user-invocable:
- true
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_preparefor 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.2without testing 5.2/6.x) are silent incompatibilities. - Replace
Rails.versionbranching 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
- assets/compatibility_matrix.md
- assets/zeitwerk_notes.md
- EXAMPLES.md
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 |
Related Skills
igmarin/rails-agent-skills
development
VerifiedTrustedCommunity
Entry point for Rails development workflows covering TDD, RSpec, Service Objects, DDD, GraphQL, Engines, and Code Quality. Use when the user asks about Ruby on Rails development patterns, needs RSpec test suites generated, wants service objects scaffolded, is setting up GraphQL schemas, performing Rails code review, refactoring .rb files, working with domain-driven design, implementing background jobs, conducting Rails security checks, or building Rails engines. Generates RSpec tests, structures service objects, enforces TDD workflows, configures GraphQL schemas, and coordinates domain-driven design patterns. Trigger keywords: Rails, RSpec, TDD, Rails testing, Rails refactor, Rails API, Rails code review, domain driven design, service objects, GraphQL, Rails engine, Ruby, .rb, background jobs, Rails migrations, Rails security check.
21SKILL.mdUpdated May 18, 2026
igmarin/release-engine
development
VerifiedTrustedCommunity
Use when shipping a Rails engine gem — FIRST run full test suite (`bundle exec rspec`) and fix ALL failures, verify gemspec metadata and dependencies match tested Rails/Ruby versions, dry-run: `gem build *.gemspec && gem push --dry-run *.gem` and verify contents, generate CHANGELOG.md organized by category (added/changed/deprecated/removed/fixed), produce step-by-step upgrade notes with before/after code, set semantic version in `lib/[engine_name]/version.rb`, document deprecations with migration paths, load release assets conditionally and state which one informed the output. Trigger words: version bump, changelog, deprecation, gemspec, upgrade, release, publish gem, ship gem.
21SKILL.mdUpdated May 9, 2026
igmarin/tdd
development
VerifiedTrustedCommunity
Orchestrates the full Rails TDD cycle with hard gates: test MUST exist, be run, and FAIL for the correct reason (e.g. undefined method, not syntax error) before any implementation code — propose minimal implementation and wait for user approval → verify test PASSES → run full suite with rubocop, brakeman, rspec all green → produce YARD documentation and self-reviewed PR; phases context/test design→implementation→iterate→finish. Use when practicing test-driven development, red-green-refactor, TDD workflow, writing tests before code, adding tests first, or building a Rails feature where specs must gate implementation.
19SKILL.mdUpdated Jun 5, 2026
igmarin/setup
development
VerifiedTrustedCommunity
Complete Rails project setup loop with hard gates: verify Ruby version matches .ruby-version, Bundler installed, database connection successful, all env vars loaded, and ALL external CI actions pinned to immutable commit SHAs (never mutable tags like @v4) → configure CI/CD pipeline with linting, testing, and security scanning → validate end-to-end with bundle install, db:create, db:migrate, rspec, and write SETUP_CHECKLIST.md; phases context/onboarding→CI/CD configuration→environment validation. Use when starting a new Rails project, running `rails new`, configuring a Gemfile or .ruby-version, setting up a development environment, or wiring up CI/CD for a Ruby on Rails app. Trigger: setup project, new Rails app, configure CI/CD, dev environment setup, rails new, Gemfile setup, .ruby-version, Ruby on Rails project bootstrap.
19SKILL.mdUpdated Jun 5, 2026