setup
Verify and configure the mutation-testing plugin for this repository. check inspects the ecosystem's mutation tool (installed, runnable, supported test runner), the baseline suite's health, and the tracked docs/conventions/mutation-testing.yaml config across its merge layers, read-only; apply detects the ecosystem, installs or names the tool, interviews for the diff target and operator set, and writes the config plus an empty arid-node suppression record. Use when: 'set up mutation testing', 'is mutation testing configured', 'which mutation tool for this repo', 'mutation-testing setup', or the audit skill ran on fallback defaults or reports an unavailable tool. Re-runnable. Safe to invoke again to reconfigure.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 30
- Forks
- 7
01 前言 Front Matter
- description
- Verify and configure the mutation-testing plugin for this repository. check inspects the ecosystem's mutation tool (installed, runnable, supported test runner), the baseline suite's health, and the tracked docs/conventions/mutation-testing.yaml config across its merge layers, read-only; apply detects the ecosystem, installs or names the tool, interviews for the diff target and operator set, and writes the config plus an empty arid-node suppression record. Use when: 'set up mutation testing', 'is mutation testing configured', 'which mutation tool for this repo', 'mutation-testing setup', or the audit skill ran on fallback defaults or reports an unavailable tool. Re-runnable. Safe to invoke again to reconfigure.
- argument-hint
- [check|apply [team|local|user]]
- user-invocable
- true
- disable-model-invocation
- true
02 资源文件 1
- 参考文档templates/config-template.md5.0 KB
03 SKILL.md 正文
Purpose
Establish the four things /mutation-testing:audit cannot infer repeatably at run time: which tool,
which diff target, which operators, and where arid-node suppressions live.
Configuration is optional: with none at any layer, the audit falls back to tool: manual, the diff
target from origin/HEAD, the changed source files and the effort cap, and asks the user for the
test command, which it never guesses. Configure anyway for a repeatable run. A mutation run drives
the project's own test runner against deliberately broken source; a guessed tool or diff target
either does nothing or does something expensive, and the config records the answers once.
Check-centric per the uniform setup contract (docs/plugin-philosophy.md
"Setup is explicit and repeatable" in the marketplace repository): check inspects read-only;
apply interviews and writes, then re-runs check. No argument or check runs the check; apply
runs the check first, then the write flow. apply takes the target layer as its next word: team
(the default), local or user (apply by layer).
The config merge model
The config resolves across three layers, lowest first: the user layer (userConfig) → team
(${CLAUDE_PROJECT_DIR}/docs/conventions/mutation-testing.yaml, a YAML file validated by
${CLAUDE_PLUGIN_ROOT}/schemas/mutation-testing.schema.json) → personal override
(.claude/mutation-testing.local.md), later layers overriding scalars and unioning lists.
The team file of earlier releases, .claude/mutation-testing.md, is retired and never read as a
layer. While it exists, check probe 6 reports it as INFO, which gates nothing, naming apply as the move, or, once
the YAML file exists, deleting it; apply step 7 carries its keys over.
There is no user-global file, and ~/.claude/mutation-testing.md is never read: a per-person
value lives in this plugin's userConfig, which Claude Code prompts for and stores. It carries two keys that mean the same thing in every repository,
operators and max_mutants (the config's max-mutants); their rendered values are:
operators:${user_config.operators}max_mutants:${user_config.max_mutants}
An empty value or a surviving literal ${user_config.…} token is unset. A value outside the key's
range (operators other than default or narrow, max_mutants not a whole number of at least 1)
is reported with its key and value and dropped. The other keys are per repository, test-command
above all, so they are never read from userConfig. Report explicitly when a personal override changes the
team file's effect, and warn when a layer cannot be read, rather than silently presenting the team
file as effective.
The arid-node suppression record is a separate surface, .claude/mutation-testing-arid.md,
shaped by the finding-suppression convention. Keeping it separate from the config keeps the config
reviewable: a config diff is a policy change, a suppression diff is an accepted finding.
Its layering is not the config's, and the difference is the whole point. The config's later
layers override; the suppression record sits in the cascade's policy-floor precedence-inversion
class, so on a conflict for the same finding_id the team layer wins, and a personal-layer
entry for an id the team layer does not carry does not suppress at all. It is reported
personal-only, not applied. A personal layer is a draft surface here. Treating it as "layered the
same way" would let one developer silently hide a finding the team never accepted. The full
contract, including id derivation and the four dispositions, is owned by the audit skill's
${CLAUDE_PLUGIN_ROOT}/skills/audit/context/suppression.md.
check (read-only)
Report a PASS / FAIL / INFO table with one remediation line per FAIL. Modify nothing, and do not
run a mutation analysis. That is /mutation-testing:audit.
-
Ecosystem detected. Identify the stack from manifests that actually exist (
package.json,*.csproj/*.sln,pom.xml/build.gradle,composer.json,pyproject.toml). Report what was found and which mutation tool it implies. No recognized ecosystem → INFO naming the manual path in theprinciplesskill'stooling.md, not FAIL. -
Tool present and runnable. Invoke the tool's own version command. Absent → FAIL with the install line for this ecosystem. Present but erroring → FAIL quoting the error; a tool that installs but cannot start is the common case and is worth distinguishing.
-
Test runner supported. Confirm the project's runner is one the tool drives. Report the detected runner and the tool's support status. Unsupported → FAIL; this blocks every later step, so report it before anything about scores. A supported runner also gets an INFO row naming what it supports, decided as
applystep 2 decides it: a name-filter-only runner (Maven-Dtest, Gradle--tests) has noaudit --exercisedand no/testing:cleanupmutation gate, while the diff,--fulland--pathsscopes still work. -
Baseline suite is green. Run the project's test command once, unmutated, and report the result. Red → FAIL. A red baseline kills every mutant and reports a perfect score, so no mutation result is meaningful until this passes. Record the wall-clock; it is the input to the timeout setting and to whether diff-scoping is sufficient. For
dotnet test, run it once per test project, naming the project, never over a solution or a directory. With no configuredtest-command, ask the user for the command, or propose one and wait for their confirmation, before running anything; an unattended run reports this probe as not run. -
Known flakiness. Ask, and check for a documented flaky-test list or retry configuration. Flakiness present → INFO with the consequence stated plainly: mutants killed by a flaky failure inflate the score by an unknown margin.
-
Config presence (effective, across layers). Report the merged result and which layer contributes what: tool, diff target, operator set, timeout, paths to mutate, with a value from the user layer named
userConfigand an invalid one reported as FAIL naming the key, the value and/plugin configureas the fix. Nothing readable → INFO naming the audit's fallback:tool: manual, the diff target fromorigin/HEAD, the changed source files, the effort cap, and a test command the user supplies or confirms at run time.applywrites a config that replaces it. The retired .claude/mutation-testing.md present → INFO, as the merge model says; it never counts as a layer here. -
Diff target resolves, the configured target must resolve in this repository (
git rev-parse --verify <target>). Unresolvable → FAIL naming it; a stale default here silently scopes a run to nothing or to everything. Atest-commandwithout{tests}as a standalone word (whitespace or the end of the string on both sides, unquoted) → FAIL:audit --exercisedreplaces that word with the test paths, one argument each. Without it every mutant would run against the whole suite; inside quotes ("{tests}") or a larger word (--files={tests}) the paths would merge into one argument or split wrongly. Absenttest-command→ INFO; only the exercised scope under the manual protocol needs it. -
Suppression record. Report presence and entry count of
.claude/mutation-testing-arid.mdacross layers. Absent is a valid state (no suppressions) → INFO. Present → validate every entry against the full contract in${CLAUDE_PLUGIN_ROOT}/skills/audit/context/suppression.md, not a subset of it.Grade the entries with the lint rather than deriving anything by hand, passing every layer that exists:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/suppression-lint.sh" .claude/mutation-testing-arid.mdIt prints
record <path>and then one line per entry, and exits 0 when every entry passes, 1 when any entry fails, and 2 when it cannot grade a record at all: no top-levelsuppressions:mapping, an unreadable node-kind table, or no digest tool. An absent record and an emptysuppressions:mapping are both exit 0. Its three failure verdicts are FAIL conditions here; the two items after them are the probe's own, and the lint decides neither:malformed <id>. A required key is missing (check,claim,siteswith asurfaceand ananchor/v<N>,reason,date),dateis present but is not a real calendar day writtenYYYY-MM-DD, orclaimis not the canonical form. FAIL, naming the entry and the key the lint names. A partial parse is not offered: an entry withsites,reason, anddatebut nocheckorclaimis malformed and must not be reported as usable, because the audit would otherwise suppress a mutant on a location match the contract never authorized.mismatch <id>. The entry's(check, claim, sites)do not hash to the key it is filed under, and the line names the id they do hash to. FAIL. This is the case a hand-edited constituent beside a stale key produces, and it silently stops suppressing if unchecked.unknown-kind <id>.claimbindsarid(kind=<node-kind>)with a kind that is not a member of the enumerated table in${CLAUDE_PLUGIN_ROOT}/skills/principles/reference/scaling-and-suppression.md("The node-kind vocabulary"), which the lint reads at run time. FAIL, reporting the accepted kinds the lint prints beneath the failing entries. Membership is the test, not shape: a single-word kind that is not in the table is indistinguishable from prose that happens to be one word, and passing it would make every suppression self-justifying.- Personal-only entries. Any id present in a
.local.mdlayer but absent from the team layer is reportedpersonal-only, not applied, with promotion to the team layer named as the remedy. This is INFO, not FAIL: the entry is legal, it simply does not suppress. - Report the contributing layer for every entry. A malformed layer degrades soft. Report it and continue, never fail the whole read.
-
Tracked, not ignored. Both the config and the suppression record must be committed to be team-shared, and not ignored is only half of that. Run both probes per file:
git ls-files --error-unmatch <path>(is it tracked?) andgit check-ignore -v <path>(is it ignored?). Untracked → FAIL, naming thegit addthat fixes it; ignored → FAIL with the matching pattern. Checking onlycheck-ignoreis the trap: immediately afterapplywrites them the files are untracked but not ignored, socheck-ignoreis silent and the probe would report success on two files no teammate will ever receive. The.local.mdpersonal overrides are expected to be both untracked and ignored. INFO, not FAIL. A file that does not exist is not probed: probe 6 already reports the missing config as INFO, and probe 8 the missing record.
apply (idempotent)
Run check, then interview and write. Proceed non-interactively where the repository makes a value
unambiguous; ask only where the answer is genuinely the user's.
- Read the effective config first, across all layers, and summarize it before proposing changes. Nothing is dropped without the user confirming.
- Detect and propose the tool. From the ecosystem, name the tool and the exact install command,
and ask before installing anything. Installing a dependency into the consumer's project is the
user's decision, not this skill's. Propose, never install unprompted. In the same message, before
any later question, name the detected test runner and what it supports, so the user can stop
here; read its kind from the audit skill's
tool-test-restriction.md"test-commandfilter forms". A path-list runner ordotnet testsupportsaudit --exercisedand/testing:cleanup's mutation gate, which runs through it. A name-filter-only runner (Maven-Dtest, Gradle--tests), or one that table does not list, supports neither:audit --exercisedrefuses unless the tool's own restriction readsyesin that file, and cleanup's mutation runs always need a path-listtest-command, so it can offer only its cannot-fail-only mode. The diff,--fulland--pathsscopes need notest-commandand work for every runner the tool drives. - Settle the diff target. Default to the repository's own default branch as resolved from
origin/HEAD, not a hardcodedmainormaster. Confirm it resolves. - Settle the operator set. Default to the tool's defaults, and say why: optional and experimental operators raise the mutant count and the unproductive rate together. Offer the narrowed set only if the user asks for a cheaper run.
- Settle the timeout from the measured baseline suite time in
check, not from a guess. - Settle the mutate paths and the test command. Propose source roots, excluding generated
code, vendored directories, and test code itself. Mutating tests measures nothing. Then propose
test-commandfor the detected ecosystem when its runner takes test file paths, with{tests}where the paths go:python -m pytest {tests},python -m unittest {tests},npx vitest run {tests},npx jest --runTestsByPath {tests},vendor/bin/phpunit {tests}. The audit fills{tests}with each path quoted as its own argument. When the detected runner isdotnet test, proposedotnet test {tests}: the audit runs it once per test project, with{tests}replaced by that project and a name filter for the test files' classes. Propose nothing for a runner that only filters by name (Maven-Dtest, Gradle--tests); step 2 already said what that costs. The forms and their sources are in the audit skill'stool-test-restriction.md. - Write the config to
docs/conventions/mutation-testing.yaml, the template's YAML block without its Markdown, following${CLAUDE_PLUGIN_ROOT}/skills/setup/templates/config-template.md. Keep every key name as the template spells it. When that file does not exist yet and the retired .claude/mutation-testing.md does, this first write carries every key of the retired file'syamlblock with its value unchanged, a value settled in steps 2 to 6 replacing it; with nothing to settle, the write is that move alone. Leave the retired file in place and tell the user to delete it once the YAML file is committed, since the plugin does not read it. - Create the suppression record empty, with its header comment and an empty
suppressions:mapping, a mapping, never a list, since a list is taken whole and one personal entry would discard the team's entire accepted set. An empty record makes the first suppression an edit to a reviewed file rather than the creation of a new one. - Get both files tracked and committed, and say so. They are team-shared surfaces; leaving them
untracked is the failure probe 9 exists to catch, and
applyis where it is cheapest to fix. Offer thegit addand the commit that follows it, and run each only on the user's explicit acceptance; never commit unasked. Do not stop at staging as a matter of course: staged and unstaged both leave a dirty working tree, and a session-end gate that refuses a dirty tree holds the session open until these two files are committed and pushed. Say so when the user declines, so the tree they are left with is a choice rather than a surprise. - Verify after remediation. Re-run the
checkprobes on what was written, including both halves of probe 9, tracked and not-ignored, then offer the personal override convention: personal config overrides in.claude/mutation-testing.local.md, and recommend the recursive.claude/**/*.local.*line in.gitignoreif not already covered. State plainly that the same personal override pattern does not give personal suppressions effect: an arid entry in a.local.mdis a draft until promoted to the team layer.
Re-running apply after everything passes changes nothing and reports "already configured".
apply by layer
Steps 1 to 10 are the team flow. The other two layers change what is written:
-
localwrites to.claude/mutation-testing.local.mdonly, and only the keys the user wants to override, without the template's team-shared header. It skips step 8, since a personal suppression entry would not suppress, and step 9, since the personal override is meant to stay untracked. Before writing, rungit check-ignore -v .claude/mutation-testing.local.md; when nothing ignores it, offer the.claude/**/*.local.*line in.gitignoreand write it only on the user's acceptance. -
userwrites no file and no setting, and ofcheckit runs only probe 6, so it runs no test command. It runs step 1, then settles only the twouserConfigkeys:operatorsas step 4 does, andmax_mutantsunset by default, so the effort cap applies, offering a cap only when the user asks. When the renderedmax_mutantsabove is already a valid saved cap and the user wants the effort cap, do not say the effort cap now applies: say the saved cap stays in force, since leaving the key out keeps it, and that clearing it is done in/plugin configure mutation-testing@<marketplace>. When this repository's team or local file already setsoperatorsormax-mutants, say that file overrides the user value here. Then name how to save them through Claude Code's native flow: interactively with/plugin configure mutation-testing@<marketplace>, or by a headless route as the marketplace's plugin-reconfiguration convention gives them in § The routes (it owns the verified-version record, and what a key left out does), with the scope and failure-signal caveats in its § Caveats every setup skill's short form carries. Read both sections and print what they give, the fallback route, its behavior on an already-installed plugin and the scope to pass included, rather than only naming them, and leave out the verified-version record. Save only the keys the user settled:operators, plusmax_mutantsonly when the user chose a cap (never an empty or invented cap). Never uninstall to reconfigure; that section links what an uninstall deletes. Acheckin a fresh session shows the saved value, since a same-sessioncheckcan still show the old one; report only an observed value, never an unobserved change. Never writepluginConfigsor any settings file yourself.- Pointer: for the headless command's flags, how it reports a saved or refused value, and when a saved value applies, fetch plugin CLI reference § plugin configure live.
Say that steps 7 to 10 were skipped because nothing in the repository was written, so
git statusis unchanged, and that a repository's tool, diff target, mutate paths and test command still come from its team or local file or the audit's fallback.
Output
For the team layer, a tracked docs/conventions/mutation-testing.yaml and
.claude/mutation-testing-arid.md in the consuming repo; for local, the untracked personal override; for user, no file and the
/plugin configure line. Each ends with a one-paragraph summary of what was written and how to
re-run this setup to reconfigure; team and local also give the measured baseline suite time.
What this skill does NOT do
- Run a mutation analysis. That is
/mutation-testing:audit.checkruns the unmutated suite once to establish the baseline, and nothing more. - Install anything without asking.
- Write the plugin cache, Claude Code user settings, or
pluginConfigs. The user layer isuserConfig, which Claude Code stores;apply usernames/plugin configurefor it. - Write machine-local state other than the personal override
apply localwrites on request. Configuration lives in the consumer's repository files, never in the plugin directory or the plugin data directory. - Set a score threshold. The config template deliberately has no such field; see the
principlesskill'sscaling-and-suppression.mdfor why gating on the score inverts the incentive.
04 同仓库更多 Skills
track
Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.
reviewer-media
Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from /review:explain-change's digest, has /explainer-video:produce render it and hands the manifest to /source-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
principles
Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is /architecture:improve.
write
Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').