CtrlK
BlogDocsLog inGet started
Tessl Logo

igmarin/rails-agent-skills

Curated library of AI agent skills for Ruby on Rails development. Covers code review, architecture, security, testing (RSpec), engines, service objects, DDD patterns, and workflow automation.

73

Quality

91%

Does it follow best practices?

Impact

—

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

SKILL.mdrails-engine-installers/

name:
rails-engine-installers
description:
Use when creating install generators, copied migrations, or initializer installers for Rails engines. Covers idempotent setup tasks, host-app onboarding, and route mount setup. Trigger words: install generator, mountable engine setup, gem installation, engine onboarding, rails plugin installer, copy migrations, initializer generator, route mount setup, engine configuration generator.

Rails Engine Installers

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.

Installer Components

ComponentPurposeKey constraint
GeneratorCreates initializer, route mount, or setup filesMust be idempotent — safe to rerun
MigrationsCopies engine migrations into host db/migrateHost owns and runs them; never apply automatically
InitializerProvides configuration defaultsGenerated once, editable by host
RoutesAdds mount Engine, at: '/path'Check for existing mount before injecting

HARD-GATE: Validation Workflow

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.

Constraints

ConstraintDoAvoid
Boot-time mutationConfigure only in initializersModifying host files or state at load time from engine.rb or initializers
IdempotencyGuard with File.exist? or Thor's inject_into_file with a markerOverwriting or inserting routes, initializers, or migrations without checking
MigrationsCopy to host db/migrate; host runs themApplying migrations automatically
Manual stepsDocument rollback steps and required env varsLeaving install gaps undocumented
Docs accuracyMatch install docs to generator behaviorDocs that describe a different install path than the generator produces

Examples

Idempotent install generator — only inject once:

# lib/generators/my_engine/install/install_generator.rb
module MyEngine
  class InstallGenerator < Rails::Generators::Base
    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
      route "mount MyEngine::Engine, at: '/admin'"
    end
  end
end

Generator test — covers single run and idempotent rerun:

RSpec.describe MyEngine::InstallGenerator, type: :generator do
  destination File.expand_path('../../tmp', __dir__)
  before { prepare_destination }

  it 'creates the initializer' do
    run_generator
    expect(file('config/initializers/my_engine.rb')).to exist
  end

  it 'does not duplicate the initializer on rerun' do
    2.times { run_generator }
    content = File.read(file('config/initializers/my_engine.rb'))
    expect(content.scan('MyEngine.configure').size).to eq(1)
  end

  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
end

Generator Checklist

  • Files created in correct host paths
  • No duplicate inserts on rerun (validated manually and in specs)
  • Sensible defaults that are easy to edit
  • Clear output telling the user what remains manual
  • Rollback steps documented
  • Install docs match what the generator actually produces

Output Style

When implementing an install flow:

  1. Identify what must be generated vs. manually configured — state this explicitly.
  2. Implement with idempotency guards for every file, route, and migration copy.
  3. Add generator specs covering single-run and rerun behavior, then write concise user-facing setup instructions.

Integration

SkillWhen to chain
rails-engine-authorWhen designing the engine structure that installers will configure
rails-engine-docsWhen documenting install steps or upgrade instructions
rails-engine-testingWhen adding generator specs or dummy-app install coverage

rails-engine-installers

SKILL.md

README.md

tile.json