ruby-rails
/ruby-rails
Use this skill when building Ruby on Rails applications — MVC, ActiveRecord, service objects, API mode, background jobs, and testing. This skill enforces: thin controllers, service objects for business logic, ActiveRecord query best practices, Rails API mode conventions, and RSpec testing patterns. Requires Rails 7+ and Ruby 3.1+. Do NOT use for: Sinatra, Rack apps, Hanami, or non-Rails Ruby projects.
- Author
- j4flmao ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 10.10.2026
Assessment and security
- Files in this package
- 9
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 10.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use this skill when building Ruby on Rails applications — MVC, ActiveRecord, service objects, API mode, background jobs, and testing. This skill enforces: thin controllers, service objects for business logic, ActiveRecord query best practices, Rails API mode conventions, and RSpec testing patterns. Requires Rails 7+ and Ruby 3.1+. Do NOT use for: Sinatra, Rack apps, Hanami, or non-Rails Ruby projects.
Original author description
Use this skill when building Ruby on Rails applications — MVC, ActiveRecord, service objects, API mode, background jobs, and testing. This skill enforces: thin controllers, service objects for business logic, ActiveRecord query best practices, Rails API mode conventions, and RSpec testing patterns. Requires Rails 7+ and Ruby 3.1+. Do NOT use for: Sinatra, Rack apps, Hanami, or non-Rails Ruby projects.
How it works
- Purpose
- Agent Protocol
- Architecture Decision Trees
- Workflow
- Implementation Patterns
- Production Considerations
- Anti-Patterns
- Security Considerations
- Testing Strategies
- Rules
SKILL.md preview
---
name: ruby-rails
description: >
Use this skill when building Ruby on Rails applications — MVC, ActiveRecord, service objects, API mode, background jobs, and testing. This skill enforces: thin controllers, service objects for business logic, ActiveRecord query best practices, Rails API mode conventions, and RSpec testing patterns. Requires Rails 7+ and Ruby 3.1+. Do NOT use for: Sinatra, Rack apps, Hanami, or non-Rails Ruby projects.
version: "1.0.0"
author: "j4flmao"
license: "MIT"
compatibility:
claude-code: true
cursor: true
codex: true
windsurf: true
tags: [backend, ruby, rails, phase-4]
---
# Ruby on Rails
## Purpose
Build Rails applications with clean MVC separation, service objects, ActiveRecord optimization, API mode conventions, Sidekiq background jobs, and RSpec testing patterns.
## Agent Protocol
### Trigger
User request includes: `Rails`, `Ruby on Rails`, `Rails API`, `ActiveRecord`, `Rails controller`, `Rails model`, `Rails service`, `Rails job`, `Rails spec`, `Rails migration`.
### Input Context
- Rails version (7.0+, 7.1+)
- Ruby version (3.1+, 3.2+, 3.3+)
- Database (PostgreSQL, MySQL, SQLite)
- Mode (API-only, full MVC)
- Auth (Devise, JWT, OAuth)
- Background jobs (Sidekiq, GoodJob, Solid Queue)
### Output Artifact
Controller, model, service object, job class, migration, RSpec test.
### Response Format
Produce artifact directly. No preamble, no postamble, no explanations.
### Completion Criteria
- Controller delegates to service objects
- ActiveRecord model with scopes, validations, associations
- Service object encapsulates business logic
- Background job with retry configuration
- Request spec covers CRUD with JSON
- Migration with proper indexes
### Max Response Length
4096 tokens
## Architecture Decision Trees
### Service Objects vs PORO Models vs Concerns
| Criterion | Service Object | Fat Model | Concern |
|-----------|---------------|-----------|---------|
| Business logic location | `app/services/` | `app/models/` | `app/concerns/` |
| Testability | Easy (isolated) | Moderate (needs DB) | Moderate |
| Reusability | High (injectable) | Low (AR callbacks) | Medium (mixed into models) |
| Complexity per unit | Low | High (grows unbound) | Medium |
| Rails conventions | No (manual) | Yes (default) | Yes (Rails 4+) |
Decision: Complex business rules → Service Object. Simple validations/scopes → Model. Cross-model behavior → Concern.
### ActiveRecord vs ActiveRecord::Base vs Sequel
| Criterion | ActiveRecord | Sequel | ROM.rb |
|-----------|-------------|--------|--------|
| Rails integration | Native | Adapter | Adapter |
| Performance | Moderate | High | High |
| Query interface | Rich DSL | Sequel DSL | Relation-based |
| Associations | Declarative | Declarative | Explicit |
| Migration system | Built-in | Built-in | Standalone |
Decision: Rails project → ActiveRecord. Heavy data pipeline → Sequel. Hexagonal/clean arch → ROM.rb.
## Workflow
### Step 1: Rails API Setup
```bash
rails new my_api --api --database=postgresql --skip-test
cd my_api
```
### Step 2: Directory Conventions (API Mode)
```
app/
controllers/
application_controller.rb
api/
v1/
users_controller.rb
orders_controller.rb
models/
user.rb
order.rb
services/
users/
create_service.rb
update_service.rb
orders/
place_order_service.rb
serializers/
user_serializer.rb
order_serializer.rb
jobs/
process_order_job.rb
policies/
user_policy.rb
config/
routes.rb
spec/
requests/
users_spec.rb
services/
users/
create_service_spec.rb
```
### Step 3: Routes
```ruby
# config/routes.rb
Rails.application.routes.draw do
namespace :api do
namespace :v1 do
resources :users, only: [:index, :show, :create, :update, :destroy]
resources :orders, only: [:index, :show, :create]
end
end
end
```
### Step 4: ActiveRecord Model
```ruby
# app/models/user.rb
class User < ApplicationRecord
# Enums
enum :role, { user: 0, admin: 1, moderator: 2 }, default: :user
# Validations
validates :email, presence: true, uniqueness: { case_sensitive: false },
format: { with: URI::MailTo::EMAIL_REGEXP }
validates :name, presence: true, length: { minimum: 2, maximum: 100 }
# Scopes
scope :active, -> { where(active: true) }
scope :by_role, ->(role) { where(role: role) }
scope :recent, -> { order(created_at: :desc) }
scope :search, ->(query) {
where('name ILIKE :q OR email ILIKE :q', q: "%#{sanitize_sql_like(query)}%")
}
# Associations
has_many :orders, dependent: :destroy
# Callbacks
after_create :send_welcome_email
private
def send_welcome_email
UserMailer.welcome(self).deliver_later
end
end
# db/migrate/xxxx_create_users.rb
class CreateUsers < ActiveRecord::Migration[7.1]
def change
create_table :users, id: :uuid do |t|
t.string :name, null: false
t.string :email, null: false
t.integer :role, default: 0, null: false
t.boolean :active, default: true, null: false
t.timestamps
end
add_index :users, :email, unique: true
add_index :users, :role
add_index :users, [:active, :role]
end
end
```
### Step 5: Serializer
```ruby
# app/serializers/user_serializer.rb
class UserSerializer
include JSONAPI::Serializer
attributes :name, :email, :role, :active
attribute :created_at do |user|
user.created_at.iso8601
end
has_many :orders, serializer: OrderSerializer
end
```
### Step 6: Service Object
```ruby
# app/services/users/create_service.rb
module Users
class CreateService < ApplicationService
attr_reader :params
def initialize(params)
@params = params
end
def call
validate_email_uniqueness!
user = User.new(user_attributes)
ActiveRecord::Base.transaction do
user.save!
create_audit_log(user)
end
Result.success(user)
rescue ActiveRecord::RecordInvalid => e
Result.failure(e.record.errors.full_messages)
rescue ActiveRecord::RecordNotUnique
Result.failure(['Email has already been taken'])
end
private
def user_attributes
{
name: params[:name],
email: params[:email].downcase.strip,
role: params[:role] || :user,
}
end
def validate_email_uniqueness!
if User.exists?(email: params[:email])
raise ActiveRecord::RecordNotUnique, "Email taken"
end
end
def create_audit_log(user)
AuditLog.create!(action: 'user_created', target: user)
end
end
end
# app/services/application_service.rb
class ApplicationService
Result = Struct.new(:success?, :data, :errors, keyword_init: true)
def self.call(...)
new(...).call
end
end
```
### Step 7: Thin Controller
```ruby
# app/controllers/api/v1/users_controller.rb
module Api
module V1
class UsersController < ApplicationController
before_action :authenticate_user!
before_action :set_user, only: [:show, :update, :destroy]
def index
users = User.active.recent.page(params[:page]).per(params[:per_page] || 20)
render json: UserSerializer.new(users).serializable_hash
end
def show
render json: UserSerializer.new(@user).serializable_hash
end
def create
result = Users::CreateService.call(user_params.to_h)
if result.success?
render json: UserSerializer.new(result.data).serializable_hash, status: :created
else
render json: { errors: result.errors }, status: :unprocessable_entity
end
end
def update
result = Users::UpdateService.call(@user, user_params.to_h)
if result.success?
render json: UserSerializer.new(result.data).serializable_hash
else
render json: { errors: result.errors }, status: :unprocessable_entity
end
end
def destroy
@user.update!(active: false)
head :no_content
end
private
def set_user
@user = User.find(params[:id])
end
def user_params
params.permit(:name, :email, :role)
end
end
end
end
```
### Step 8: Background Job
```ruby
# app/jobs/process_order_job.rb
class ProcessOrderJob < ApplicationJob
queue_as :default
retry_on StandardError, attempts: 3, wait: :exponentially_longer
discard_on ActiveRecord::RecordNotFound
def perform(order_id)
order = Order.find(order_id)
InventoryService.new.reserve_items(order)
order.update!(status: :processing)
OrderMailer.confirmation(order).deliver_later
rescue InsufficientInventoryError => e
order.update!(status: :failed, failure_reason: e.message)
raise
end
end
```
## Implementation Patterns
### Pattern: Query Object
```ruby
# app/queries/user_orders_query.rb
class UserOrdersQuery
def initialize(relation = Order.all)
@relation = relation
end
def by_user(user_id)
@relation.where(user_id: user_id)
end
def with_status(status)
@relation.where(status: status)
end
def recent_first
@relation.order(created_at: :desc)
end
def paginated(page:, per_page: 20)
@relation.page(page).per(per_page)
end
end
```
### Pattern: Policy Object
```ruby
# app/policies/user_policy.rb
class UserPolicy
def initialize(current_user, target_user)
@current_user = current_user
@target_user = target_user
end
def show?
@current_user == @target_user || @current_user.admin?
end
def update?
@current_user == @target_user || @current_user.admin?
end
def destroy?
@current_user.admin?
end
end
```
## Production Considerations
### Database Performance
- Add `id: :uuid` for distributed systems, `:bigint` for sequential
- Index all foreign keys and frequently queried columns
- Use `includes(:associations)` for eager loading — never lazy load in views
- Use `pluck` for single column queries instead of loading full records
- Use `find_each`/`in_batches` for large data processing (not `all.each`)
- Connection pooling: `pool: ENV.fetch('RAILS_MAX_THREADS', 5)` in database.yml
### Sidekiq Configuration
```ruby
# config/sidekiq.yml
:concurrency: 5
:queues:
- critical
- default
- low
:schedule:
cleanup_job:
cron: "0 0 * * *"
class: CleanupJob
```
## Anti-Patterns
| Anti-Pattern | Why | Fix |
|-------------|-----|-----|
| Callbacks for cross-model logic | Hidden dependencies, hard to test | Service objects |
| Fat models with > 200 lines | SRP violation, unmaintainable | Extract service/query objects |
| N+1 queries in serializers | 100+ queries per response | `includes` in controller |
| `all.each` on large tables | Memory exhaustion | `find_each` or `in_batches` |
| Logic in `before_action` | Hard to trace, test | Policy objects or direct checks |
| Strong params in controller | Repetitive across actions | Permitted params in service object |
## Security Considerations
- `has_secure_password` for bcrypt — never store plain passwords
- Devise or JWT for auth — never custom token implementation
- Strong parameters in every controller — prevent mass assignment
- `before_action :authenticate_user!` on protected controllers
- SQL injection: ActiveRecord is safe (parameterized), but `where("name = '#{param}'")` is not
- `config.force_ssl = true` in production
- CORS gem (`rack-cors`) for API mode — restrict origins
- Rate limiting with `rack-attack` gem
## Testing Strategies
```ruby
# spec/requests/api/v1/users_spec.rb
RSpec.describe 'Users API', type: :request do
describe 'POST /api/v1/users' do
let(:valid_params) { { name: 'John', email: 'john@test.com' } }
it 'creates a new user' do
post '/api/v1/users', params: valid_params, as: :json
expect(response).to have_http_status(:created)
expect(json['data']['attributes']['email']).to eq('john@test.com')
end
it 'returns 422 with invalid params' do
post '/api/v1/users', params: { name: '' }, as: :json
expect(response).to have_http_status(:unprocessable_entity)
end
end
end
```
Use `factory_bot_rails` for test data. Use `shoulda-matchers` for model specs. Use `database_cleaner` for test isolation. Use `webmock`/`vcr` for external HTTP. Use `rspec-sidekiq` for job testing.
## Rules
- Controllers are thin — one line of business logic per action.
- Service objects in `app/services/` — call with `.call(params)` returning `Result`.
- ActiveRecord models under 150 lines — validations, scopes, associations only.
- Serializers via `jsonapi-serializer` or `active_model_serializers`.
- Background jobs have `retry_on` with limits and `discard_on` for known failures.
- All database migrations have `add_index` for foreign keys and filtered columns.
- API mode Rails — no views, no cookies (token-based auth).
## References
- references/rails-active-record.md — ActiveRecord Best Practices
- references/rails-api-conventions.md — Rails API Conventions
- references/rails-api-design.md — Rails API Design
- references/rails-background-jobs.md — Background Jobs
- references/rails-performance-tuning.md — Performance Tuning
- references/rails-performance.md — Rails Performance
- references/rails-security.md — Rails Security
- references/rails-testing.md — Testing Rails Applications
## Handoff
Hand off to `backend/universal/api-response/SKILL.md` for API response formatting or `backend/universal/backend-testing/SKILL.md` for test patterns.
## Implementation Patterns
### Factory Pattern for Module Creation
`
function createModule<T>(config: ModuleConfig): T {
const dependencies = initializeDependencies(config);
const module = new Module(dependencies);
module.hooks.onInit();
return module as T;
}
`
### Builder Pattern for Complex Configuration
`
class ConfigBuilder {
private config: AppConfig = new AppConfig();
withDatabase(url: string): ConfigBuilder { ... }
withCache(ttl: number): ConfigBuilder { ... }
withLogging(level: string): ConfigBuilder { ... }
build(): AppConfig { return this.config; }
}
`
## Production Considerations
### Deployment Checklist
- [ ] Production build with optimizations enabled
- [ ] Environment variables configured per environment
- [ ] Health check endpoint responds correctly
- [ ] Error tracking and monitoring integrated
- [ ] Logging level configured (not debug in production)
- [ ] Resource limits configured
- [ ] Database migrations applied
- [ ] Static assets built and served from CDN or cache
- [ ] Feature flags toggled appropriately
- [ ] Rollback plan documented and tested
### Monitoring and Alerting
| Metric | Threshold | Severity | Action |
|--------|-----------|----------|--------|
| Error rate | > 1% | Critical | Rollback or fix |
| p95 latency | > 500ms | Warning | Profile and optimize |
| Uptime | < 99.9% | Critical | Investigate infrastructure |
| Memory usage | > 80% | Warning | Check for leaks |
| CPU usage | > 80% | Warning | Scale up or optimize |
## Rules
- Prefer composition over inheritance
- Favor immutable data structures
- Use dependency injection for testability
- Keep functions pure when possible — no side effects
- Fail fast with clear error messages
- Don't repeat yourself (DRY) — extract shared logic
- Keep it simple (KISS) — avoid unnecessary complexity
- You aren't gonna need it (YAGNI) — build what's required
- Separate concerns — single responsibility per module
- Code to interfaces, not implementations
- Write self-documenting code — clear names over comments
- Prefer standard library over third-party dependencies
- Handle errors explicitly — no silent failures
- Validate inputs at boundaries
- Log at appropriate levels (debug, info, warn, error)
Files in this package (9)
- SKILL.md 15 KB
- references/rails-active-record.md 1 KB
- references/rails-api-conventions.md 1 KB
- references/rails-api-design.md 71 KB
- references/rails-background-jobs.md 4 KB
- references/rails-performance-tuning.md 58 KB
- references/rails-performance.md 2 KB
- references/rails-security.md 4 KB
- references/rails-testing.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · j4flmao/agent-skills | 90 | MIT |
| Mindrally/skills | 100 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version c5107af08a10 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100programming-ruby
Ruby and Rails practices: objects, services, ActiveRecord persistence, transactions, Active Job boundaries. Use when writing or reviewing Ruby or Rails. - 100ruby
Use when writing Ruby or working in Rails codebases. Covers idiomatic object design, service objects, ActiveRecord query performance, RSpec structure, and RuboCop-clean style. Trigger on "this rails controller is too fat", "activerecord is doing n+1 queries", "clean up this… - 100rails-patterns
Ruby on Rails framework patterns for Rails 7.1+ and 8.x apps. Covers the directory contract, skinny controllers with service objects, form objects, query objects, idiomatic ActiveRecord, background jobs, ViewComponent, Hotwire, and the Rails 8 Solid stack. Use when building or… - 100rails-dev
Ruby on Rails performance and maintainability optimization guidelines for building backend APIs and frontend web applications. This skill should be used when writing, reviewing, or refactoring Ruby on Rails code to ensure optimal patterns for controllers, models, ActiveRecord… - 100rails-idioms
Ruby on Rails framework patterns: ActiveRecord scopes, N+1 query prevention, model validations, RESTful routing, and RSpec/Minitest testing. Use when building, maintaining, or auditing Rails web applications and APIs. Pair with ruby-idioms. - 86ruby-on-rails
Ruby on Rails coding conventions and guidelines Triggers on: **/*.rb