How do I install the Contract Test skill?

Run npx skillmds@latest add zavelinski/contract-test in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Contract Test safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Contract Test?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Contract Test free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Contract Test?

zavelinski (@zavelinski) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Contract Test by zavelinski — Agent Skill

Name: Contract Test
Author: zavelinski

Contract Test

When two components/services talk (API client+server, producer+consumer, module boundary), pin the contract they share and test BOTH sides against it, instead of only unit-testing each in isolation. Use on integration boundaries, API changes, microservices, public interfaces. Trigger with /contract-test or "contract test", "will this break the consumer", "test the API boundary".

zavelinski a528324 3.1 KB Updated Sep 17, 2026

File contents

contract-test

Unit tests pass on both sides and integration still breaks, because nothing tested the SHARED contract. This pins the interface two parties rely on and tests both against it.

Why this exists (evidence)

Consumer-driven contract testing (the Pact pattern) is the established fix for integration breakage in distributed/microservice systems: catch a breaking interface change at the boundary, before deploy, without a full end-to-end environment.
The failure it targets: provider changes a field/type/status code; provider's own unit tests stay green; the consumer breaks in production. A contract test fails the moment the provider violates what the consumer expects.

When to use

Any client+server / producer+consumer / module boundary, especially across repos or teams (compose with multi-repo-context).
Before changing a public API, schema, event shape, or shared type.
NOT for purely internal logic with no cross-boundary consumer (unit tests / testsmith cover that).

The method

Name the contract: the exact shape both sides depend on, request + response fields and types, status/error codes, event schema, required vs optional, ordering/idempotency assumptions.
Consumer expectations: write what the consumer actually needs (not the provider's full surface). This is the contract.
Test the provider against it: assert the provider produces responses that satisfy the contract (every required field, correct types, documented error codes).
Test the consumer against it: assert the consumer works against a stub/mock that returns exactly the contract (no reliance on undocumented behavior).
Run on both, on change: a provider change that breaks the contract fails here; a consumer that needs more must update the contract first.

How to run it

If a contract tool exists (Pact, schema/OpenAPI validation, JSON Schema), use it: validate responses against the schema both sides agree on.
Lightweight: encode the contract as a shared fixture/schema; provider test asserts output matches it, consumer test runs against it as a stub.
Compose with structured-output (the contract IS a schema) and testsmith (mutation-test the boundary handling).

Composes with

structured-output: the contract expressed as an enforceable schema.
multi-repo-context: contracts are where cross-repo boundaries live; the manifest names them.
testsmith: unit/mutation within a side; contract-test across the boundary.

Honest limits

A contract test verifies conformance to the AGREED contract, not that the contract is the right design. Wrong contract, wrong test.
It does not replace some end-to-end checks (timing, auth, infra); it removes the large class of shape/type/status breakages.

---name: contract-testdescription: When two components/services talk (API client+server, producer+consumer, module boundary), pin the contract they share and test BOTH sides against it, instead of only unit-testing each in isolation. Use on integration boundaries, API changes, microservices, public interfaces. Trigger with /contract-test or "contract test", "will this break the consumer", "test the API boundary".---# contract-testUnit tests pass on both sides and integration still breaks, because nothing tested the SHARED contract. This pins the interface two parties rely on and tests both against it.## Why this exists (evidence)- Consumer-driven contract testing (the Pact pattern) is the established fix for integration breakage in distributed/microservice systems: catch a breaking interface change at the boundary, before deploy, without a full end-to-end environment.- The failure it targets: provider changes a field/type/status code; provider's own unit tests stay green; the consumer breaks in production. A contract test fails the moment the provider violates what the consumer expects.## When to use- Any client+server / producer+consumer / module boundary, especially across repos or teams (compose with multi-repo-context).- Before changing a public API, schema, event shape, or shared type.- NOT for purely internal logic with no cross-boundary consumer (unit tests / testsmith cover that).## The method1. **Name the contract:** the exact shape both sides depend on, request + response fields and types, status/error codes, event schema, required vs optional, ordering/idempotency assumptions.2. **Consumer expectations:** write what the consumer actually needs (not the provider's full surface). This is the contract.3. **Test the provider against it:** assert the provider produces responses that satisfy the contract (every required field, correct types, documented error codes).4. **Test the consumer against it:** assert the consumer works against a stub/mock that returns exactly the contract (no reliance on undocumented behavior).5. **Run on both, on change:** a provider change that breaks the contract fails here; a consumer that needs more must update the contract first.## How to run it- If a contract tool exists (Pact, schema/OpenAPI validation, JSON Schema), use it: validate responses against the schema both sides agree on.- Lightweight: encode the contract as a shared fixture/schema; provider test asserts output matches it, consumer test runs against it as a stub.- Compose with structured-output (the contract IS a schema) and testsmith (mutation-test the boundary handling).## Composes with- `structured-output`: the contract expressed as an enforceable schema.- `multi-repo-context`: contracts are where cross-repo boundaries live; the manifest names them.- `testsmith`: unit/mutation within a side; contract-test across the boundary.## Honest limits- A contract test verifies conformance to the AGREED contract, not that the contract is the right design. Wrong contract, wrong test.- It does not replace some end-to-end checks (timing, auth, infra); it removes the large class of shape/type/status breakages.

Frequently asked questions