⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.2.0

rails-conventions

ethos-link@ethos-link⭐ 20 stars· last commit 19d ago· 0 open issues

Rails 8.x application architecture, implementation, and review guidance for production codebases. Use when building or reviewing Ruby on Rails 8 features across models, controllers, routes, Hotwire, jobs, APIs, performance, security, and testing. Trigger for requests mentioning Rails 8, Active Record, Active Job, GoodJob, Solid Queue, Turbo/Stimulus, REST resources, migrations, code quality, naming, and production readiness.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 20 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README


What this skill helps with

rails-conventions is for real production work in Rails codebases where consistency matters.

It guides agents to:

  • inspect local patterns first (models, controllers, routes, tests, deploy setup)
  • keep naming and architecture aligned with existing conventions
  • write backend-aware job code (good_job or solid_queue) without assumptions
  • catch risks early in security, performance, and test coverage
  • write value-based tests split by responsibility (deep unit coverage, thin request checks)
  • generate migrations and installer files instead of inventing them
  • reuse existing Ruby, Rails, and installed library APIs before writing helpers
  • diagnose bugs through testable hypotheses and verify regressions before/after
  • turn repeated mistakes into safeguards and measure equivalent work

Coverage

  • Ruby 4.0+/Rails 8.1+ baseline, stable releases, and native API discovery
  • Naming, layering, and code organization
  • Active Record modeling, PostgreSQL features, and migration discipline
  • Controllers, params, and response semantics
  • REST/resource-focused routing
  • Hotwire/Turbo/Stimulus patterns (including realtime posture)
  • Background jobs (adapter detection + backend-specific guidance)
  • Webhook inbound/outbound delivery reliability
  • Performance and caching strategy
  • Security checklist (including SSRF hardening and tenancy)
  • Testing strategy (value-based assertions, Minitest and Minitest::Mock)
  • API and serialization conventions
  • Evidence-driven debugging, review, and realistic skill evaluation
  • Mailer composition and previews
  • Maintenance tasks, one-off cleanup, and maintained documentation
  • Optional 37signals-inspired profile
  • Generator-owned files policy (migrations, installers — never invent them)

Validate, install, and update

Run the bundled validation script before publishing changes:

ruby scripts/validate_skill.rb

Install or update the skill with skills:

# install from source
npx skills add [email protected]:ethos-link/rails-conventions.git --skill rails-conventions

# update an existing install
npx skills update rails-conventions

Forward-test prompts

Use these prompts to check that the skill triggers correctly and loads only the references needed for the task:

Implement a new billing webhook endpoint in this Rails app, matching existing conventions and tests.
Review this Rails 8 pull request for production readiness, focusing on naming, data integrity, security, and missing tests.
This Rails app uses GoodJob. Add a background job for exporting account reports without changing the queue backend.
Add a request test for closing a card: assert redirect, h1, and that the card is closed — do not scrape the whole page. Cover edge cases in the model test.
Generate a migration to add postponed_at to cards. Do not invent the timestamp filename by hand.

References

License

MIT.

About

Made by the team at Ethos Link — practical software for growing businesses. We build tools for hospitality operators who need clear workflows, fast onboarding, and real human support.

We also build Reviato, “Capture. Interpret. Act.”. Turn guest feedback into clear next steps for your team. Collect private appraisals, spot patterns across reviews, and act before small issues turn into public ones.

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md7.8 KBupstream ↗
    ---
    name: rails-conventions
    description: Rails 8.x application architecture, implementation, and review guidance for production codebases. Use when building or reviewing Ruby on Rails 8 features across models, controllers, routes, Hotwire, jobs, APIs, performance, security, and testing. Trigger for requests mentioning Rails 8, Active Record, Active Job, GoodJob, Solid Queue, Turbo/Stimulus, REST resources, migrations, code quality, naming, and production readiness.
    license: MIT
    compatibility: Compatible with any agent runtime that supports the Agent Skills SKILL.md convention and optional references directory loading.
    metadata:
      version: 1.1.0
      ethos_link.company: Ethos Link
      ethos_link.company_url: https://www.ethos-link.com
      ethos_link.product: Reviato
      ethos_link.product_url: https://www.reviato.com
      ethos_link.maintainer: ethos-link
      ethos_link.contact_url: https://www.ethos-link.com/contact/
    ---
    
    # Rails Convention Engineer
    
    Follow this workflow and load only the references needed for the task.
    
    ## Execution Workflow
    
    1. Inspect the codebase before proposing changes.
    2. Match existing conventions unless the user requests a migration.
    3. Use Rails conventions and plain Ruby first.
    4. Prefer small, reversible changes with tests.
    5. Report tradeoffs explicitly when choosing architecture.
    6. Verify version-sensitive APIs against official Rails or gem docs before
       changing guidance or introducing new APIs.
    7. Create generator-owned files only by running the generator — never invent them.
    
    ## Non-Negotiable Rails Defaults
    
    Rails applications should look like Rails applications. Prefer the framework's
    native resource, model, controller, job, mailer, and view boundaries before
    introducing extra architectural layers. Avoid architecture borrowed from other
    ecosystems when Rails already has a direct convention for the problem.
    
    Official Rails guides, official gem documentation, and established local app
    conventions outrank style profiles. Use 37signals-inspired guidance as taste
    guidance, not as authority over the current app or current Rails APIs.
    
    Classes and modules must earn their place. Choose the fewest concepts, files,
    and lines of code that keep the behavior clear. Do not add wrappers, aliases,
    facades, or parallel abstractions whose main purpose is naming, indirection, or
    making tests easier.
    
    Keep one owner per behavior and one owner per definition. Prompts, schemas,
    enums, constants, validation rules, normalization logic, and domain terminology
    must each have a canonical home.
    
    Identifier names must state ownership. `id` and `uuid` are owned by the local
    application. `eid` means an identifier owned by another application or provider
    and stored locally. Never alias a local `id` or `uuid` as `eid`. Use a qualified
    name such as `place_eid`, `listing_eid`, or `review_eid` when a record can carry
    identifiers from more than one external owner. A local identifier becomes an
    `*_eid` only in the consuming system, never in its owning system.
    
    Every Rails project should maintain a domain terminology document, usually
    `docs/domain-terms.md`, and link it from the README or equivalent contributor
    entrypoint. The document should define canonical domain terms, deprecated terms,
    and naming rules for code, routes, params, APIs, persisted fields, and docs.
    
    ## Generator-Owned Files
    
    Never hand-write files that Rails or a gem installer is supposed to generate.
    Invented timestamps, installer stubs, and guessed schema dumps cause drift and
    broken deploys.
    
    Run the generator (or installer task) and then edit the result:
    
    - Migrations: `bin/rails generate migration ...` / `bin/rails g model ...`
    - Mailers, jobs, controllers, scaffolds: the matching `bin/rails g ...`
    - Auth: `bin/rails generate authentication` when that is the app's path
    - Queue/cache/cable installers: the gem or Rails install task
      (`solid_queue:install`, `good_job:install`, and equivalents)
    - App/framework config seeds created by installers (`db/*_schema.rb`,
      `config/queue.yml`, binstubs such as `bin/jobs`) when the app does not
      already have them
    
    After generating, adapt the file to local conventions. Do not invent migration
    version numbers or timestamps. Do not recreate installer output from memory
    when the installer exists. If a generator cannot be run in this environment,
    say so and provide the exact command for the user — do not fabricate the file.
    
    ## Mandatory Codebase Scan
    
    Always read these files first when available:
    
    - `Gemfile`
    - `config/application.rb`
    - `config/routes.rb`
    - `config/environments/*.rb` (at least current target env)
    - `app/models/` (2-5 representative models)
    - `app/controllers/` (2-5 representative controllers)
    - `test/` or `spec/`
    - process/deploy entrypoints (`Procfile*`, `bin/jobs`, `config/deploy*.yml`, CI config)
    
    Record and follow observed patterns:
    
    - test framework
    - authentication/authorization style
    - frontend stack (Hotwire, React, hybrid)
    - queue backend and runtime topology
    - API conventions and serialization style
    
    ## Background Job Backend Policy
    
    Never assume Solid Queue just because the app is Rails 8.
    
    Detect backend in this order:
    
    1. `config.active_job.queue_adapter`
    2. `Gemfile` gems (`good_job`, `solid_queue`, others)
    3. worker runtime commands and deployment wiring
    
    Apply these rules:
    
    - If `good_job` is active, keep `good_job` conventions.
    - If `solid_queue` is active, keep `solid_queue` conventions.
    - If both gems exist, treat the configured adapter as authoritative.
    - Do not migrate queue backend implicitly as part of unrelated tasks.
    - Write backend-agnostic `ApplicationJob` code unless backend features are explicitly requested.
    
    ## Reference Routing
    
    Load references based on the task:
    
    - Code style, formatting, naming conventions, and fail-fast policy: `STYLE.md`
    - Baseline Rails 8 defaults and upgrade constraints: `references/01-baseline-rails-8.md`
    - Naming, layering, and code organization: `references/02-naming-and-structure.md`
    - Active Record, migrations, and data modeling: `references/03-models-and-data.md`
    - PostgreSQL-specific Active Record features: `references/03a-active-record-postgresql.md`
    - Controllers, params, and request flow: `references/04-controllers-and-params.md`
    - REST resources and routes: `references/05-routes-rest-and-resources.md`
    - Hotwire, Turbo, and Stimulus patterns: `references/06-hotwire-turbo-stimulus.md`
    - Job architecture and adapter detection: `references/07-background-jobs-overview.md`
    - GoodJob-specific patterns: `references/07a-background-jobs-good_job.md`
    - Solid Queue-specific patterns: `references/07b-background-jobs-solid_queue.md`
    - Performance and caching strategy: `references/08-performance-caching-and-db.md`
    - Security review checklist: `references/09-security-checklist.md`
    - Test strategy and quality gates: `references/10-testing-strategy.md`
    - API-only and mixed-mode API patterns: `references/11-api-mode-and-serialization.md`
    - 37signals-inspired style profile: `references/12-37signals-inspired-profile.md`
    - Code quality thresholds and detection patterns: `references/13-code-quality-gates.md`
    - Inbound/outbound webhooks and delivery reliability: `references/14-webhooks.md`
    
    ## Task Routing
    
    | Task | Load |
    |------|------|
    | Ruby style, naming, method order, fail-fast | `STYLE.md`, `references/13-code-quality-gates.md` |
    | New model, migration, data invariant, parser | `references/03-models-and-data.md`, `references/03a-active-record-postgresql.md`, `references/10-testing-strategy.md` |
    | Controller params, authz, sessions, responses | `references/04-controllers-and-params.md`, `references/09-security-checklist.md`, `references/10-testing-strategy.md` |
    | Routes or custom actions | `references/05-routes-rest-and-resources.md`, `references/04-controllers-and-params.md` |
    | Hotwire, Turbo, Stimulus | `references/06-hotwire-turbo-stimulus.md`, `references/10-testing-strategy.md` |
    | Background jobs | `references/07-background-jobs-overview.md`, adapter-specific `07a` or `07b`, `referenc
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/ethos-link-rails-conventions.md

// REPO STATS

20 stars
0 open issues
Last commit: 19d ago