Rails Conventions Skill

Auto-validates and enforces Rails conventions across all code changes.

What This Skill Does

Automatic Enforcement:

• •Model naming: PascalCase, singular (User, not Users)
• •Controller naming: PascalCase, plural, ends with Controller (UsersController)
• •File paths: snake_case matching class names (users_controller.rb)
• •RESTful routes: Standard 7 actions (index, show, new, create, edit, update, destroy)
• •MVC separation: No business logic in views, no SQL in controllers

When It Activates:

• •Every time a .rb file is created or modified
• •When routes.rb is changed
• •When view files are created

What It Checks:

1. •

   Naming Conventions

   • •Class names follow Rails conventions
   • •File names match class names (snake_case ↔ PascalCase)
   • •Variable names descriptive and snake_case
   • •Constants in SCREAMING_SNAKE_CASE
2. •

   MVC Separation

   • •Controllers: Thin, delegate to models/services
   • •Models: Business logic, no rendering
   • •Views: Presentation only, minimal logic
3. •

   RESTful Patterns

   • •Routes follow REST conventions
   • •Custom actions documented and justified
   • •Nested routes limited to 2 levels
4. •

   Rails Idioms

   • •Use scopes over class methods for queries
   • •Use concerns for shared behavior
   • •Use before_action for controller filters

Validation Examples

Example 1: Model Naming

Input:

# app/models/users.rb
class Users < ApplicationRecord
end

Skill Output:

❌ Convention Violation: Model class name should be singular
Expected: User
Found: Users

Fix:
- Rename class to "User"
- Rename file to "user.rb"

Example 2: Controller Naming

Input:

# app/controllers/user.rb
class User < ApplicationController
end

Skill Output:

❌ Convention Violation: Controller class name should be plural and end with 'Controller'
Expected: UsersController
Found: User

❌ File Naming: Controller file should match class name
Expected: users_controller.rb
Found: user.rb

Example 3: MVC Separation

Input:

# app/controllers/posts_controller.rb
def index
  @posts = Post.where("created_at > ?", 1.week.ago)
              .joins(:author)
              .order(created_at: :desc)
end

Skill Output:

⚠️  MVC Separation: Complex query logic in controller
Recommendation: Extract to model scope

Suggested refactoring:
# app/models/post.rb
scope :recent, -> { where("created_at > ?", 1.week.ago) }
scope :with_author, -> { joins(:author) }
scope :newest_first, -> { order(created_at: :desc) }

# app/controllers/posts_controller.rb
def index
  @posts = Post.recent.with_author.newest_first
end

Example 4: RESTful Routes

Input:

# config/routes.rb
resources :posts do
  get 'activate'
  get 'deactivate'
  get 'toggle_status'
  get 'publish'
end

Skill Output:

⚠️  RESTful Pattern: Multiple custom actions detected
Current: 4 custom actions (activate, deactivate, toggle_status, publish)
Recommendation: Consider consolidating to single update action

Suggested refactoring:
resources :posts do
  patch 'status', to: 'posts#update_status'
end

# Controller:
def update_status
  action = params[:action_type] # 'activate', 'deactivate', 'publish'
  @post.update!(status: action)
end

Configuration

Skill can be configured via .rails-conventions.yml:

# .rails-conventions.yml
naming:
  enforce_singular_models: true
  enforce_plural_controllers: true

mvc_separation:
  max_controller_lines: 100
  warn_on_complex_queries: true

restful:
  max_custom_actions: 2
  max_nesting_depth: 2

Auto-Fix Capability

This skill can automatically fix simple violations:

Auto-fixable:

• •File renaming to match class names
• •Converting class method queries to scopes
• •Extracting inline queries to model scopes

Manual fix required:

• •Class name changes (impacts migrations, associations)
• •MVC layer violations (requires architectural decisions)
• •Custom route consolidation (business logic dependent)

Integration with Agents

This skill enhances all agents:

• •@rails-model-specialist: Validates model naming and scope usage
• •@rails-controller-specialist: Enforces RESTful patterns and thin controllers
• •@rails-view-specialist: Validates view logic separation
• •@rails-architect: Provides convention checks during coordination

Severity Levels

• •❌ Error: Blocks commit (via pre-commit hook) - naming violations, missing strong params
• •⚠️ Warning: Suggests improvement - complex queries, non-RESTful routes
• •ℹ️ Info: Best practice suggestion - use of concerns, scope opportunities

Performance

• •Activates on: File save
• •Execution time: < 100ms per file
• •No network calls
• •Works offline

This skill runs automatically - no invocation needed. It keeps your Rails code conventional and maintainable.