How to use the Test Suite Audit agent skill (test-audit)

What is an agent skill, and what does test-audit make the agent do?

An agent skill is a folder of instructions that an AI agent loads when a task matches the skill's description. The skill's main file, SKILL.md, tells the agent how to approach the task, and supporting files hold detailed guides.

With test-audit installed, the agent reviews a project's automated test suite for tests that are duplicated, meaningless, or tightly tied to implementation details. Before deleting anything, it must justify each removal by showing that another retained test still catches the same regression. It can also choose to keep tests that remain useful.

The skill follows a structured workflow for two kinds of work: focused cleanups of one area, or larger coordinated audit campaigns across several owners, agents or pull requests. At the end it reports what was removed, what was kept, and why.

• Inspect: pin the base revision and read candidates, fixtures, production callers, history and CI routing.
• Plan: mark each item as retain, repair, consolidate, delete or defer.
• Prove: establish a baseline before treating failures as cleanup candidates.
• Edit: move unique assertions first, then retire duplicates and unused support.
• Validate and review: run keepers and affected sibling tests, then reconcile deleted contracts with retained proof.

How do you install the test-audit skill?

Download the test-audit ZIP from this page and unzip it. The skill folder contains SKILL.md and the supporting files listed below. Put the folder in one of these locations, depending on how you want to use it:

For all of your projects, place it in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder so it applies only to that repository.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal skill: ~/.claude/skills/test-audit/
• Project skill: .claude/skills/test-audit/ inside the repository

How do you trigger the skill with a natural request?

You do not need a special command. Ask the agent in plain language about test audits, test pruning, duplicate coverage, or reducing CI test cost. The skill's description lists these topics, so requests that use them are the most likely to load it.

State the scope in your request. A focused request names one area of the suite. A campaign request names several owners or a whole subsystem and should say whether you want a targeted sweep or an exhaustive audit, because the skill asks you to declare which one it is doing.

• Audit the tests in the billing module for duplicate coverage and tell me what you would remove.
• Run a test pruning pass on the API integration tests to reduce CI time, keep anything that guards a distinct failure mode.
• Start a coordinated test audit campaign across the scheduler, storage and browser suites; report baseline results for each owner.
• Find redundant tests in this repo, but do not delete anything until you have shown which retained test catches each regression.

What should you expect from an audit?

The skill applies a decision gate to every proposed removal. The agent must name the contract and plausible regression that the assertions cover, identify a retained test that detects the same regression through the responsible production code, check whether the candidate uniquely covers an independent failure mode such as permissions, storage or platform behaviour, and state what improves.

The skill is deliberately conservative. Similarity, size, slowness, or suspected AI authorship alone never justify deletion. Keeping an area after review is a valid outcome, and the agent is told not to create repository documentation unless you explicitly ask for it.

• Removals and keepers, with the reason for each.
• Retained or deferred candidates.
• Checks run, limitations, and distinct cases versus repeated executions.
• Test and support code versus production lines of code changed.
• The actual endpoint: findings only, a validated local patch, a published PR, an intermediate merge, or landed in the target branch.

What do you need before running it?

The skill assumes a working environment. Without it, the workflow cannot run or validate tests before any removal, so it will not produce useful deletions.

• A local copy of the target repository, with its test runner and dependencies installed.
• Git access, so the agent can pin a base revision and review history.
• Optional: CI access, so results can be compared against runs on the matching revision.
• For Paperclip repository contributors: the skill's references/paperclip.md file covers Paperclip-specific commands and conventions, which should be read alongside the repository's own instructions.

What are the safety notes?

According to the skill's listing, test-audit runs no scripts and makes no network requests. Its effects come from the agent reading your repository and editing test files, so review the diff before anything is committed or merged.

The skill says that deletion needs evidence, and that production-seam deletion needs its own caller and contract evidence. Publishing or merging is limited to what your task authorises. Preserve unrelated work in the tree, as the skill instructs.

• No scripts are run by the skill.
• No network use is declared.
• Review each proposed removal before accepting it.
• Keep audit notes in the task or pull request description rather than in new repository files.

Tips for getting useful results

Start with a focused cleanup on one slow area. You will learn how the agent reasons about your suite before you commit to a larger campaign. Give it time, since the skill needs room to investigate and run baselines.

If you suspect duplicate coverage, say so and ask the agent to show the retained test for each suspected duplicate. Campaign work is easier to review when every batch is a separate pull request.

• Give the agent a clear time budget and target branch.
• Ask for baseline results before any edits.
• Ask for a report that separates measured, estimated and historical cost evidence.