Distributed Systems Testing Skills
Two skills for testing distributed systems: a test plan built from the product's promises and a fault-injection run with verdicts.
- 231 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The executing skill generates load and injects faults into the system under test: network partitions, node stops, ordering violations.
- In author mode the skill writes test skeletons straight into the repository under test, and a run creates logs and scripts under `test-sessions/`.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/distributed-systems-testing-skillsDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The executing skill generates load and injects faults into the system under test: network partitions, node stops, ordering violations.
- In author mode the skill writes test skeletons straight into the repository under test, and a run creates logs and scripts under `test-sessions/`.
This is third-party code. Review the repository files before installing.
What it does
Distributed Systems Testing Skills is two skills in SKILL.md format. `designing-distributed-system-tests` walks the repository, lists what the product promises, builds failure hypotheses and writes a plan to `docs/testing-plans/<slug>.md`: every scenario is named after the property it tries to falsify. For safety, durability, idempotency, isolation and ordering properties a scenario also binds an abstract model, an operation-history schema and a named checker, such as linearizability or no-lost-ack. The second skill, `executing-distributed-system-tests`, reads the plan, looks for existing tests and fault-injection tooling inside the system, probes the environment and runs the scenarios. For each one it records that the fault really landed and assigns one of ten verdicts with a blame tag: the system under test, the harness, the checker or the environment. The output is a `findings/report.md` report with a coverage adequacy assessment.
Who it is for. Engineers on databases, queues and other stateful services who want a fault-injection test plan and a report fit for a release decision.
Good fit when
- Before a storage or broker release you want one test plan instead of a scatter of integration tests.
- A commit or pull request changes replication and tests have to be planned for that exact change.
- A team suspects lost acknowledged writes under a network partition and wants a linearizability checker to confirm it.
- A chaos run came back green and you want proof that the fault actually landed.
- Existing tests should be matched against what the documentation promises to expose coverage gaps.
Not a fit when
- A stateless service with a single database: a pipeline of plans, models and checkers will not pay off.
- You need a tool that injects faults itself: the skills steer the agent through a process, while injection tooling comes from the system or the environment.
- Checks would run on a production cluster: the executing skill generates load and faults.
- You want a quick test of one function: the skills are built for multi-node scenarios.
Example request
Design a project-wide test plan for this codebase.Limitations
The skills set the order of work but do not install the checking tools themselves: fault-injection tooling and checkers come from the system under test or the environment, and the executing skill runs installs with `sudo` only with your approval. The project is early: the author warns that SKILL.md files and templates will change often, and runs so far covered a handful of systems, including AgentDB and LMCache. The `evals/` folder holds manual regression prompts that point to the author's local checkouts, so there is no automated suite. Installation creates symlinks under `~/.claude/skills/` and, for other agents, appends a block to `~/AGENTS.md`.
How to disable. Remove the symlinks `~/.claude/skills/designing-distributed-system-tests` and `~/.claude/skills/executing-distributed-system-tests`, and for other agents the marked block in `~/AGENTS.md`. The clone in `~/.local/share/distributed-testing-skills/` can be deleted entirely.
FAQ
How do I install the skills in Claude Code?
Send the agent the one-line request to read `INSTALL.md` from the link in the README: the file clones the repository and creates symlinks under `~/.claude/skills/`. Plugin route: `/plugin marketplace add shenli/distributed-system-testing`, then `/plugin install distributed-testing-skills@distributed-testing-skills`.
How do I update the skills?
Repeat the same request. `INSTALL.md` is idempotent: with an existing clone it runs `git pull --ff-only`, otherwise `git clone`, and with local edits it stops and asks you.
Which verdicts does the executing skill assign?
One of ten, for example `PASS-hardening`, `FAIL-reproducible`, `INCONCLUSIVE-fault-not-proven` or `PARTIAL-model`. A passing verdict cites a checker run and a signal that the fault fired.
How does change-scoped mode differ from project-wide mode?
Change-scoped mode builds a plan for a specific commit or pull request. Project-wide mode gives a holistic plan with an inventory of existing tests and a gap analysis.
Do the skills work outside Claude Code?
Yes, the README names Codex, Copilot CLI, Cursor and Gemini. They are plain SKILL.md files, and for other agents the installer adds a pointer to `~/AGENTS.md`.
Discussion
No questions or reviews yet.
Related
SkillsA library of 169 QA skills per language: test design, API, UI, regression, load, security and LLM testing.
Guides for agents writing and fixing Playwright tests, with advice on locators, waiting and diagnosing CI failures
Thirteen testing skills from requirements to report: strategy, cases, API checks, Playwright and flaky-test triage.
A CLI and MCP for testing agent skills: repeatable YAML evals, report comparison, regression detection and skilled-improve
A CLI to evaluate and evolve agent skills: declarative YAML cases, runs across engines and structured reports
Fifty testing skills for Claude Code, Codex and Cursor: Playwright, strategy, API, visual and load checks.
README in short
The skills come with a technique catalog of eight reference files: linearizability and serializability checks, deterministic simulation, chaos tests, fuzzing, formal methods, property and metamorphic testing, performance measurement, and crash recovery with upgrades. The author distilled it from Andrey Satarin's catalog and research papers on failures in cloud systems.
README badge
Original SKILL.md
--- name: designing-distributed-system-tests description: Use when designing a test plan for a distributed or stateful system — anything with persistence, replication, consensus, retries, idempotency, async messaging, multi-tenancy, or partial failure. Plans are claim-driven: investigate the product's claimed guarantees first, then design hypotheses and scenarios that try to falsify those claims under fault. Handles change-scoped plans (a commit / PR / feature) and project-wide plans (holistic, with existing-test inventory and gap analysis). Also use when asked to write a stability plan, fault matrix, release-validation plan, durability / partition / upgrade / crash-recovery / linearizability / deterministic-simulation plan, tenant isolation / authz / boundary plan, namespace isolation plan, fairness / noisy-neighbor plan, "what should we be testing", or "make a holistic test plan". Trigger even if the user just says "what should we test for this change", "are my tenants actually isolated", or "how do I test fairness across tenants / shards / queues". --- # Designing Distributed-System Tests The default for testing distributed and stateful systems — write a few integration tests and call it done — finds a small fraction of the bugs that actually break these systems in production. This skill enforces an opinionated workflow: scope the change, generate failure-mode hypotheses that cover the categories the literature says matter most, pick techniques from a curated catalog, and emit a structured plan file that the executing-distributed-system-tests skill (or a human) can run. ## Plan modes This skill produces two shapes of plan. Decide which one applies before you start; the steps below branch on it. - **Change-scoped** — the default. Use when the caller names a commit, PR, branch-diff, or feature. The plan covers what *this change* could regress, scoped by its blast radius. - **Project-wide** — use when the caller asks for a "release-validation plan", "stability plan for the whole system", "test plan to enough coverage", "what should we be testing", or otherwise frames the request without a specific change. The plan covers what *the system* should be tested for, with an explicit inventory of existing tests and a gap analysis driving the new-scenario list. If the framing is ambiguous, ask once before starting — the modes diverge enough that retrofitting one into the other wastes work. ## Process Follow these steps in order. Do not skip; the order matters because later steps depend on artifacts the earlier steps produce. ### 1. Scope the system