yaohuangguanyaohuangguan/agent-playbook/skills/write-tests/SKILL.md

write-tests

Skill1 starsChanged 2 days agoMITView on GitHub

Write or improve automated tests that can catch real defects in any language. Use this whenever you add or change tests, including unit, API, integration and browser tests, whenever a feature or bug fix needs test coverage, or whenever someone asks you to raise coverage. It prevents tests that pass without checking anything.

We split this skill into the rules it gives an agent

7 rules. 0 are common, 7 are distinctive, and 0 are very specific to this project.

0
Common
Most of the 63 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Read the code and a neighbouring test: Use the project's framework, helpers and naming.
line 18
Distinctive:
List what could go wrong: Before you write code, go through this list and keep every item that applies:
line 21
Distinctive:
Choose the level: Use the highest level that stays fast and repeatable.
line 34
Distinctive:
Read back stored state after a write.
line 59
Distinctive:
After a denied or failed call, confirm that nothing changed.
line 60
Distinctive:
Use 404 when the caller should not learn that the item exists.
line 99
Distinctive:
Do not use a sleep to wait for work to finish.
line 106

“Common” is measured: kept by at least 6 in 10 of the 63 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Write tests

A test is only useful if it fails when the code is wrong. Tests that repeat the implementation or mock everything raise the coverage number and catch nothing.

When to use

Any time you add or change a test. To find what is missing in an existing suite, start with audit-test-suite.

Steps

Read the code and a neighbouring test. Use the project's framework, helpers and naming. Do not add a test framework or a mocking library unprompted.
List what could go wrong. Before you write code, go through this list and keep every item that applies:
- Caller has no credentials, or belongs to someone else
- Input is empty, wrong type, at the limit, or one past the limit
- Item is missing, or already exists
- Dependency times out, errors or returns bad data
- The same request arrives twice, or two arrive at once
- Time boundary: exactly at the limit, and one unit either side
- State is wrong for this action, such as cancelling something finished
- A secret or private field could appear in output
- Existing users or existing data could change

Choose the level. Use the highest level that stays fast and repeatable.

Behaviour	Level
Pure rule: dates, parsing, limits	Unit test with a table of inputs
API, permissions, persistence	Real handler, real schema, test database
Third-party service	Real client code, stubbed at the network
Multi-step business flow	One ordered scenario through real entry points
UI behaviour	Browser test against a local app
Files, processes, OS behaviour	Real OS, on each platform you ship

Keep your own code real. Fake only what you do not control: third-party APIs, the clock and platform services. Never mock the function under test or your own modules. Import the real code, never a copy.
Make fakes strict. An unexpected call must fail the test. A fake that answers anything can hide a wrong URL or an unwanted write. It must also keep the behaviour your code relies on, such as transactions and foreign keys.
Write the test. Each case sets up its data, does one action, then checks the result. See the example for your language in the next section.
Assert the outcome, not only the response.
- Compare exact values.
- Read back stored state after a write.
- After a denied or failed call, confirm that nothing changed.
- Count side effects: one email, one charge, zero model calls.
- Plant a canary secret, then search the output for it.
Prove that the test can fail. Break the code on purpose, such as by removing the check. Run the test and confirm that it fails with the expected message. Restore the code and confirm that it passes. If it still passes while the code is broken, the test is worthless, so fix it.
Confirm it runs in CI. Find the script or job that executes this file. New files outside the configured pattern are silently never run.
Finish. Follow verify-and-report.

Examples

Open only your language. Each folder has a small API and a complete test, covering permissions, limits, audit records, secrets, replays and concurrency.

Language	Guide	Test file
JavaScript, TypeScript	`references/javascript.md`	`examples/javascript/app-test.mjs`
Python	`references/python.md`	`examples/python/test_app.py`
Go	`references/go.md`	`examples/go/app_test.go`

For another language, read the closest example and translate it to the project's test framework.

Permission matrix

For each protected operation:

Caller	Expected	Also check
No credentials, or forged ones	401	Nothing changed
Valid user, someone else's resource	404	Nothing changed, same body as missing
Member without the required role	403	Nothing changed
Owner	2xx	Stored value is correct

Use 404 when the caller should not learn that the item exists. Follow the project's convention if it differs. Run the matrix over a list of endpoints, so that a new endpoint is one new row.

Timing rules

Pass the clock in, and use fixed timestamps for date rules.
Do not use a sleep to wait for work to finish. Wait for a condition.
A deadline only guards against a hang, so make it generous.

Stop and ask when

The code cannot be tested without a large redesign.
A correct test fails and the expected behaviour is unclear.
Testing would need real credentials or a production system.

Common mistakes

Tempting move	Why it fails	Do this instead
`assert result is not None`	Passes on almost anything	Assert the exact value
Mock the database and repository	Proves only the mock	Use a real test database
Copy the implementation's logic into the test	Same bug on both sides	Use known literal values
Change the expected value to pass	Hides the defect	Find out why it differs
Check only the response	Misses storage bugs	Read back the stored state
Test only success	Misses most real incidents	Use the list in step 2
Assert on source code text	Breaks on a move, misses behaviour	Run the behaviour
Snapshot a huge output	Reviewers approve noise	Assert the fields that matter

Checklist

It failed for the right reason when the code was broken.
It runs real code through a real entry point.
Unexpected external calls fail the test.
Denied calls are covered, and they changed nothing.
Limits are tested on both sides.
Side effects are counted.
It does not depend on timing, order or leftover state.
CI runs it.

Report

Tests added: <file: what each case proves>
Failure proof: <what you broke, and the failure message>
Runs in CI through: <script or job>
Not covered: <known gaps>

Download now (ZIP)

Other versions69 projects use a version of this.
Word for word · 2
Remote-Arc/remote-arc★ 5100% same
yaohuangguan/remote-arc★ 5100% same
Edited · 0
None found.
Wrote their own version · 67
remix-run/remix★ 33ksame name
elie222/inbox-zero★ 13ksame name
getsentry/sentry-javascript★ 8.8ksame name
dzhng/jevgrep★ 3.1ksame name
meta-pytorch/OpenEnv★ 2.8ksame name
huggingface/OpenEnv★ 2.8ksame name
JamieMason/syncpack★ 2.1ksame name
dzhng/skills★ 1.4ksame name
clice-io/clice★ 1.4ksame name
ryokun6/ryos★ 1.3ksame name
57 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Used alongsideProjects with it also use close-spec, design-with-images and 9 more.
Other files people use alongside this one.
- dzhngSkill
  close-spec
  When a spec under specs/<feature>/ is done shipping (a write-spec build, or any planned task that produced a spec), archive it to specs/done/ and rewrite it from a build-plan into a durable rationale — the why, the principles, the invariants — pointing back to the real code for the how. Use when implementation has landed and the plan no longer matches what shipped, or the user says a feature/spec is finished. Pairs with [write-spec](../write-spec/SKILL.md) (the plan this closes) and [review](../review/SKILL.md) (run before closing).
  Also in 5 projects that use this
- dzhngSkill
  design-with-images
  Explore UI and visual design with image generation, then iterate the real implementation against the user-selected concept. Use when brainstorming visual directions, offering mockup variants, or implementing an approved generated design; do not stop at the mockups or the first code approximation.
  Also in 5 projects that use this
- transitive-bullshitSkill
  compare-screenshots
  Compare screenshots against the intended design, distinguishing approved references from historical baselines. Use for iterative implementation matching, before/after visual review, objective image telemetry, or checking a lone capture for flat, empty, or badly framed content.
  Also in 5 projects that use this
- LucasMatuszewskiSkill
  audit-agents
  Audit and maintain agent configuration files (.claude/agents, AGENTS.md, CLAUDE.md, agent-memory). Checks for duplicates, outdated info, naming conflicts, wrong technical facts, and files over 200 lines. Fixes all issues and commits.
  Also in 5 projects that use this
- wolverin0Skill
  audit-decisions
  Standardize remediation decisions, baseline-policy entries, and legal-review banners for accepted, deferred, or policy-blocked audit findings.
  Also in 4 projects that use this
- rhnfzlSkill
  explore-unknowns
  Walk the user through mapping the unknowns of a task before, during, and after they build it, and hand them a four-quadrant map (settled ground, open decisions, taste, and landmines) they keep. Reach for this eagerly whenever a request is ambiguous or underspecified, the codebase or domain is unfamiliar, the user will "know it when they see it", a reference implementation must be understood before porting, a build-queue or architecture-changing task is about to start, a mid-build deviation needs capturing, or a finished change needs buy-in or verified understanding before merge. Trigger even when the skill is not named: "do a blindspot pass", "find my unknown unknowns", "interview me about this change", "brainstorm the approach for a task I am about to build", "help me scope this", "what am I missing here", "plan this before I build", "I know nothing about X in this codebase". When a territory profile is present it reads memory and the graph first and feeds the map into the build pipeline; without one it degrades to a plain general map. Not for trivial or mechanical tasks with clear acceptance criteria, single-fact lookups, pure debugging of a known symptom, or pure code review, those have their own tools. Do not use it to run the build itself; the map is the deliverable and implementation remains a separate task, whether it has not started or is already underway.
  Also in 5 projects that use this
- +5 more from dzhng
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- audit-test-suiteSkill
- change-data-safelySkill
- debug-failureSkill
- fix-flaky-testSkill
- hand-off-workSkill
- implement-changeSkill
- orient-in-codebaseSkill
- refactor-safelySkill
- review-codeSkill
- secure-changeSkill
- use-external-apiSkill
- verify-and-reportSkill
- write-pull-requestSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free

7 rules. 0 are common, 7 are distinctive, and 0 are very specific to this project.

Write tests

When to use

Steps

Examples

Permission matrix

Timing rules

Stop and ask when

Common mistakes

Checklist

Report

Word for word · 2

Edited · 0

Wrote their own version · 67

close-spec

design-with-images

compare-screenshots

audit-agents

audit-decisions

explore-unknowns

Does it work?

No reviews yet

Your trail

Now do this for your own.