From rails-agent-skills
Guides creation of idempotent install generators for Rails engines, including copied migrations, initializers, route mounts, and host-app onboarding validation.
npx claudepluginhub igmarin/rails-agent-skills --plugin rails-agent-skillsThis skill uses the workspace's default tool permissions.
Use this skill when the task is to design or review how a host app installs and configures a Rails engine — generating initializers, copying migrations, mounting routes, or exposing a single install command.
Guides creating, scaffolding, or refactoring Rails engines, covering types (Plain, Railtie, Engine, Mountable), namespace isolation, host-app contracts, and file structure.
Writes idiomatic Ruby code using metaprogramming, Rails patterns, performance optimization. Specializes in gem development, RSpec/Minitest testing, and RuboCop.
Writes idiomatic Ruby code using metaprogramming, Rails patterns, and performance optimizations. Supports Rails apps, gem development, RSpec/Minitest testing, and refactoring.
Share bugs, ideas, or general feedback.
Use this skill when the task is to design or review how a host app installs and configures a Rails engine — generating initializers, copying migrations, mounting routes, or exposing a single install command.
Core principle: Setup must be explicit, repeatable, and safe to rerun. Never modify the host app at boot time.
| Component | Purpose | Key constraint |
|---|---|---|
| Generator | Creates initializer, route mount, or setup files | Must be idempotent — safe to rerun |
| Migrations | Copies engine migrations into host db/migrate | Host owns and runs them; never apply automatically |
| Initializer | Provides configuration defaults | Generated once, editable by host |
| Routes | Adds mount Engine, at: '/path' | Check for existing mount before injecting |
WHEN building or reviewing an install generator:
1. GENERATE: Run the generator against a clean host app
2. VERIFY: Check output files exist in the correct host paths
3. RERUN: Run the generator a second time
4. CONFIRM: No duplicate files, routes, or initializer blocks inserted
5. DOCUMENT: List what was generated vs. what the user must do manually
6. TEST: Cover both single-run and rerun behavior in generator specs
DO NOT ship a generator without completing steps 3 and 4.
| Constraint | Do | Avoid |
|---|---|---|
| Boot-time mutation | Configure only in initializers | Modifying host files or state at load time from engine.rb or initializers |
| Idempotency | Guard with File.exist? or Thor's inject_into_file with a marker | Overwriting or inserting routes, initializers, or migrations without checking |
| Migrations | Copy to host db/migrate; host runs them | Applying migrations automatically |
| Manual steps | Document rollback steps and required env vars | Leaving install gaps undocumented |
| Docs accuracy | Match install docs to generator behavior | Docs that describe a different install path than the generator produces |
Idempotency guards — check before creating or injecting:
def create_initializer
return if File.exist?(File.join(destination_root, 'config/initializers/my_engine.rb'))
create_file 'config/initializers/my_engine.rb', <<~RUBY
MyEngine.configure do |config|
config.user_class = "User"
end
RUBY
end
def mount_route
# inject_into_file with force: false skips insertion if sentinel already present
inject_into_file 'config/routes.rb',
"\n mount MyEngine::Engine, at: '/admin'\n",
after: "Rails.application.routes.draw do",
force: false
end
Minimal rerun spec (must always pass):
it 'does not duplicate the route mount on rerun' do
2.times { run_generator }
expect(File.read(file('config/routes.rb')).scan('mount MyEngine::Engine').size).to eq(1)
end
See EXAMPLES.md for a full generator class and complete spec suite, including migration copy helpers and multi-step install scenarios.
| Skill | When to chain |
|---|---|
| rails-engine-author | When designing the engine structure that installers will configure |
| rails-engine-docs | When documenting install steps or upgrade instructions |
| rails-engine-testing | When adding generator specs or dummy-app install coverage |