How to Use ub-mode in Claude Code and Cursor: Install Uncle Bob's Agent Skill and Run a Code Change Through Its Quality Gates

Introduction

Most coding agents will happily write the code you asked for and stop there. The tests may be thin, a function may carry three responsibilities, a block may be pasted twice with one variable renamed, and nobody notices until the next person touches the file. ub-mode is a single agent skill from Robert C. Martin, known as Uncle Bob, that refuses that stopping point. It drives one code change through three phases, First Make it Work, Then Make it Right, and Practice, with the middle phase enforced by deterministic tools, not by the agent’s judgment alone. This tutorial installs the skill in Claude Code or Cursor, then takes one small change through its gates: CRAP under 10 per function, duplication at rank 0.8 or above eliminated, mutation survivors killed or deleted, and the result reviewed before small ordered commits.

Quick answer

Copy ub-mode’s SKILL.md into ~/.claude/skills/ub-mode/ or ~/.cursor/skills/ub-mode/, invoke /ub-mode, and let it drive one small change through working code, quality gates, and small ordered commits.

Evidence

ub-mode arrived fast. The repository was created on October 25, 2026, and its GitHub page showed about 2,425 stars and 111 forks as of October 28, 2026, three days later. Read that velocity with care: a three-day-old repository with a famous author’s name attached attracts curiosity clicks as well as real adopters, so treat the star count as attention, not proof of production maturity. The skill text may still change, so this tutorial says where to pin your copy.

The author’s own framing is plain. The ub-mode repository describes the skill as “an agent skill that enforces disciplined software engineering principles when writing or changing code.” It is loosely based on portions of poteto-mode, a ruleset by another developer, reduced and paired with deterministic quality-gate tools. That pairing is the whole point: principles alone are easy for an agent to nod along to, while a tool that prints a number is not. When the agent claims a function is fine and crapper prints CRAP 24, the number wins.

The gates themselves are specific and measurable. Crapper computes CRAP as cyclomatic complexity squared times one minus coverage cubed, plus complexity, and ub-mode demands every function under CRAP 10. Dryer flags structural duplication at similarity rank 0.8 or above for elimination. Mutator runs mutation testing to expose uncovered code and surviving mutants. uml-viewer visualizes components, coverage, CRAP, mutation scores, and dependency directions. Note the strictness: crapper’s own documentation treats 1 to 5 as low risk and only 30 and above as complex and under-tested, while ub-mode holds every function under 10.

Prerequisites

• Claude Code or Cursor with agent skills support, plus a terminal. Grok is also listed in the README examples, but this tutorial covers the Claude Code and Cursor paths.
• A git repository with a small, real change queued up, ideally one function or one bug fix, not a refactor of a whole module.
• A test runner for your language. Crapper supports Clojure, Java, Go, TypeScript, Rust, and Python.
• git, and a willingness to review diffs. The skill ends with commits and a push, so keep the work on a feature branch.

Step 1: Install the single skill file

ub-mode is one skill, not a bundle, so installation is one file copy. The README says to copy SKILL.md into your agent’s skills directory as ub-mode/SKILL.md, then invoke /ub-mode. Its examples are ~/.grok/skills/, ~/.claude/skills/, and ~/.cursor/skills/. There is no Codex path in those examples, so this tutorial does not claim one.

For Claude Code, clone the repository and copy the file:

git clone https://github.com/unclebob/ub-mode
mkdir -p ~/.claude/skills/ub-mode
cp ub-mode/SKILL.md ~/.claude/skills/ub-mode/SKILL.md

For Cursor, use the same clone and the Cursor path instead:

mkdir -p ~/.cursor/skills/ub-mode
cp ub-mode/SKILL.md ~/.cursor/skills/ub-mode/SKILL.md

Verify the placement before you invoke anything. The file must be named exactly SKILL.md inside a directory named exactly ub-mode, directly under the skills directory. A common failure is copying it to ~/.claude/skills/SKILL.md without the ub-mode folder, or nesting it one level too deep inside the clone. Confirm one file at the expected path, start a fresh session, and invoke /ub-mode.

Pin the copy you verified. Because the repository is days old, clone once and update deliberately rather than re-copying on every session, so a silent upstream edit cannot change the gates mid-week. Diff your pinned copy against the repository when you choose to update.

Step 2: Get the four companion tools

The skill text instructs the agent to use crapper, dryer, mutator, and uml-viewer during the Make it Right phase. Clone all four:

git clone https://github.com/unclebob/crapper
git clone https://github.com/unclebob/dryer
git clone https://github.com/unclebob/mutator
git clone https://github.com/unclebob/uml-viewer

Crapper is the tool you will see first. Its README documents a concrete run: from a project root, ./crapper walks the tree, skips test, spec, vendor, node_modules, and target directories, prints a table worst score first, and writes .metrics/crap.edn, a snapshot that uml-viewer already reads. Useful variants include ./crapper --changed for git additions and edits only. Remember that ub-mode’s gate is stricter: every function under CRAP 10, not merely under 30.

For dryer, mutator, and uml-viewer, read each repository’s own README for its run command before you start, rather than guessing flags. The skill text states the outcome each tool must produce, but the exact invocation belongs to each tool’s documentation. If a tool is missing when the agent reaches its gate, the gate stalls, and that is correct: a gate that cannot measure should block, not wave through.

Step 3: Pick one small change

Do not point /ub-mode at a whole feature on the first run. Pick the smallest change that still exercises the loop: one bug fix, one new validation rule, or one function that grew a second responsibility. The skill’s Laziness Protocol says one decision lives in one place and you ship the smallest edit that solves the problem, so a small target is the method, not a compromise.

State the change in one sentence, then invoke the skill:

/ub-mode: fix the duplicate email validation in the signup handler,
so both the web form and the API path reject malformed addresses
with the same error.

Then let the agent work the spine in order. Do not skip ahead to the gates: the skill sequences work into verifiable units, finishing one small unit and checking it before starting the next.

Step 4: First Make it Work

The first phase is about getting the behavior right with the smallest possible edit. The skill text lists the moves: get the data shape right before writing the logic, do first whatever helps every later phase, write the failing test before changing the code, see it fail for the reason you expect, and make the smallest change that makes it pass. If an honest test is impractical, the skill says not to write a bad one.

Two moves deserve attention because agents routinely violate them. “Subtract Before You Add” means the agent should delete the duplicated validation block before writing the shared replacement, not leave both in place. “Attack the Premise” means that when two fixes sharing one premise fail the same gate, the agent should write that premise in one sentence and remove the assignment instead of starting a third fix. Watch for both in the agent’s log.

Architecture discipline runs through the same phase: model the domain so illegal states are impossible, check data where it enters, keep business logic pure, and make operations idempotent.

Step 5: Then Make it Right, through the gates

Work it gate by gate, and treat each gate’s output as a verdict, not a suggestion.

First, crapper. Run it on the changed code and read the worst score first, since that is how its table is ordered. Any function at CRAP 10 or above must come down by splitting it, by testing it, or both. The skill also says to consider whether case statements are worth reducing: a long switch is often the cheapest complexity to remove. Do not accept “the function is inherently complex” as a resolution; the gate exists to force the split or the test.

Second, dryer. Eliminate structural duplication at similarity rank 0.8 or above. The worked example’s duplicated validation is the textbook case: two blocks alike except for one variable should become one shared function with one test. Rank below 0.8 is not automatically fine, but the gate draws its line at 0.8.

Third, mutator. The skill’s three verbs are cover the uncovered, kill the survivors, and delete dead code. A surviving mutant is a test gap: the suite cannot tell the mutated code from the original, so add the test that can. Dead code that no mutant and no test touches is a deletion candidate. If a survivor cannot be killed by any honest test, the code is likely unreachable or the test is wrong.

Fourth, uml-viewer. Review the visualization of components, coverage, CRAP, mutation scores, and dependency directions before you declare the change done. This is where a dependency pointing the wrong way, or a component that quietly absorbed two responsibilities, becomes visible. The skill’s refactoring step says to pin what the code does, change the structure, and prove the behavior did not change.

Compare this with the tstack skills for the pull request loop: ub-mode disciplines the change, tstack disciplines what happens to the change after it is written.

Step 6: Follow Practice, then review before pushing

The final phase is small and easy to skip, which is why the skill writes it down. Keep a log of every action and the reason, and report that log upon completion. Guard the context window by keeping the main thread small and sending bulk work elsewhere. Clean up the worktree, confirming nothing still in use needs what you remove, and let uncommitted work wait for a decision.

Commits come last, and the skill is specific: commit often, in small ordered commits, where each commit says why, what changed, and how you proved it, then push to the main line at the end. Read the reported log and review the diff before that push. The log is your audit trail: if a gate was skipped or a survivor was left alive, the log is where you will see it.

For a next step after this loop feels routine, the n8n agent skills tutorial shows the other side of agent skills, teaching an agent to generate workflows rather than gate code changes, and the n8n complete guide collects the broader automation patterns these skills plug into.

Troubleshooting

The agent does not recognize /ub-mode

The cause is almost always placement. Confirm the file is at ~/.claude/skills/ub-mode/SKILL.md for Claude Code or ~/.cursor/skills/ub-mode/SKILL.md for Cursor, with exactly that directory and file name, and start a fresh session after copying. Sessions started before the copy will not see the skill.

The agent claims Codex support

The README installation examples as of October 28, 2026 list Grok, Claude Code, and Cursor only. If the agent asserts a Codex skills path, ask it to show the README line it is relying on.

A gate stalls because a companion tool is missing

Clone the four companion repositories and confirm each tool runs first. Crapper’s documented run is ./crapper from a project root. For dryer, mutator, and uml-viewer, follow each repository’s own README. A stalled gate is the system working: do not tell the agent to skip the gate, fix the missing tool instead.

CRAP will not drop below 10

Split the function, add tests, or both, in that order of preference. Check case statements first, since they are the cheapest complexity to reduce. If the function resists every split, suspect it carries two responsibilities: name them, extract one, and re-run ./crapper --changed.

Mutator survivors you cannot kill

A survivor is either a missing test or dead code. Write the test that distinguishes the mutant from the original; if no honest test can do that, delete the code. Never write a test that passes regardless of the code just to clear the gate: the skill text explicitly forbids bad tests, and a test that cannot fail certifies nothing.

The skill text changes under you

The repository is days old, so upstream edits are likely. Diff your pinned copy against the repository before updating, and re-verify the install path and gate thresholds after any update.

FAQ

What exactly is ub-mode?

ub-mode is a single agent skill, not a bundle, published by Robert C. Martin (Uncle Bob). It makes an agent follow a three-phase spine on every code change: First Make it Work, Then Make it Right, and Practice. The middle phase enforces measurable gates with four companion tools: crapper, dryer, mutator, and uml-viewer.

Does ub-mode work with Codex?

Not according to the README examples as of October 28, 2026, which list Grok, Claude Code, and Cursor skills directories only, with no Codex path. Do not assume a Codex skills path works; re-check the live README before claiming Codex support.

Do I need all four companion tools?

Yes, if you want the gates to actually run. The skill instructs the agent to use crapper, dryer, and mutator during the Make it Right phase, and uml-viewer visualizes the results. Without them, the agent can recite the principles but cannot measure the scores.

How is ub-mode different from tstack?

tstack skills cover the pull request loop: proving, reviewing, filing, babysitting, and merging a change. ub-mode covers the change itself: how the code is written, tested, and cleaned up before it ever becomes a pull request. The two complement each other.

Is it safe to let the agent commit and push?

The skill’s Practice phase ends with small ordered commits and a push, but it also requires the agent to keep a log of every action and report that log upon completion. Read that log and review the diff before the push lands on a shared branch, and keep the agent on a feature branch until you trust the loop.

Conclusion

ub-mode is a small file with a large claim: a code change is not done when it works, but when it works, passes measurable gates, and is committed in small ordered units with a log. Install the one SKILL.md file, give the agent the four companion tools, and run one small change through CRAP under 10, duplication below rank 0.8, mutation survivors killed or deleted, and a visualization review. If the loop feels strict, that is the point. Once it is routine, pair it with the tstack skills for the pull request loop to carry the gated change to a merged pull request.

Frequently asked questions