AGENT SKILL

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

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.

  1. 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 the principles skill's tooling.md, not FAIL.

  2. 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.

  3. 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 apply step 2 decides it: a name-filter-only runner (Maven -Dtest, Gradle --tests) has no audit --exercised and no /testing:cleanup mutation gate, while the diff, --full and --paths scopes still work.

  4. 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 configured test-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.

  5. 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.

  6. 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 userConfig and an invalid one reported as FAIL naming the key, the value and /plugin configure as the fix. Nothing readable → INFO naming the audit's fallback: tool: manual, the diff target from origin/HEAD, the changed source files, the effort cap, and a test command the user supplies or confirms at run time. apply writes 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.

  7. 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. A test-command without {tests} as a standalone word (whitespace or the end of the string on both sides, unquoted) → FAIL: audit --exercised replaces 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. Absent test-command → INFO; only the exercised scope under the manual protocol needs it.

  8. Suppression record. Report presence and entry count of .claude/mutation-testing-arid.md across 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.md
    

    It 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-level suppressions: mapping, an unreadable node-kind table, or no digest tool. An absent record and an empty suppressions: 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, sites with a surface and an anchor/v<N>, reason, date), date is present but is not a real calendar day written YYYY-MM-DD, or claim is not the canonical form. FAIL, naming the entry and the key the lint names. A partial parse is not offered: an entry with sites, reason, and date but no check or claim is 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>. claim binds arid(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.md layer but absent from the team layer is reported personal-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.
  9. 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?) and git check-ignore -v <path> (is it ignored?). Untracked → FAIL, naming the git add that fixes it; ignored → FAIL with the matching pattern. Checking only check-ignore is the trap: immediately after apply writes them the files are untracked but not ignored, so check-ignore is silent and the probe would report success on two files no teammate will ever receive. The .local.md personal 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.

  1. Read the effective config first, across all layers, and summarize it before proposing changes. Nothing is dropped without the user confirming.
  2. 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-command filter forms". A path-list runner or dotnet test supports audit --exercised and /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 --exercised refuses unless the tool's own restriction reads yes in that file, and cleanup's mutation runs always need a path-list test-command, so it can offer only its cannot-fail-only mode. The diff, --full and --paths scopes need no test-command and work for every runner the tool drives.
  3. Settle the diff target. Default to the repository's own default branch as resolved from origin/HEAD, not a hardcoded main or master. Confirm it resolves.
  4. 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.
  5. Settle the timeout from the measured baseline suite time in check, not from a guess.
  6. 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-command for 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 is dotnet test, propose dotnet 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's tool-test-restriction.md.
  7. 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's yaml block 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.
  8. 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.
  9. 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 apply is where it is cheapest to fix. Offer the git add and 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.
  10. Verify after remediation. Re-run the check probes 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 .gitignore if not already covered. State plainly that the same personal override pattern does not give personal suppressions effect: an arid entry in a .local.md is 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:

  • local writes to .claude/mutation-testing.local.md only, 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, run git check-ignore -v .claude/mutation-testing.local.md; when nothing ignores it, offer the .claude/**/*.local.* line in .gitignore and write it only on the user's acceptance.

  • user writes no file and no setting, and of check it runs only probe 6, so it runs no test command. It runs step 1, then settles only the two userConfig keys: operators as step 4 does, and max_mutants unset by default, so the effort cap applies, offering a cap only when the user asks. When the rendered max_mutants above 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 sets operators or max-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, plus max_mutants only when the user chose a cap (never an empty or invented cap). Never uninstall to reconfigure; that section links what an uninstall deletes. A check in a fresh session shows the saved value, since a same-session check can still show the old one; report only an observed value, never an unobserved change. Never write pluginConfigs or any settings file yourself.

    Say that steps 7 to 10 were skipped because nothing in the repository was written, so git status is 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. check runs 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 is userConfig, which Claude Code stores; apply user names /plugin configure for it.
  • Write machine-local state other than the personal override apply local writes 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 principles skill's scaling-and-suppression.md for why gating on the score inverts the incentive.

04 同仓库更多 Skills

melodic-software
melodic-software/claude-code-plugins

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.

★ 30
melodic-software
melodic-software/claude-code-plugins

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.

★ 30
melodic-software
melodic-software/claude-code-plugins

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.

★ 30
melodic-software
melodic-software/claude-code-plugins

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.

★ 30
melodic-software
melodic-software/claude-code-plugins

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.

★ 30
melodic-software
melodic-software/claude-code-plugins

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').

★ 30