writing-tests

Gates whether a new test should exist and forces it to be efficient, protecting CI from low-value test bloat. Use before adding or substantially changing any pytest, Jest, or Playwright test — whenever an agent or engineer is about to write tests for a new feature, bugfix, or PR. Front-loads the value bar (every test must catch a realistic regression no existing test already catches; test behavior through the public interface, not implementation details; collapse near-duplicates into parameterized cases) and the efficiency bar (deterministic, isolated, fast; pick the cheapest test level; Django TestCase over TransactionTestCase; no sleeps, no real network). Includes a "don't write it" decision tree. For fixing an existing flaky test use `/fixing-flaky-tests`; after this gate says a Playwright test is warranted, use `/playwright-test` for mechanics.

Quality

91%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

92%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A high-quality, operational gate skill: executable code and named helpers make it directly actionable, the single-question decision flow with a PR-time checkpoint gives clear workflow validation, and the bug catalog is appropriately offloaded to a verified one-level reference. The only weakness is mild verbosity in a couple of rationale paragraphs.

Suggestions

Tighten the DRF validation section: the four-paragraph rationale on to_internal_value ordering, the exceptions-hog envelope, and the wiring-guard nuance could compress to the rule plus the code example and a one-line 'keep one DB-backed endpoint test as a wiring guard', trimming roughly a third of the tokens.

Compress the TransactionTestCase bullet's three nested cases into a short table or a single 'reach for it only when...' line; the current prose re-explains Postgres isolation orthogonality twice.

Consider moving the per-framework 'Always — determinism and isolation' and Frontend house rules into a short reference checklist, keeping SKILL.md focused on the gate decision.

Dimension	Reasoning	Score
Conciseness	Largely lean and assumes Claude's competence — rules are stated once as directives ('No time.sleep / arbitrary waits', 'Never commit .only') without explaining what a test is — but a few sections pad slightly, e.g. the multi-paragraph DRF validation rationale and the extended TransactionTestCase prose could tighten without losing the rule.	4 / 5
Actionability	Fully executable guidance throughout: a copy-paste-ready SimpleTestCase serializer example, specific helper names ('posthog/test/persons.py', 'create_person', 'add_cohort_members'), concrete selector guidance ('getByText', 'getByTestId', 'within(<small container>)'), and named tooling ('jest-no-byrole-name-queries' semgrep rule, 'self.captureOnCommitCallbacks(execute=True)') covering the common cases.	5 / 5
Workflow Clarity	The gate is a single explicit decision question with a concrete pass/fail answer and worked examples, followed by a sequenced 'five no's' triage, a cost ladder, and a 'Before you open the PR' validation checkpoint that closes the loop ('If you can't write that line, you've found a test that shouldn't be in the PR'). Validation is explicit and tied to a real recovery action.	5 / 5
Progressive Disclosure	SKILL.md is a well-organized overview that points one level deep to a real, verified reference file (references/mistakes-we-make.md) and two sibling skills, with the bulk catalog of bug shapes correctly deferred to that reference rather than inlined; navigation is clearly signaled with descriptive link text.	5 / 5
	Total	19 / 20 Passed

Description

91%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, concrete description that explicitly covers what the skill does and when to use it with natural trigger terms and framework names. It is highly specific and mostly distinct from sibling skills, with only minor overlap risk and slight over-padding from inlining several rules that the body elaborates.

Suggestions

Trim the inline rule enumeration ('every test must catch a realistic regression... collapse near-duplicates... deterministic, isolated, fast; pick the cheapest test level') — these duplicate the body and pad the description; a one-line 'front-loads a value bar and an efficiency bar' would stay clear and lean.

Move the per-framework mechanics ('Django TestCase over TransactionTestCase; no sleeps, no real network') into the body, since they are detail rather than trigger/what guidance and slightly blur the description's scannability.

Dimension	Reasoning	Score
Specificity	Lists several concrete capabilities — 'catch a realistic regression no existing test already catches', 'test behavior through the public interface, not implementation details', 'collapse near-duplicates into parameterized cases', 'pick the cheapest test level', 'Django TestCase over TransactionTestCase', 'no sleeps, no real network' — with only minor gaps in coverage compared to a fully exhaustive list.	4 / 5
Completeness	Explicitly answers both 'what' (gates whether a new test should exist and forces it to be efficient, front-loads value and efficiency bars) and 'when' ('Use before adding or substantially changing any pytest, Jest, or Playwright test — whenever an agent or engineer is about to write tests for a new feature, bugfix, or PR') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Comprehensive natural trigger coverage including the framework names users actually say — 'pytest, Jest, or Playwright test', 'new feature, bugfix, or PR' — plus the natural 'Use before adding or substantially changing any test' phrasing and concrete routing phrases ('write tests for a new feature, bugfix, or PR').	5 / 5
Distinctiveness Conflict Risk	Clear niche (test-writing gate for pytest/Jest/Playwright) with explicit routing to sibling skills ('/fixing-flaky-tests', '/playwright-test') that reduces conflict risk, but it could still overlap slightly with general testing guidance since 'writing tests' is a broad activity.	4 / 5
	Total	18 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 suspicious	Warning

	Total	15 / 16 Passed

Repository: PostHog/posthog
Path: .agents/skills/writing-tests/SKILL.md
Commit: 06292db

Reviewed: 17 minutes ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.