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.

2.21x

Quality

97%

Does it follow best practices?

Impact

91%

2.21x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

name:: ruby-service-objects
description:: Use when creating or refactoring Ruby service classes in Rails. Covers the .call pattern, module namespacing, YARD documentation, standardized responses, orchestrator delegation, transaction wrapping, and error handling conventions.

Ruby Service Objects

Name: igmarin/rails-agent-skills
Rating: 95.82 (1 reviews)
Author: igmarin

HARD-GATE: Tests Gate Implementation

EVERY service object MUST have its test written and validated BEFORE implementation.
  1. Write the spec for .call (with contexts for success, error, edge cases)
  2. Run the spec — verify it fails because the service does not exist yet
  3. ONLY THEN write the service implementation
See rspec-best-practices for the full gate cycle.

Quick Reference

Convention	Rule
Entry point	`.call` class method delegating to `new.call`
Response format	`{ success: true/false, response: { ... } }`
File location	`app/services/module_name/service_name.rb`
Pragma	`frozen_string_literal: true` in every file
Docs	YARD on every public method (see yard-documentation)
Validation	Raise early on invalid input
Errors	Rescue, log, return error hash — don't leak exceptions
Transactions	Wrap multi-step DB operations

Core Patterns

1. The `.call` Pattern

module AnimalTransfers
  class TransferService
    attr_reader :source_shelter_id, :target_shelter_id

    def self.call(params)
      new(params).call
    end

    def initialize(params)
      @source_shelter_id = params.dig(:source_shelter, :shelter_id)
      @target_shelter_id = params.dig(:target_shelter, :shelter_id)
    end

    def call
      validate_shelters!
      result = process_data
      build_success_response(result)
    rescue ActiveRecord::RecordInvalid => e
      log_error('Validation Error', e)
      build_error_response(e.message, [])
    rescue StandardError => e
      log_error('Processing Error', e, include_backtrace: true)
      build_error_response(e.message, [])
    end
  end
end

2. Standardized Response Format

# Success
{ success: true, response: { successful_items: [...] } }

# Error
{ success: false, response: { error: { message: '...', failed_items: [...] } } }

# Partial success
{
  success: true,
  response: {
    successful_transfers: ['TAG001'],
    error: { message: 'Some animals were not found...', failed_transfers: ['TAG002'] }
  }
}

3. Class-only Services (Static Methods)

When no instance state is needed:

class ShelterValidator
  def self.validate_source_shelter!(shelter_id)
    shelter = Shelter.find_by(id: shelter_id)
    raise ArgumentError, 'Source shelter not found' unless shelter
    shelter
  end
end

Additional Patterns

Constants for configuration

MISSING_CONFIGURATION_ERROR = 'Missing required configuration'
DEFAULT_TIMEOUT = 30

SQL sanitization

def self.find(tag_number:)
  query = ActiveRecord::Base.sanitize_sql(['SELECT * FROM table WHERE tag_number = ?;', tag_number])
  fetcher.execute_query(query)
end

Checklist for New Service Objects

Module namespace matches directory structure
Constants defined for error messages and defaults
Graceful handling for non-critical failures
SQL sanitization for any dynamic queries
README.md documenting the module

Pitfalls

Problem	Correct approach
Returning raw exceptions instead of error hash	Callers should get `{ success: false, ... }`, not unhandled exceptions
Skipping input validation	Bad input causes cryptic errors deep in the call chain
Transaction wrapping everything	Only wrap multi-step DB operations that must be atomic
`.call` method longer than 20 lines	Extract to sub-services — orchestrator should coordinate, not implement
Service renders HTTP responses	That's the controller's job — service returns data only
Service modifies unrelated models	Unclear boundary — extract a new service with a single responsibility
Duplicated validation across services	Extract to a shared validator object

Integration

Skill	When to chain
yard-documentation	When writing or reviewing inline docs for classes and public methods
ruby-api-client-integration	For external API integrations (Auth, Client, Fetcher, Builder layers)
strategy-factory-null-calculator	For variant-based calculators (Factory + Strategy + Null Object)
rspec-service-testing	For testing service objects
rspec-best-practices	For general RSpec structure
rails-architecture-review	When service extraction is part of an architecture review

api-rest-collection

create-prd

ddd-boundaries-review

ddd-rails-modeling

ddd-ubiquitous-language

evals

generate-tasks

rails-agent-skills

rails-architecture-review

rails-background-jobs

rails-bug-triage

rails-code-conventions

rails-code-review

rails-engine-author

rails-engine-compatibility

rails-engine-docs

rails-engine-extraction

rails-engine-installers

rails-engine-release

rails-engine-reviewer

rails-engine-testing

rails-graphql-best-practices

rails-migration-safety

rails-review-response

rails-security-review

rails-stack-conventions

rails-tdd-slices

refactor-safely

rspec-best-practices

rspec-service-testing

ruby-api-client-integration

ruby-service-objects

SKILL.md

strategy-factory-null-calculator

ticket-planning

yard-documentation

README.md

tile.json