Rails Audit by thoughtbot skill
Rails Audit (thoughtbot)
A thoughtbot skill for reviewing Rails applications, finding code and test issues and ranking findings by severity
- 264 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Optional metrics execute test code and change project dependencies and configuration
- Restoration and cleanup steps can remove uncommitted edits and existing reports
- The agent reads application sources and configuration, which the selected model processes
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/rails-audit-thoughtbotDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Optional metrics execute test code and change project dependencies and configuration
- Restoration and cleanup steps can remove uncommitted edits and existing reports
- The agent reads application sources and configuration, which the selected model processes
This is third-party code. Review the repository files before installing.
What it does
Rails Audit is a Claude Code skill from the thoughtbot studio. It walks through a Rails application and produces an audit: RSpec tests, security, models, controllers, code design, views, database indexes and migrations, external services with timeouts and background jobs, common performance mistakes. It leans on the books Ruby Science, Testing Rails and Rails Antipatterns, and in design advice it prefers plain Ruby objects (POROs) over service objects. The audit is full or targeted. A full audit reads app, spec or test, config, db and lib. A targeted one takes a path from your request, for example `/rails-audit-thoughtbot audit controllers`. The result is a Markdown report with findings grouped by category (Testing, Security, Models, Controllers, Code Design, Views) and by severity: Critical, High, Medium, Low. Before it starts, the skill offers optional tool-measured metrics. SimpleCov runs your tests and shows coverage per directory. RubyCritic analyzes source complexity and duplication without running tests. The instructions offer a choice of either tool, both or neither. Each tool has its own subagent.
Who it is for. For Rails developers and tech leads who inherit someone else's code or want an independent look at the state of their own app.
Good fit when
- You inherit a Rails application and need a list of problems with severity levels
- Before a release you want to check controllers for excess logic and models for mixed responsibilities
- You need to know where test coverage is zero: SimpleCov shows the weakest files
- You suspect missing database indexes or slow queries written in Ruby where SQL would do
- You need an audit of one directory, for example app/models, without reviewing the whole project
Not a fit when
- The project is not Rails: the skill looks for Rails conventions and antipatterns
- You need dependency vulnerability scanning or dynamic security testing: the security checklist is only a set of code questions
- Tests are not written in RSpec or Minitest: the testing sections lose their meaning
- The working directory must not change even temporarily: for metrics the skill briefly edits the Gemfile
Example request
/rails-audit-thoughtbot audit controllers: review controller logic without running metrics and prioritize each finding.Limitations
The review follows thoughtbot’s conventions, so some architecture advice may differ from your team’s rules. A model produces the findings; verify them against the code. If SimpleCov is unavailable, the skill permits an approximate coverage estimate with an explanation. That is not a measurement.
Metric collection changes the Gemfile, lockfile and test setup. When both tools need adding, parallel runs may conflict; run them sequentially on a clean working tree. File restoration and report cleanup can affect existing edits and the coverage and tmp/rubycritic directories. Back them up before starting.
How to disable. Remove the plugin through `/plugin`. For a manual installation, remove ~/.claude/skills/rails-audit-thoughtbot. Saved reports remain in the project.
FAQ
How do I install the Rails audit skill in Claude Code?
Add the thoughtbot marketplace and install the plugin with the commands in the installation section. A manual option is also available: clone the repository into Claude Code’s skills directory. Choose one method to avoid loading the collection twice.
How do I audit a single directory?
Include the target in the full command: `/rails-audit-thoughtbot audit controllers`. The agent limits reading to the specified files or directories.
Can I get a review when tests do not run?
Yes. The core review reads source files. Measuring coverage requires Ruby, Bundler and a working RSpec or Minitest suite. If tests cannot run, skip that stage and state the report’s limitation.
Where do the audit rules come from?
From thoughtbot's Ruby Science and Testing Rails, and for antipatterns also from Rails Antipatterns by Chad Pytel and Tammer Saleh. They are condensed into reference files in the references folder: code smells, testing, POROs, a security checklist.
What format does the report come in?
Markdown following report_template.md. Findings are grouped by category and split into Critical, High, Medium and Low inside each.
Discussion
No questions or reviews yet.
Related
SkillsTwo skills for Codex and Claude Code: a read-only repository audit and an experiment loop with saved baselines.
A Claude Code plugin for UX regression testing that walks user journeys in a live app and returns a ranked fix plan.
A six-skill accessibility plugin: page review, WCAG 2.2 audit with Playwright, audit planning and an improvement roadmap.
An adversarial code-audit skill: Hunter finds bugs, Skeptic challenges them, Referee rules, and no source edit happens without your permission
The evidence-code-review skill for Codex and Claude Code: evidence-based change review with MUST, SHOULD, BETTER and NITS levels
A Claude Code plugin for SwiftUI that walks an app like a user and finds unreachable screens, dead ends and placeholder data.
README in short
The collection uses MIT and accepts contributions to its detection rules. Reference material is organized by topic, so you can inspect the methodology before running it on your project.
README badge
Original SKILL.md
---
name: rails-audit-thoughtbot
description: Perform comprehensive code audits of Ruby on Rails applications based on thoughtbot best practices. Use this skill when the user requests a code audit, code review, quality assessment, or analysis of a Rails application. The skill analyzes the entire codebase focusing on testing practices (RSpec), security vulnerabilities, code design (skinny controllers, domain models, PORO with ActiveModel), Rails conventions, database optimization, and Ruby best practices. Outputs a detailed markdown audit report grouped by category (Testing, Security, Models, Controllers, Code Design, Views) with severity levels (Critical, High, Medium, Low) within each category.
---
# Rails Audit Skill (thoughtbot Best Practices)
Perform comprehensive Ruby on Rails application audits based on thoughtbot's Ruby Science and Testing Rails best practices, with emphasis on Plain Old Ruby Objects (POROs) over Service Objects.
## Audit Scope
The audit can be run in two modes:
1. **Full Application Audit**: Analyze entire Rails application
2. **Targeted Audit**: Analyze specific files or directories
## Execution Flow
### Step 1: Determine Audit Scope
Ask user or infer from request:
- Full audit: Analyze all of `app/`, `spec/` or `test/`, `config/`, `db/`, `lib/`
- Targeted audit: Analyze specified paths only
### Step 2: Collect Optional Metrics (SimpleCov + RubyCritic)
Ask the user **both questions upfront** in a single `AskUserQuestion` so they can decide once:
- **Question**: "Before starting the audit, would you like to collect automated metrics?\n\n1. **SimpleCov** — runs your test suite to capture actual code coverage percentages\n2. **RubyCritic** — analyzes code complexity, duplication, and smells (does not run tests)\n\nBoth are recommended for the most thorough audit."
- **Options**: "Yes to both (Recommended)" / "SimpleCov only" / "RubyCritic only" / "Skip both"
Based on the user's choice, spawn the accepted subagents **in parallel** using the Task tool. Both can run at the same time because SimpleCov modifies the test helper while RubyCritic only reads source files — they don't conflict.
**SimpleCov subagent** (if accepted):
> Read the file `agents/simplecov_agent.md` and follow all steps described in it. The audit scope is: {{SCOPE from Step 1}}. Return the coverage data in the output format specified in that file.
**RubyCritic subagent** (if accepted):
> Read the file `agents/rubycritic_agent.md` and follow all steps described in it. The audit scope is: {{SCOPE from Step 1}}. Return the code quality data in the output format specified in that file.
**After both agents finish**, clean up:
- If SimpleCov ran: `rm -rf coverage/`
- If RubyCritic ran: `rm -rf tmp/rubycritic/`
**Interpreting responses:**
- `COVERAGE_FAILED` / `RUBYCRITIC_FAILED`: no data for that tool — use estimation mode (SimpleCov) or omit the section (RubyCritic). Note the failure reason in the report.