37signals-skills: agent instructions for writing Rails the Basecamp way

Skills as text files, not a library

The 37signals-skills repository is a community project, and it says so at the top. It is unofficial, based on 37signals' public code and discussions, and not affiliated with or endorsed by 37signals.

What it actually contains is two things. The first is a set of agent skills, and the second is a longer reference guide. The skills are the part your assistant reads; the guide is the part you read.

The format is worth understanding because it determines the whole install story. Each skill is a plain SKILL.md with YAML frontmatter, in the Agent Skills format, and most SKILL.md-compatible tools can load them as-is. There is no plugin to install, no runtime, no dependency, and nothing to compile. If your tool does not understand the format, you can paste the contents into your system prompt or rules file.

The claim the project makes for itself is that you drop the skills into Claude Code or Cursor and your agent starts applying the same patterns 37signals uses: rich domain models over service objects, state as records, CRUD-everything routing, fixtures over factories, vanilla Rails over gems.

The two directories at the repository root are `skills/` and `guide/`, plus a CLAUDE.md and a .gitignore. There is no code at all, and the primary language is recorded as unknown, which is the honest classification for a repository of Markdown.

The provenance is stated as well. The skills are extracted from Fizzy, Campfire, and 100 or more of DHH's code reviews, and the guide was extracted by analyzing 265 pull requests in 37signals' Fizzy codebase, not just the final code, but the reviews, trade-offs and iterations that led to it. The acknowledgements credit 37signals for open-sourcing their codebases, Rob Zolkos for identifying and cataloging the most educational pull requests, and Claude Code for creating the guide through iterative deep-dive research sessions.

One automatic skill, six on demand, and a slash command

The skill table is the index of the project, and the invocation column is the part that tells you how it behaves.

`rails-best-practices-core` is marked Automatic. It covers architecture, naming, modelling patterns, REST routing and authorization, and is described as the baseline for all Rails work. So this one loads whenever the assistant is doing Rails work at all.

The rest are On demand: `rails-hotwire-realtime` for Turbo Streams and Frames, morphing, Stimulus, ActionCable, presence, optimistic UI and web push; `rails-jobs` for Active Job design, the `_later` and `_now` conventions, Solid Queue, recurring tasks and retry policy; `rails-migrations` for safe schema changes, staged rollouts, script backfills and multi-DB or multi-adapter setups; `rails-security-multitenancy` for path-based tenancy, the Identity to Session to User auth flow, scoped lookups, SSRF, CSRF and rate limiting; `rails-testing` for Minitest and fixtures, a coverage budget, Turbo and broadcast assertions and multi-tenant test wiring; and `rails-webhooks` for outbox delivery, failure classification, delinquency circuit breakers and payload signing.

And then `dhh`, invoked with `/dhh`, whose description is to review code like DHH would, that is, direct, opinionated and allergic to over-engineering.

The reason six of the eight are on demand is stated plainly: they are marked `disable-model-invocation: true` so they do not bloat every request, and you invoke them explicitly, for example as a slash command, or let the core skill point to them. That is a design decision about context budget, and it is the same reasoning that produced the skill format in the first place. A skill that loads on every request costs tokens on every request, so the ones that apply to a narrow task are opt-in.

The `dhh` skill is the most interesting of the eight to look at, because a slash command that applies a named reviewer's judgement is a different kind of tool from a checklist. It is closer to a persona than a rule set, and it is the one that a team would argue about installing.

Copying into Claude Code, Cursor or Codex

Installation is a clone and a copy, and the three supported tools each have their own directory.

For Claude Code, you copy the skills you want into your personal or project skills directory:

git clone https://github.com/marckohlbrugge/37signals-skills.git

# Personal (all projects)
cp -R 37signals-skills/skills/* ~/.claude/skills/

# Or per-project
cp -R 37signals-skills/skills/* your-app/.claude/skills/

Then you ask for a review with `/dhh`, or just write Rails code, at which point the core skill activates automatically.

For Cursor, the copy is per-project only:

# Per-project
cp -R 37signals-skills/skills/* your-app/.cursor/skills/

For Codex, the skills go into the global Codex skills directory:

git clone https://github.com/marckohlbrugge/37signals-skills.git
mkdir -p ~/.agents/skills
cp -R 37signals-skills/skills/* ~/.agents/skills/

Codex can invoke skills explicitly with `$skill-name`, for example `$dhh`, or automatically when a task matches the skill description, and the documentation advises restarting Codex if the new skills do not appear.

The copy approach has an obvious problem, and the project offers the fix. To stay up to date, clone the repo somewhere permanent and symlink instead of copying:

ln -s "$(pwd)/37signals-skills/skills/"* ~/.claude/skills/

and for Codex:

mkdir -p ~/.agents/skills
ln -s "$(pwd)/37signals-skills/skills/"* ~/.agents/skills/

After that, `git pull` gets updates. The symlink form is the better default for anyone who intends to keep the skills, and the copy form is fine for a one-off look at what is inside.

The guide is thirty five topics of extracted practice

The guide directory is the larger half of the repository, and the README describes the skills as distilled from it. It covers about 35 topics, and the index is organised by subject rather than alphabetically.

The core Rails topics are routing, controllers, models and views. The frontend set is Hotwire, Stimulus, CSS, accessibility and mobile. The backend set is authentication, multi-tenancy, database, background jobs, caching and performance.

Real-time and communication covers ActionCable, notifications and email. Features covers webhooks, workflows, watching, filtering and AI/LLM integration. Rails components covers Active Storage and Action Text.

Infrastructure and testing covers a security checklist, testing, configuration and observability. And the last group, Philosophy and People, covers development philosophy, what they avoid, and three separate pages on DHH, Jason Zimdars and Jorge Manrubia. That last group is a strong signal about the project's character. Most of these files are about architecture, but three of them are about individuals and how they think, which is the part of a style guide that cannot be reduced to a list of rules.

The quick start section condenses the philosophy into eight numbered points, and it is the most quotable thing in the repository: rich domain models over service objects, CRUD controllers over custom actions, concerns for horizontal code sharing, records as state over boolean columns, database-backed everything with no Redis, build it yourself before reaching for gems, ship to learn because prototype quality is valid, and vanilla Rails is plenty, so maximize what Rails gives you.

Each of those eight is a position that a Rails shop can disagree with, and that is the point. The value of a style guide is not that it is right, it is that it is specific enough to argue with.

The README tells you to take it with a grain of salt

Two caveats in the README are unusual enough to be worth reading before you install anything.

The first is about how the content was made. The guide and these skills were largely produced by an LLM, Claude, analyzing source code, PR descriptions and code snippets. The README says there may be hallucinations or inaccuracies, and to take everything with a grain of salt and verify against actual implementations.

That is a significant admission, and it changes how the project should be evaluated. This is not a curated style guide written by 37signals engineers. It is a machine-generated synthesis of a codebase, which means the most likely failure mode is a confident, well-formatted, plausible claim about how Rails works that is subtly wrong. The formatting is uniform, which is exactly what makes a hallucination hard to spot in a long document.

The second is about licensing, and it is the one that matters if you copy code rather than ideas. Code examples extracted from Fizzy are licensed under the O'Saasy License, and the README asks you to review that license before using code snippets in your projects. So the repository's own licence does not cover the code examples in the guide. A style guide that is read and internalised is one thing; a snippet that is pasted into a product is a different legal question.

There is also a limit on the source. The guide was extracted from one codebase, Fizzy, with 265 pull requests analysed, plus Campfire and 100 or more of DHH's code reviews. That is a real sample of how one well-resourced company builds software, and it is not a sample of Rails generally. Teams that write software for a different market, or that have constraints 37signals does not, will find parts of it that simply do not apply.

The last push to the repository was on 2026-06-09 and there are no GitHub releases, so the guide and the skills change in place as a fork is pulled.

Editorial conclusion

Adopt 37signals-skills if you work in Rails and want an assistant that defaults to the same modelling and routing choices 37signals makes, since the skills are plain text files you can read before installing. Do not adopt it as an authority on Rails itself, because the README says the guide was largely produced by an LLM and may contain inaccuracies, and check the licence of any code snippet you copy, since examples extracted from Fizzy fall under a separate licence rather than the one covering this repository.

Frequently asked questions

Official sources

1. Issues
2. marckohlbrugge/37signals-skills on GitHub
3. README