Rails Audit Skill (thoughtbot Best Practices)

A Claude Code skill that performs comprehensive code audits of
Ruby on Rails applications based on thoughtbot's Ruby Science and
Testing Rails best practices.

Quick links

Ruby Science - thoughtbot's guide to fixing code smells
Testing Rails - thoughtbot's guide to testing Rails applications
Rails Antipatterns - Best practices for Ruby on
Rails refactoring (Chad Pytel & Tammer Saleh)

Overview
Installation
Usage
- Full application audit
- Targeted audit
Reference materials
Contributing
License
About thoughtbot

Overview

This skill analyses Rails applications and generates detailed audit reports
covering:

Testing practices (RSpec)
Security vulnerabilities
Code design (skinny controllers, domain models, POROs with ActiveModel)
Rails conventions
Database optimisation (missing indexes, migrations hygiene)
External services (timeouts, error handling, background jobs)
Performance antipatterns (Ruby vs SQL, silent failures)
Ruby best practices

Installation

Copy the skill directory to your Claude Code skills folder:

cp -r rails-audit-thoughtbot ~/.claude/skills/

Or clone directly:

git clone https://github.com/thoughtbot/rails-audit-thoughtbot ~/.claude/skills/rails-audit-thoughtbot

Usage

If you are in your terminal and not in a Claude session, you can invoke the
skill directly by using the below. You need to be in the root directory of your
Rails project.

Full application audit

claude audit

If you are in a Claude session, you can reference the skill directly:

/rails-audit-thoughtbot

Targeted audit

In a Claude session you can also run targeted audits:

/rails-audit-thoughtbot audit controllers

This focuses the audit on specific files or directories.

Reference materials

The skill includes reference documentation based on thoughtbot best practices.
All the materials are compacted information from the books mentioned above.

Recommendations of PORO objects are based on different thoughtbot sources and
Service objects are poorly-named models.

File	Description
`references/code_smells.md`	Code smell patterns to identify (Ruby Science)
`references/testing_guidelines.md`	Testing best practices (Testing Rails)
`references/poro_patterns.md`	PORO and ActiveModel patterns
`references/security_checklist.md`	Security vulnerability checklist
`references/rails_antipatterns.md`	Rails-specific antipatterns: external services, migrations, performance
`references/report_template.md`	Audit report structure template

Contributing

Contributions are welcome! If you'd like to improve the audit patterns or add
new detection rules:

Fork the repository
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

License

This skill is open source and available under the MIT License.

About thoughtbot

This skill is inspired by and based on thoughtbot's excellent guides:

Ruby Science
Testing Rails
Rails Antipatterns by Chad Pytel & Tammer Saleh

The names and logos for thoughtbot are trademarks of thoughtbot, inc.

We love open source software!
See thoughtbot's other projects.

LeipeLeon/rails-audit