gh-nbarthel-claudy-plugins-rails-workflow/skills/rails-conventions/skill.md

name, description, auto_invoke, trigger_on, file_patterns, tags, priority, version

name	description	auto_invoke	trigger_on	file_patterns	tags	priority	version
rails-conventions	Automatically enforces Rails naming conventions, MVC separation, and RESTful patterns	true	file_create file_modify	*.rb *.erb config/routes.rb	rails conventions patterns rest mvc	1	2.0

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.