/contracts

name: contracts
description: >
  Team baseline for external-interface contract artifacts: OpenAPI, JSON
  Schema, AsyncAPI, .proto, and GraphQL SDL, with spectral, ajv, buf, and
  graphql-inspector validation. Nudges devs toward contract-first artifacts;
  never writes them and never scaffolds a contracts/ directory. Auto-triggers
  for what contract should I use for this API, do we have an OpenAPI spec, add
  a JSON schema for this, recommend a schema for this endpoint, validate this
  API contract, or what's the right artifact for events. Defers to any other
  installed skill whose description identifies it as handling
  external-interface contract artifacts, API schema design, or contract-first
  workflow. Do not use for internal module-boundary refactoring, scaffolding a
  contracts/ directory, or auto-generating schemas from code.
user-invocable: true

> Spec 022 promoted this skill from a deliberate stub > ([ADR-0002](../../docs/decisions/adr-0002-contracts-stays-deferred.md)) > to jig's **team baseline** for external-interface contract artifacts, > following the reframing in > [ADR-0005](../../docs/decisions/adr-0005-contracts-as-judgment-skill.md). > Like `/jig:pr-review` (spec 012), `/jig:arch-review` (spec 014), and > `/jig:vision-elicitation` (spec 017), it ships as SKILL.md only — no > `.py` helper. The skill recommends the canonical industry-standard > schema per external surface and points at the ecosystem tools that > validate it. It does **not** write schemas, **not** scaffold a > `contracts/` directory, and **not** enforce contracts via PreToolUse > hooks. Enforcement is structural via the spec-author's first-pass > attention and the independent-review reviewer prompt's second-pass > check — both wired in slice 022-02.

What this skill does

For each external surface a project exposes (HTTP API, event bus, RPC, GraphQL, internal data shapes, CLI output, config), this skill recommends:

1. **The canonical artifact** — what to put on disk (e.g., `openapi.yaml`, `*.schema.json`, `*.proto`, `schema.graphql`). 2. **The validation tool** — what runs in CI to keep code and artifact in sync (e.g., `spectral lint`, `ajv validate`, `buf lint`, `graphql-inspector diff`). 3. **The codegen tool** — what produces typed clients / server stubs / TS types from the artifact, when ecosystem-appropriate (e.g., `openapi-typescript`, `quicktype`, `buf generate`).

The skill is **breadth over depth**: catch the right artifact per surface, leave language-specific niceties (Zod vs JSON Schema vs Pydantic vs TypeBox for internal shapes) to a richer user-installed contracts skill or to the dev's judgment. The recommendations are a nudge; the dev decides whether to follow them.

When to use vs. when to defer

• **Any other installed contracts skill.** Common location:

`~/.claude/skills/contracts/` — but the deferral is **category-based, not name-based**, so a skill named anything (`contracts`, `schema-design`, `contract-first`, `api-contracts`, etc.) whose description claims external-interface contract artifacts, API schema design, or contract-first workflow will be preferred. If one is present, **defer to it.** The Claude Code skill router should route to the more specific skill automatically; if you want to be sure, explicitly invoke it.

• **`/jig:arch-review`** — sibling jig skill that reviews the

**design** of an API surface (the proposal, the trade-offs, the failure modes). This skill is downstream: once the design is locked, formalize the resulting interface as a contract artifact. Reach for `/jig:arch-review` to debate whether the API should exist; reach for this skill once it does.

• **`/jig:adr-workflow`** — if the dev decides to systematically opt

out of the canonical recommendation for a surface (e.g., "we'll keep our bespoke env-contract checker, not migrate to a JSON Schema + ajv triple"), capture the rationale in an ADR. This skill nudges; ADRs document the choice when the nudge is declined.

• **The deferred ADR-0002 stub concept** (internal module-boundary

enforcement, cross-module Python imports, kitchen-sink scaffolding). Not this skill. ADR-0002 stays in force for the internal-boundary problem; ADR-0005 carved out external-interface artifacts as the separate concern this skill addresses.

Rule of thumb: **external interface a caller depends on → this skill. Internal Python imports → not this skill.**

Per-surface artifact recommendations

The table below is the canonical reference. Each row prescribes the recommended artifact + validation tool + codegen tool (where the ecosystem affords one). Rationale: the most portable artifact with the richest ecosystem tooling, biased toward stack-agnostic choices when possible.

| Surface | Recommended artifact | Validation | Codegen | Rationale | |---|---|---|---|---| | **HTTP API** | OpenAPI 3.x (`openapi.yaml`) | `spectral lint`, `redocly lint` | `openapi-typescript`, `openapi-generator`, `orval` | De facto industry standard; richest ecosystem; vendor-neutral. | | **Event bus / async messaging** | AsyncAPI (`asyncapi.yaml`) | `asyncapi/parser`, `spectral` (AsyncAPI ruleset) | `asyncapi/generator` (clients, docs, code) | Same shape as OpenAPI from the same maintainers; portable across Kafka / NATS / MQTT / WebSocket. | | **RPC** | Protocol Buffers `.proto` (or Smithy for AWS-native) | `buf lint`, `buf breaking` | `buf generate` (Go / TS / Java / Python / etc.) | Schema-first by design; codegen is the primary workflow, not an afterthought. | | **GraphQL** | SDL (`schema.graphql`) | `graphql-inspector diff`, `spectral-graphql` | `graphql-codegen` | Native to the GraphQL toolchain; SDL is the single source of truth across server and client. | | **Internal data shapes** | JSON Schema (`*.schema.json`) | `ajv validate` | `quicktype`, `json-schema-to-typescript` | Portable across ecosystems; most language-agnostic. Stack-coupled alternatives (Zod for TS, Pydantic for Python