Build Tests with Agent Skills

When create atomic-testing scaffolds your project, it also installs four agent skills and project CLAUDE.md + AGENTS.md guides. The skills are plain-Markdown SKILL.md workflows in the open Agent Skills format, so they aren't tied to one tool: Claude Code and xAI's Grok Build discover them with zero setup, OpenAI's Codex CLI reads the same format, and any other agent can be pointed at them (see Works with your agent). Together they mean an AI agent working in your repo already knows the component-driver method — so instead of learning driver decomposition and locator APIs before writing your first real test, you can describe what you want tested in plain language and review what the agent proposes.

To be clear about where the AI sits: the skills help an agent build drivers and tests. What lands in your repo is ordinary atomic-testing code — deterministic, reviewable, and executed by your own test runner. Nothing about running your test suite involves AI.

The five-second version

Scaffolded with the defaults? Open your coding agent in the project and say:

Write tests for CheckoutPage

The scaffold-test-driver skill takes over: it inventories the @atomic-testing drivers you already have installed, proposes a driver tree for the page, waits for your go-ahead, then writes the drivers, scene, and tests — and runs them in every runner your project configures.

What gets installed

your-project/
├─ .claude/
│  └─ skills/
│     ├─ scaffold-test-driver/SKILL.md    # create a driver tree for a component or page
│     ├─ author-component-tests/SKILL.md  # write behavior tests against an existing tree
│     ├─ diagnose-test-failure/SKILL.md   # classify and fix a red or flaky test
│     └─ sync-test-driver/SKILL.md        # update a driver after the UI changed
├─ CLAUDE.md                              # names your detected framework, runner, and driver package
└─ AGENTS.md                              # the same guide for AGENTS.md-reading agents (Codex CLI, …)

A skill is a plain-Markdown workflow file that a skills-aware agent loads automatically whenever your request matches its trigger — there is no command to memorize. .claude/skills/ is the canonical location: Claude Code and Grok Build discover it as-is, while Codex CLI looks in .codex/skills/ (a copy or symlink away — see Works with your agent). The generated CLAUDE.md and AGENTS.md carry the same guide — one for the Claude Code / Grok Build ecosystem, one for AGENTS.md-reading tools like Codex CLI — stating your project's detected stack (framework, test engine, runner, driver package) so the agent reaches for the right packages without being told.

The four skills

The skills cover the whole life of a test — create → write → debug → maintain — and hand off to each other, which is why the scaffolder always installs all four:

You say something like…	Skill	What the agent does
"Write tests for CheckoutPage" · "I need a driver for the settings panel" · "Test this page"	scaffold-test-driver	Reuses the shipped drivers you already have, decomposes the component or page into a right-sized driver tree, shows you the plan before writing any file, then implements it with portable locators and verifies it in every configured runner.
"Add a test for the empty state" · "Cover the case where saving fails"	author-component-tests	Translates a plain-language behavior into driver calls plus assertions against your existing tree — with anti-flake defaults (waitUntil probes instead of sleeps) applied from the start.
"This test is flaky" · "It passes locally but fails in CI" · "Why is this red?"	diagnose-test-failure	Classifies the failure as flaky, brittle, vacuously green, or contaminated — confirms the diagnosis with a check, then applies the library's intended fix. Adding a sleep or stretching a timeout without a diagnosis is explicitly banned.
"I renamed the data-testid" · "This component changed — update its driver"	sync-test-driver	Re-probes the current DOM, diffs it against every locator the driver assumes, and updates the driver in place without regenerating the tree or breaking hand-written methods.

What's left for you

Less typing, not less control. The scaffolding skill stops at a plan checkpoint — a driver-tree diagram you approve before any file is written — and every skill runs your project's own test commands to prove its output, so what you review is a passing diff, not a promise.

The skills also encode the same method the rest of these docs teach: reuse shipped drivers before writing new ones, keep drivers right-sized (the decomposition rules are narrated in Decomposing driver trees), prefer portable locators, and verify in every environment. Understanding what came out is still worth your while — the Step-by-Step Tutorial teaches the same workflow by hand, and Core Concepts explains the pieces the agent assembled.

Getting the skills

Via the scaffolder (default)

create atomic-testing writes the skills and the CLAUDE.md/AGENTS.md guides by default; pass --no-agents to skip them. The flag reference lives in Scaffold in CI / non-interactive.

Adding them to an existing project

Installed the packages by hand, or scaffolded with --no-agents? Run the scaffolder now — it is safe on a configured project:

npm create atomic-testing@latest -- --no-install

It never overwrites your files: anything that already exists and differs (your runner config, your CLAUDE.md) is written as a <file>.atomic-example sibling for you to compare and delete, while the skills land in .claude/skills/ as usual. --no-install skips dependency installation since your packages are already in place.

Prefer not to run it? The skills are plain files — copy the four directories from .claude/skills/ in the atomic-testing repo into your project's .claude/skills/.

Works with your agent

The skills deliberately contain nothing vendor-specific — no Claude-only tools, no assumptions about which agent is reading them. How they load depends on the tool:

Agent	How the skills load
Claude Code	Auto-discovers .claude/skills/ — no setup.
Grok Build (xAI)	Reads CLAUDE.md and .claude/ (skills included) natively — no setup.
Codex CLI (OpenAI)	Supports the same SKILL.md format from .codex/skills/ — copy or symlink the four skill directories there — the scaffolder's generated AGENTS.md already points Codex at .claude/skills/.
Anything else	The skills are ordinary Markdown — point the agent at them: "follow .claude/skills/scaffold-test-driver/SKILL.md to build a driver for SettingsPanel" works in any tool that accepts a prompt.

One honest caveat: Claude Code is how the atomic-testing maintainers exercise these skills daily. Grok Build and Codex CLI compatibility follows from their adoption of the Agent Skills format rather than from this project's own CI — if you run the skills there, reports (good or bad) are welcome on the issue tracker.

Where the skills come from

They are the same skills the atomic-testing maintainers use to develop the library and its example apps, embedded verbatim into the scaffolder and kept in sync by CI — not a summary written for the docs. That's also why they're opinionated: they exist to keep generated driver trees consistent with the best practices these docs describe.