The Experiment

I remember one of my first teachers in the bootcamp saying that software developers are lazy. We like to automate repetitive tasks and leave all hard work to the machine.

The other day I was looking at a Rails codebase and thought: what if Claude could help me review some of these files? I wanted to see if it could spot issues I might miss, following the patterns I care about and thoughtbot best practices.

What started as a quick experiment turned into something more interesting. I ended up building a Claude Skill to audit Rails applications.

What’s a Claude Skill?

If you’ve used Claude Code (the CLI tool), you might have seen the .claude/skills/ directory. Skills are basically instruction files that extend Claude’s abilities with specific knowledge.

A skill consists of:

SKILL.md: The main instruction file
references/: Detailed documentation Claude can read during execution

When you ask Claude to do something, it checks available skills and loads the relevant ones. The skill tells Claude how to approach the problem.

Building the skill

The skill I created using Claude has five reference files based on thoughtbot’s books and blog posts:

code_smells.md - Based on Ruby Science, covering different code smells.

testing_guidelines.md - Based on Testing Rails

poro_patterns.md— This one I care about a lot. It documents why service objects should be domain models and how to use ActiveModel::Model properly.

Instead of:

class UserRegistrationService
  def self.call(params)
    # registration logic
  end
end

We should write:

class Registration
  include ActiveModel::Model

  attr_accessor :email, :password, :company_name

  validates :email, presence: true
  validates :password, presence: true, length: { minimum: 8 }

  def complete
    return false unless valid?
    create_user
    send_welcome_email
    true
  end
end

You can find more about this pattern in the reference file of the skill in the repository.

security_checklist.md - Twelve categories of security issues with detection patterns.

report_template.md - A structured template for the audit output.

Using it

Once you add the skill to your project’s .claude/skills/ directory, you can ask Claude to audit your code:

claude audit

A session of Claude will start, match the audit word with the skill name, and ask you if you want to run the skill.

The results

Here’s the honest part: the output is reasonably good, but you still need to steer the wheel.

What works well:

Identifying code smells (long methods, large classes)
Flagging missing tests
Catching common security issues
Suggesting PORO refactorings for service objects

What requires your judgment:

Deciding if a suggestion makes sense in your context
Prioritising what to fix first
Understanding when a “smell” is actually fine for your situation

Try it yourself

If you want to experiment with this:

Create .claude/skills/ in your Rails project or in your computer root directory
Clone the rails-audit-thoughtbot folder with SKILL.md and references/
Ask Claude to audit your code

Final thoughts

This was a fun experiment. I wanted to see if Claude could help with code reviews following specific patterns, and building a skill turned out to be a good way to make that happen.

The skill is not perfect, but it’s a decent starting point. And the nice thing about skills is that they’re just markdown files you can adjust them for your own patterns.

Code audits that once took days now complete in minutes, freeing us to focus on implementing the changes that drive value.

You can find the skill on GitHub.

Code Audits in the Days of AI