AI-powered test authoring with Claude and Playwright: Skills, Agents & CLAUDE.md (3/5)

Chapter 3 — Skills, Agents, and CLAUDE.md

The how, the who, and the map

Introducing Claude to the project: orchestration, execution, and the entry point.

When you drop Claude Code into a repo, you have three primitives to work with. The mistake is treating them as interchangeable places to stuff instructions. They’re not. Each answers a different question, and the whole design gets clean the moment you assign each its own question.

CLAUDE.md — the entry point (“what is this place?”)

CLAUDE.md is the first thing Claude reads, every session. It's not the manual — it's the map to the manual. Ours is deliberately short: the app is mobile-only on an iPhone; TC IDs are per-feature (TC_<PREFIX>_<NN>); there's a dismiss-the-modal quirk on first load; tests run with workers: 1; and — critically — here is where the real knowledge lives, and here are the skills and agents that do the work.

Its job is orientation, not detail. If a fact is only needed while performing a specific task, CLAUDE.md shouldn't carry it — it should point at whatever does. Overload the entry point and you pay for it on every single turn (the same context tax we just spent Chapter 2 avoiding).

Skills — orchestration (“how do we do this?”)

A skill is a workflow. It encodes the sequence — the phases, the order, the decision points, the guard rails. /write-test and /fix-test are our two skills, and they're mirror images: one authors new tests, one repairs tests after the app changes.

A skill defines how a job gets done: /write-test walks through seven phases — requirements → plan → capture → author → validate → docs → summary — and refuses to write a line of code before Phase 4. That ordering is the skill. It's the senior-engineer discipline ("understand and observe before you implement") written down as a procedure a newcomer can't skip.

Skills orchestrate. They don’t, themselves, go poke at a browser.

Agents — execution (“who does this part?”)

An agent is a specialist with a role, its own tools, and — this is the point — its own isolated context. When a phase needs a specific, noisy, self-contained job done, the skill invokes an agent to do it and hands back only the result.

Our agent is dom-scout. Its entire job is browser reconnaissance: drive the Playwright CLI, read the snapshot YAML, translate what it actually saw into verified Playwright locators, and return a clean table. It has three hard rules that make it trustworthy — never invent a locator it didn't observe in a snapshot, follow the locator-priority order strictly, and it's read-only (no Edit/Write, it never touches your POM or spec files). It also has no user channel: if something's ambiguous, it reports it upward rather than guessing or asking.

That isolation is exactly the Chapter 2 payoff realised: all the browser noise happens inside dom-scout's context and evaporates when it returns. The /write-test skill's context stays clean, holding only the distilled locator table.

How they fit together

The division of labour is the whole idea:

CLAUDE.md says what this project is and where to look. Skills define how a job is done — the phases and guard rails. Agents define who executes a given step — role-bound specialists with isolated context. A skill runs the workflow and, at the phase that needs it, invokes an agent to do the heavy, noisy execution.

Concretely: you type /write-test. The skill runs the requirements Q&A and the planning itself (it wants that in the main conversation — it's talking to you). Then at Phase 3 (capture) it spawns dom-scout with a target path and a capture checklist. dom-scout drives the browser off in its own context and hands back a locator table. The skill takes it from there — confirms with you, writes the code, validates, summarises. Orchestrator and executor, each doing only its job.

The problem this creates

Here’s the catch, and it’s the whole reason for the next chapter. Both skills need the same facts: locator priority, file layout, TC-numbering rules, tagging conventions, the app’s quirks. So does dom-scout, when it translates a raw element into a properly-prioritised locator. So does a human reviewing the PR.

If I write those conventions into each skill and each agent, I now have four copies of the truth. Update one, forget the others, and my tooling starts quietly disagreeing with itself — the exact drift I built this system to prevent. As you add skills and agents, CLAUDE.md and every reference file balloon and go out of sync.

The building blocks, left alone, become unwieldy. There has to be one place the truth lives, that all of them read from.

← Previous: Chapter 2 — MCP or CLI? → Next: Chapter 4 — One Folder to Ground Them All