In this stream, Chad installed Jose’s experimental Claude skill and put it though it’s paces auditing our internal operations platform, which is a 10+ year old Rails codebase, with plenty of legacy surface area. You can watch the full replay on YouTube or read on for what we learned about auditing Rails apps using Claude skills.

What are Claude Skills?

Agent Skills are an open, file-based format maintained by Anthropic and open to contributions from the community. At its most basic, a skill is a SKILL.md file with YAML front matter, and a markdown body of instructions. Anthropic has introduced skills across Claude, and Claude Code looks for them in your repo or on your local machine, usually under ~/.claude/skills/.

It’s a bit like human-authored tool calling: The short front matter stays lightweight, and the content only loads when the skill is relevant, or if you invoke it explicitly.

What goes into rails-audit-thoughtbot?

Jose’s new experimental skill encodes thoughtbot-flavored Rails best practice. Let’s allow the code to speak for itself. Here’s the YAML from matter at the top of rails-audit-thoughtbot’s 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.
---

As you can see, the long description is what Claude Code uses to decide when the skill should be applied; the rest of the file stays unloaded until the skill runs.

In developing this skill, Jose drew on our free books Ruby Science (code smells and fixes), Testing Rails, as well as a security checklist (12 categories with detection patterns), and a report template so the audit output is structured and comparable between runs. Following the feedback from this livestream, he added references/rails_antipatterns.md, a reference drawn from Chad’s book Rails Antipatterns that extends the audit with external services, migrations, performance, and failure-handling patterns.

The skill is open-source and available at thoughtbot/rails-audit-thoughtbot. Feel free to clone or copy it into your skills directory and get ready to experiment.

Installing and running the skill

Chad started from a clean checkout of Hub: He created ~/.claude/skills, then cloned the rails-audit-thoughtbot skills repo into that directory. With a Claude Code session running in the terminal, after some debugging, Chad was able to call the skill using its name slash-command:

/rails-audit-thoughtbot

Tip from the stream: you do not have to audit the whole app on day one. The skill supports a targeted run inside a session, for example:

/rails-audit-thoughtbot audit controllers

or

Do a code review on my models

What the Hub run looked like

On a full-application pass, the skill took ~5 minutes to generate an audit report that summarized findings grouped by category (testing, security, models, controllers, code design, views) with assigned severities. Chad highlighted a few headline items:

• Large Model: a textbook god class on Person which runs to hundreds of lines and many public methods, aligning with what the team already knew from past code reviews.
• PORO: many service-style objects flagged for refactor toward ActiveModel-backed domain objects, per intentionally-opinionated PORO.
• Missing model specs The skills treated “no _spec per model file” as a gap but Chad dug in and noted this was a bit of a false-positive as view-model style objects had integration coverage instead.
• Positives: strong testing culture, good use of calculators, presenters, and query objects, no :focus tags in RSpec (Chad recommends against committing :focus: use line-number runs instead e.g. .\spec_name.rb:34).

Where human judgment still matters

The audit was promising but not perfect. A couple of areas where the skill could be improved included:

• Composition vs. wider design: recommendations leaned on extracting small objects with composition, which aligns with Ruby Science. However, for real refactors, Chad reminded us to ask whether the leverage is alongside or above a hot spot before following the first suggested carve-out.
• “Issues” that are really clean bills of health: for external API wrappers, the skill correctly said “no changes required,” yet still surfaced them under severity report styling meant for problems. Chad noted that for onboarding to a new codebase, calling out “we looked here and it’s fine” is valuable, but the skill’s report template could be updated separate passes from findings so readers are not misled.

Throughout, the audit was pretty consistent with how we begin client audits at thoughtbot: Move fast for orientation, then validate each area with deep domain knowledge.

How a thoughtbot services audit goes deeper

The stream’s run was overwhelmingly static analysis using Claude Code, which finished in ~5 minutes. Compared with 11–13 minutes for Hub’s full test suite alone, this was a fair tradeoff for a first pass. Chad contrasted the skill with what we typically do on client Rails audits: Run diagnostic tools like rails-flog, flay, Bullet for N+1s, execute the test suite, and attach real coverage metrics, folding all of that into the written recommendations. Following this stream, Jose picked up on Chad’s recommendations and added agentic support for running SimpleCov, and RubyCritic, which rolls-up rails-flog, flay and other analytics tools.

Chad also imagined CI hooks down the road: Not to block merges blindly, but to keep a living quality guide next to our style guide, maintain expert human oversight.

Test it out yourself

If you use Claude Code and maintain a Rails app, clone rails-audit-thoughtbot, run a full or targeted audit, and see how the report reads on your codebase. We would love reactions on the YouTube replay as well as issues and PRs on GitHub.

rails-audit-thoughtbot is experimental. It is a starting point, not a finished product. We actively encourage open-source contributions: Open an issue or fork the repo and open a pull requests with ways you think this Claude skill can work better for your team.

Get in touch

If your Claude Code skill audit surfaces more than your team has capacity for right now, get in touch with us. We have been auditing and reviewing Rails apps for a long time, and are excited to help prioritize what actually moves the needle for your business.

Roux is what we’d call a boilerplate – a generic and reusable piece of content (in this case, code), that can be used in any relevant project without much alteration. It serves as a solid foundation to build from, without having to start from scratch.

Do you have one or two patterns you’ve used from project to project? Great! You, too, can build a boilerplate.

What is a boilerplate?

Most of my favorite design terminology, like gutters, drop caps, pull quotes, come from newspapers and print journalism. Boilerplate is one of those…well, sort of.

Originally it’s a term from steamships in the 1800s. They were sheets of rolled steel to make boilers to heat water. These boilers generated steam for the ship’s engine.

By the late 1800s/early 1900s, some newspapers were using reclaimed steamship boilerplates for hot metal typesetting in their printing presses. Linotype machines (among a few others) allowed for this typesetting, pouring molten lead into a mold, and producing multiple typesets from that mold. Perhaps there was an article or an advertisement that you’d want to send out to multiple newspapers to set in their printing as they chose. These more widely became known as “boilerplates”, which were more conventional content that could be applied to a number of publications geographically.

The term has since grown from its newspaper beginnings, to being used in contract law with “boilerplate clauses” and now in code.

How it works in code

In development, boilerplates are generally defined as reusable bits of code, agnostic to the type of project. It’s something you can start a codebase with or insert along the way as needed. Some are extremely opinionated, some are looser. Some are very thorough, and some are sparse. What it all boils down to (heh) is having something that is useful to you that works in various contexts.

Boilerplates can be useful by:

• Standardizing opinions, rules, and best practices by your team’s agreed-upon conventions into a reusable starting point
  • Which in turn can ensure a consistent user experience with predictable and standardized interactions and patterns.
• Reducing decision fatigue because foundational choices are made (like CSS architecture), freeing you up to focus on more impactful work
• Minimizing human error by reducing or eliminating the risk of manual mistakes with repetitive setup tasks
• Accelerating onboarding that allows you or your team to jump into a familiar structure rather than inferring conventions from scratch

How you might approach writing your own

You probably already have a handful of code bits or content that you’re writing in the same or similar way over and over again – you just haven’t documented it. Take a look at your own corpus of code and see what emerges.

• Audit what you repeatedly build after looking at past projects and identifying a few patterns, structures, or sections you’re commonly recreating.
• Capture the annoying or painful bits. Useful boilerplates can solve the setup steps you may dread the most.
• Cherry pick from your best work with successful past projects. Sometimes that’s taking patterns in their entirety or frankensteining together bits from various projects.
  • For example, I had a modal element where I liked the slide in transition I did in one project and another where I felt it had better accessibility support, so I mushed them together into one pattern.
• Strip out the project-specific details for the parts you want to use and leave what’s universally useful.
• Include comments, notes, or annotations that explain why things are set up the way they are. This may be useful not just for other people reading your boilerplate, but future you who has since forgotten why you decided on a specific structure or syntax, etc.
• Treat it as a living document and update it as your opinions and standards evolve.

Most importantly, know that it doesn’t have to be complicated or involved. Your boilerplate can be just a few patterns that are helpful to just you. It doesn’t even have to be code – it can be designs or layouts that you build prototypes with; it could be structures for documentation that you commonly write out. And while we did just talk about iterating on your boilerplate, it can absolutely be something that you write once and never adjust.

Boilerplates in the age of AI

Why bother writing out a boilerplate if Claude or any other LLMs can do it for you? The output reflects patterns it’s trained on, which are not necessarily your patterns. It doesn’t know you or your team’s specific decisions you’ve made over the years. Articulating what good and useful looks like for you forces you to refine those standards and create a more solid source of truth.

Sharing your patterns

Even if your boilerplate may only have a narrow use case for yourself, opening it up to feedback can sharpen your own thinking. Others might spot a gap or inconsistency you’ve been too close to notice. Sharing can also help others adopt your useful patterns in their own work. More broadly, it invites people to build, adapt, and improve it. You may surprise yourself at how novel your own workflows are to others!

Last week, I wrote about building a management system with Claude Code in a week. That post covered the foundation:

• meeting transcripts,
• daily logs,
• a /morning command that pulls everything together.

By the end of week one, I had something useful. Week two is where I found out what “useful” actually meant.

Sixty-six commits in seven days. Fifteen commands created. Three deleted. The system grew, then pruned itself.

Tuesday: the explosion

Tuesday was the most productive day I’ve had with this system. I made twenty-eight commits. The morning started with refactoring my goals into concrete project files. By lunchtime, I’d created /inbox, a command to process my Things inbox one item at a time, following the GTD clarify-and-organise workflow.

The /inbox command was ambitious. It identified whether an item was a project or a single action. It created Things tasks, support files, and Trello cards in one operation. It detected duplicates. It had a --dry-run flag. By the afternoon I’d:

• added single-item processing,
• an “already-actioned” flow for items I’d dealt with but hadn’t tracked,
• and inline project creation, so I didn’t have to break out of the processing loop.

Then came /delegate, a Slack-based delegation command that sent a message, created a waiting task, and set a follow-up deadline. And /waiting, a simpler version for things that didn’t need a Slack message.

Here’s what /waiting looked like:

# Waiting Command

Create a "Waiting for" task to track a delegated
item or pending response.

## Arguments

- `<person> <topic>`: Create a waiting task
- No arguments: Prompt for person and topic

## Instructions

### Step 1: Parse Arguments

If arguments provided:
- First word = person
- Remaining words = topic

### Step 2: Gather Optional Details

1. Deadline: When to follow up if no response?
   Default: 1 week from today
2. Project: Add to a project?

### Step 3: Create Waiting Task

Use `mcp__things__add_todo` with:
- title: "Waiting for [person] to respond RE: [topic]"
- tags: ["Waiting"]
- deadline: Selected deadline

Twenty lines of instructions. That’s all it takes to codify a GTD pattern that I repeat several times a week. The command doesn’t do anything clever. It only makes sure the task title, tag, and deadline are consistent every time.

Wednesday: real work surfaces real needs

Wednesday brought four meetings: a candidate interview, two 1:1s, and a scheduling sync. The meeting transcripts needed processing. The Coverage Sync document needed updating. I built /covsync, a command that scans recent meeting notes and extracts topics for the weekly Coverage Sync document.

The difference between /covsync and /inbox lies in their origins. /covsync emerged because I was sitting in front of a Coverage Sync document that I needed to fill out. /inbox emerged because I should have a command for it.

The weekend: Brave New Work

On Sunday, I read Aaron Dignan’s Brave New Work and started applying it. I created project files for three initiatives:

• defining Fusion’s purpose,
• improving investment time visibility,
• and AI ethics guidelines.

Each one started with a tension, something that felt wrong about how the team operated, and a plan to address it through the team, not for the team.

That was the system doing something I hadn’t planned. It wasn’t only tracking my work. It was giving me a place to think about the kind of leader I wanted to be. A project file that starts with “the team will define their own purpose” is a different artefact from a task that says “write a purpose statement.”

Monday: the pruning

By Monday, I had too many commands. /inbox was the worst offender. It tried to handle the full GTD workflow in a single skill and had become unwieldy. I deleted it. I deleted /project too. Both tried to codify processes that worked better as conversations.

I also rewrote the commit message guidelines. The old version said, “focus on why, not how.” The new version gave a specific structure: Before, We wanted, We did. Every commit since has followed this pattern. It’s a small thing, but it lets me read the git history like a journal.

What I learned

The commands that survived week two share a trait: they do one thing, and I repeat it often enough to want consistency. /waiting creates a task with the right title format, tag, and deadline. /covsync gathers meeting notes into a specific document format. /morning assembles a briefing from five data sources.

The commands that died tried to be clever. /inbox tried to handle every possible inbox item. /project tried to formalise something that worked better as a conversation. They were frameworks for hypothetical work rather than tools for actual work.

Sixty-six commits in a week is a lot. But the system is smaller now than it was on Tuesday. That feels right. The value isn’t in the number of commands. It’s in knowing which ones to keep.

If you’re building something like this, start with the commands you’d use today. Not the ones you think you’ll need.