How to use the Test Collaboration Governance agent skill

What the skill makes the agent do

Once installed, the agent inventories the tests that already exist in your project and records what they cover. It links requirements, business rules, risks and bugs to stable TEST-IDs such as TEST-ORDER-001, and records whether each one has sufficient evidence in the repository's test registry, usually TESTS.md.

• Inventories existing tests by module, suite or critical workflow rather than listing every test function.
• Assigns TEST-IDs and tracks a state for each item: missing, in progress, unverified, covered or not applicable.
• Flags coverage gaps, possibly duplicate or stale tests, and bugs fixed without regression protection.
• For shared APIs, ties one TEST-ID to contract, consumer, provider and integration evidence.
• Classifies tests as unit, integration, contract, E2E or smoke.

Install the skill (ZIP download or Claude apps upload)

Download the test-collaboration ZIP from this page and unzip it. Choose one of two locations depending on how you want to use it. For a single user across all projects, unzip it into ~/.claude/skills/. For one project that the whole team shares, unzip it into the project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your repository
• Claude apps: Settings → Capabilities → Skills

Know what the skill package contains

The package has three files: SKILL.md, which holds the instructions the agent follows; agents/openai.yaml; and templates/TESTS.example.md, a starter registry template. The skill does not add a dedicated tool, slash command or generator. The current session carries out the work by reading your files and following SKILL.md.

• SKILL.md: the instructions and workflow.
• agents/openai.yaml: agent configuration included in the package.
• templates/TESTS.example.md: the template for a TESTS.md registry.

Prepare your project before you ask

The skill works best when the project already has a test runner or test registry. It reads the registry if one exists, either TESTS.md or the tests role in .governance/docs-map.json. If none exists, the skill creates a default TESTS.md only then. The agent also needs access to your test files, CI configuration and contract files such as OpenAPI or JSON Schema.

Keep the template at hand. Its first section lists test entry points such as the default tests, contract validation and specialized E2E runs, with a column for external dependencies.

• An existing test runner or test registry (TESTS.md or the tests role in .governance/docs-map.json).
• Access to test files, CI configuration and contract files such as OpenAPI or JSON Schema.
• Your existing naming and layout: the skill is written to preserve them.

Trigger the skill with natural requests

You do not need a special command. Describe the task in plain language and the agent should match it to the skill's description. The skill is designed for these tasks: test inventory, test gap analysis, classifying tests by level, bug-to-test regression protection, consumer and provider contract testing, test-necessity review and pre-delivery evidence review.

Be specific about the module, feature or bug. The skill rescans by event, so a request about one area will normally touch only that area.

• "Inventory our tests and create or update TESTS.md."
• "Which requirements in the payments module have no test evidence?"
• "Check that the bug we fixed in the checkout flow has a regression test."
• "Review test evidence before we merge this release branch."
• "Are the OpenAPI client types in sync with the provider tests?"

Read the output and decide what to act on

The skill reports candidates and gaps; it does not delete, rewrite or quarantine tests on its own. A test marked as possibly duplicate or stale needs a human decision. Treat a test count, the existence of a file, or a green CI run as insufficient proof of behaviour, as the skill itself warns.

If you ask for a change that would weaken or remove a test to get a green build, the skill expects the risk and an explicit manual exit to be recorded.

• Gaps and duplicates are suggestions for review.
• A bug is not fully closed until it has a TEST-ID or a recorded manual verification path.
• Generated types or mocks that do not match the contract cannot be marked covered.

Keep the registry and the code in step

The registry stores indexes, assessments and evidence, not copies of test code or of the business success criteria. Success criteria stay in your spec or issue, and the registry links to them. When a contract changes, the skill expects you to change the single contract source first, then regenerate consumer assets and rerun provider and integration tests.

• Change the contract source first, then regenerate and rerun tests.
• Record the actual command, exit code and evidence location for each contract layer.
• Mark a boundary as missing or unverifiable if no machine-checkable contract exists.