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.

98

1.38x
Quality

99%

Does it follow best practices?

Impact

98%

1.38x

Average score across 26 eval scenarios

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

SKILL.mdrails-stack-conventions/

name:
rails-stack-conventions
description:
Use when writing new Rails code for a project using the PostgreSQL + Hotwire + Tailwind CSS stack. Covers stack-specific patterns only: MVC structure, ActiveRecord query conventions, Turbo Frames/Streams wiring, Stimulus controllers, and Tailwind component patterns. Not for general Rails design principles — this skill is scoped to what changes based on this specific technology stack.

Rails Stack Conventions

When writing or generating code for this project, follow these conventions. Stack: Ruby on Rails, PostgreSQL, Hotwire (Turbo + Stimulus), Tailwind CSS.

Style: If the project uses a linter, treat it as the source of truth for formatting. For cross-cutting design principles (DRY, YAGNI, structured logging, rules by directory), use rails-code-conventions.

HARD-GATE: Tests Gate Implementation

ALL new code MUST have its test written and validated BEFORE implementation.
  1. Write the spec: bundle exec rspec spec/[path]_spec.rb
  2. Verify it FAILS — output must show the feature does not exist yet
  3. ONLY THEN write the implementation code
See rspec-best-practices for the full gate cycle.

Quick Reference

AspectConvention
StyleRuboCop project config when present; otherwise Ruby Style Guide, single quotes
ModelsMVC — service objects for complex logic, concerns for shared behavior
QueriesEager load with includes; never iterate over associations without preloading
FrontendHotwire (Turbo + Stimulus); Tailwind CSS
TestingRSpec with FactoryBot; TDD
SecurityStrong params, guard XSS/CSRF/SQLi; Devise/Pundit for auth

Key Code Patterns

Hotwire: Turbo Frames

<%# Wrap a section to be replaced without a full page reload %>
<turbo-frame id="order-<%= @order.id %>">
  <%= render "orders/details", order: @order %>
</turbo-frame>

<%# Link that targets only this frame %>
<%= link_to "Edit", edit_order_path(@order), data: { turbo_frame: "order-#{@order.id}" } %>

Hotwire: Turbo Streams (broadcast from controller)

respond_to do |format|
  format.turbo_stream do
    render turbo_stream: turbo_stream.replace(
      "order_#{@order.id}",
      partial: "orders/order",
      locals: { order: @order }
    )
  end
  format.html { redirect_to @order }
end

Avoiding N+1 — Eager Loading

# BAD — triggers one query per order
@orders = Order.where(user: current_user)
@orders.each { |o| o.line_items.count }

# GOOD — single JOIN via includes
@orders = Order.includes(:line_items).where(user: current_user)

Service Object (complex business logic out of the controller)

# Controller stays thin — delegate to service
result = Orders::CreateOrder.call(user: current_user, params: order_params)
if result[:success]
  redirect_to result[:order], notice: "Order created"
else
  @order = Order.new(order_params)
  render :new, status: :unprocessable_entity
end

See ruby-service-objects for the full .call pattern and response format.

Security

  • Strong params on every controller action that writes data
  • Guard against XSS (use html_escape, avoid raw), CSRF (Rails default on), SQLi (use AR query methods or sanitize_sql for raw SQL)
  • Auth: Devise for authentication, Pundit for authorization

Common Mistakes

MistakeCorrect approach
Business logic in viewsUse helpers, presenters, or Stimulus controllers
N+1 queries in loopsEager load with includes before the loop
Raw SQL without parameterizationUse AR query methods or ActiveRecord::Base.sanitize_sql
Skipping FactoryBot for "quick" testFixtures are brittle — always use factories

Red Flags

  • Controller action with more than 15 lines of business logic
  • Model with no validations on required fields
  • View with embedded Ruby conditionals spanning 10+ lines
  • No includes on associations used in loops
  • Hardcoded strings that belong in I18n

Integration

SkillWhen to chain
rails-code-conventionsFor design principles, structured logging, and path-specific rules
rails-code-reviewWhen reviewing existing code against these conventions
ruby-service-objectsWhen extracting business logic into service objects
rspec-best-practicesFor testing conventions and TDD cycle
rails-architecture-reviewFor structural review beyond conventions

rails-stack-conventions

README.md

tile.json