writing-unit-tests skill (riekelt): test the contract, not the implementation

Makes Claude write unit tests that check behavior, with names that state the claim and no sleeps or real network.

Installs: 20.4K; on skills.sh
Stars: 7; on GitHub
Updated: Sep 2026; last repo commit

writing-unit-tests fires when Claude writes, refactors or fixes a unit test, including a flaky or unreadable one. Its rule is to test the contract, not the implementation: one behavior per test, a name that states subject, scenario and outcome, and expected values worked out independently instead of computed with production code. It also bans sleeps and real time, randomness, network or filesystem in a unit test, and treats every mock as an assumption. It names principal-engineering as required background.

Good for

Developers who want Claude's new tests to survive a refactor
Anyone fixing a flaky or unreadable test
Reviewers tired of mirror tests and mock-only tests

Install writing-unit-tests

Claude Code

Copy this prompt.

Install the writing-unit-tests skill in Claude Code. Run this command:

/plugin marketplace add riekelt/principal-engineer
/plugin install principal-engineer@principal-engineer

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route. The plugin installs all 11 skills in the repo, plus one agent (change-verifier) and two commands (/verify and /preflight), counted from the git tree. writing-unit-tests names principal-engineering as required background, so the skills CLI and folder routes below install both. There is no Claude app upload route: the README documents only the Claude Code plugin and the other-agents routes.

From the project README. Source.

What's in the skill

When it loads

Use when writing or refactoring unit tests - a new test file, added cases, a flaky test, an unreadable one. Encodes behavior-first testing: one behavior per test, names that state the claim, deterministic setup, mocks only at boundaries you do not own. Use whenever a test is being written, even a quick one, and whenever a test needs a sleep, a mock of your own code, or a copy of the implementation's math.

Sections in SKILL.md

Overview
Contract over implementation
One behavior per test, named as the claim
Determinism
Mocks are assumptions
Assertions and failure paths
Common mistakes

Key facts

Author: riekelt (named as author in the plugin manifest)
License: MIT per the README and plugin.json; the repo has no LICENSE file and GitHub shows none
Installs on skills.sh: 20,415 (Nov 2, 2026)
GitHub stars: 7 for the whole riekelt/principal-engineer repo (Nov 2, 2026)
Last repo commit: Sep 11, 2026
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
What it includes: 1 file: SKILL.md (counted from the git tree)
Part of: The principal-engineer plugin: 11 skills, 1 agent and 2 commands (counted from the git tree)
Needs: The principal-engineering skill, named as required background in SKILL.md
Works in: Claude Code via the plugin; other agents via a plugin loader or symlinked skill folders, as the README describes

What it includes

Tests through the public contract; expected values are literals
Three rules. A refactor that preserves behavior should not break tests, and expected values are worked out independently with the derivation in a comment.
Write · Contract over implementation
Subject, scenario and outcome in the name; arrange, act, assert
The skill's example is expired_token_is_rejected_with_401, not test_auth_3. Tests contain no branching or loops.
Write · One behavior per test, named as the claim
No real time, randomness, network or filesystem; no sleeps
Inject the clock, seed or inject randomness, mock the boundary. Async waits poll the outcome with a deadline.
Write · Determinism
Mocks only the boundaries you do not own
When a test is mostly mock wiring, widen the unit or accept that the seam needs an integration test.
Write · Mocks are assumptions
Asserts outcomes with values and treats failure paths as first-class
Tests follow the no-silent-swallows contract: no catch-and-ignore, no conditional assertions that skip silently.
Write · Assertions and failure paths
Names six traps, such as the mirror test and the mock echo chamber
The six: mirror test, mock echo chamber, mega-test, shared mutable fixtures, the sleep that "fixes" flakiness, and green-checking the fixture.
Read · Common mistakes

From the official docs

Permissions

Low risk

writing-unit-tests is instructions for Claude and the plugin route adds an agent and two commands. Our advice: review the diff after each session and keep your tool's permission prompts on.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

The plugin route adds an agent that can run shell commands
change-verifier lists the tools Read, Glob, Grep and Bash, and the plugin adds the /verify and /preflight commands. The repo tree has no hooks or MCP config files. Use the skills CLI route to install only this skill. github.com

Technical details

Turning on read-only	SKILL.md describes no read-only mode.
Sign-in and keys	SKILL.md names no account, key or token.
Scopes	Claude writes and edits test files and fixtures in your repository The plugin route also installs 10 other skills, one agent and two commands

Questions

What does writing-unit-tests do?

It makes Claude write unit tests as named behavioral claims. Tests go through the public contract, take one behavior each, avoid real time, randomness, network and filesystem, and use mocks only at boundaries you do not own.

How do I install it?

Use the install box at the top. The skills CLI and folder routes add principal-engineering as well, because this skill names it as required background. testing-changes is an optional companion. The plugin route installs all eleven skills.

How is it different from testing-changes?

writing-unit-tests is the craft of the tests themselves. testing-changes governs which tests a change owes in the first place, including the regression test for a bug fix.

Does it work with any test framework?

SKILL.md names no framework. It describes rules for tests in general and says property-based tests are the accepted form for invariants and follow their framework's shape.

Does it work in the Claude app or Codex?

The README documents the Claude Code plugin and, for other agents, a plugin loader pointed at plugins/principal-engineer/ or symlinked skill folders. It documents no Claude app upload route.

Is it safe to install?

The skill folder bundles no scripts. It leads Claude to write and edit test files in your repository, so read the diff. The plugin route also adds an agent, covered under "Watch out for".

Information

updated Nov 2, 2026

Repository: riekelt/principal-engineer
Folder: plugins/principal-engineer/skills/writing-unit-tests

riekelt/principal-engineer skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

writing-unit-tests SKILL.md · github.com
principal-engineering SKILL.md · github.com
README · github.com
plugin.json · github.com
testing-changes file · github.com
change-verifier agent · github.com