Skill packLesson

Engineering skills

An agent writes code faster than anyone can read it, so the useful question is what tells it, and you, that the code is right. The Skill pack's engineering Skills each answer part of that: a test that fails first, a bug caught by a check that goes red, a review that compares the change with both the repo's rules and the request, and cheap answers to design questions before any of it.

Know these Skills already? Skip to In Terrarium.

Outside the box · General

The concept

These from the pack shape how a change gets built and checked. The agent can reach for any of them on its own when the task fits.

tdd is the red-then-green loop: write one failing test, then only enough code to pass it, one slice at a time. Tests sit at seams, the public boundaries where behaviour can be seen without reaching inside, and the seams are agreed with the person before any test is written. The Skill names three traps: tests coupled to the implementation, tests that recompute the expected value the way the code does, and writing every test before any code. Refactoring is left out of the loop on purpose; it belongs to review.

diagnosing-bugs starts from the same idea. Its first phase, the one it calls "the skill", is a feedback loop: one command, already run, that goes red on this exact bug, gives the same verdict every run and takes seconds. Only then does it reproduce and shrink the case, rank several falsifiable hypotheses, test them one variable at a time, write the regression test before the fix, and remove its tagged debug logs. Where no seam lets a regression test catch the real bug, it records that as a finding rather than write a shallow test that gives false confidence.

code-review reviews the diff from a fixed point, such as a branch or commit, on two axes. Standards asks whether the change follows the repo's documented rules, plus a baseline of code smells from Martin Fowler's Refactoring that a documented rule always overrides. Spec asks whether it does what the originating issue asked, no more and no less. Each axis runs in its own sub-agent, and the two reports stay separate, so a change that passes one can't hide that it fails the other.

prototype builds throwaway code to answer one design question: a single HTML file for "does this logic feel right", or several switchable variants on one route for "what should this look like". When it is done, the decision goes into the real code and the prototype is kept on a branch outside main, linked from the issue.

research sends a background agent to answer a question from primary sources, such as official docs, source code and specs, and writes the findings with their sources to one Markdown file where the repo keeps such notes.

Full referencemattpocock/skills on GitHub

Looking inside

In Terrarium

Each of these is a pack Skill in .agents/skills/, kept exactly as installed (Skill packs). Terrarium leaves most of them optional and makes one a fixed step.

That step is code-review. Before a branch's first push, a session runs code-review against origin/main, fixes what it finds, and then runs pnpm gate:scoped on the final head, as docs/agents/pr-workflow.md sets out. A simple change gets the author's own read of its diff instead, and the same file says what counts as simple. An integration PR that stacks several reviewed stories gets one more review of its whole diff. The Standards axis has no single standards file to read here: Terrarium's rules live in CLAUDE.md, in .claude/rules/ and in the docs those point to.

One runs the loop from end to end. In .claude/workflows/clear-backlog-build.js, a build agent follows the pack's implement Skill, test-first with tdd. The script then runs the two review axes as parallel agents of its own, each reading the code-review Skill and applying one axis. A fix agent takes the findings worth fixing, and the review runs again, up to a fixed number of rounds. When no finding is worth fixing, a final-gate agent runs pnpm gate:scoped again on the branch's head:

.claude/workflows/clear-backlog-build.js ↗156–174as of 1 Nov 2026

156  for (let round = 1; round <= MAX_ROUNDS; round++) {
⋯    // …
163    const all = reviews.flatMap(r => r.findings)
164    const toFix = all.filter(f => f.worthFixing)
165    out.judgementCalls = all.filter(f => !f.worthFixing)
166    if (!toFix.length) {
167      // Re-gate unconditionally: a stale gatePassed: true is the usual failure (#2523).
168      const gate = await agent(gatePrompt(b, out.worktree), { label: `gate ${b.name}`, phase: 'Review', schema: WORK, ...modelOf(b) })
169      out.verdicts.push(...tagged(gate, `gate ${b.name}`))
170      if (!gate || !gate.gatePassed) return { ...out, status: 'failed', reason: `final gate: ${gate ? gate.reason || 'gate:scoped did not pass' : 'gate agent returned nothing'}` }
171      out.commits = gate.commits
172      out.decisions.push(...gate.decisions)
173      return { ...out, status: 'ready-to-push' }
174    }

A branch comes out ready to push when only judgement calls are left and that gate passes; a failed gate, or findings still worth fixing after the last round, marks it failed. A ready branch is pushed and then checked again by the in CI.

The other Skills are reached for when the work calls for them; the pack's wayfinder Skill, which plans a large piece of work as tickets on the issue tracker, names prototype and research as two of its ticket types. How much each Skill matters here, and why, is in the .

Why it's built this way

Review before the first push. A pushed branch gets its PR at once, and an agent merges its own PR on a green CI run, so review comes before the push, for prose too: Skills and rules steer every later session. The cost: nothing checks that the review ran; the merge script asks only for a posted verdict. ADR-0004 (docs/adr/0004-objective-safety-gate.md).
One more review for an integration PR. Each story of a large change, built and reviewed as its own PR, was reviewed alone, and a review of one story can't see how correct stories interact. So the whole diff gets one more review before the integration PR opens. The cost: code already reviewed is read again, as part of the whole. docs/agents/pr-workflow.md
Pack Skills as installed. These Skills are the pack's own and are never edited here, so a reinstall can't overwrite a local change; Skill packs gives the reason and its cost. ADR-0015 (docs/adr/0015-audit-skills-and-conditional-importance.md).
The loop as a workflow script. The loop's script is a real file in .claude/workflows/, named by the clear-backlog Skill that runs it; Workflow scripts says why it sits outside its Skill's folder. ADR-0005 (docs/adr/0005-skill-model.md).

What to watch for

Re-check what a reviewer cites. A review sub-agent can quote a line that isn't there. Terrarium's Inventory entry for code-review asks each review brief to restate "verify before you state", and every cited line to be read again before it is acted on.
Name a kept branch by the rules. wayfinder's research findings and the code prototype keeps each sit on a branch that gets no PR; name it as ADR-0003 (docs/adr/0003-agent-operating-model-and-governance.md) says.

Try it in your project

Next time you review a change, run it as two separate passes: first only against your project's written rules, then only against the issue it closes. Note which findings the second pass found that the first missed.

Where next

Last updated 1 Nov 2026 · Latest source on GitHub ↗