System Interface Contracts

Concept of the skill

Designing and reviewing cross-boundary interface contracts across modules, services, jobs, APIs, event producers/consumers, webhooks, data engineering surfaces, and AI agents/tools.

Concept of the Skill

What it is: System interface contract design is the discipline of making the stable promise at a boundary explicit before independently changing parties depend on it. The boundary may be a module, package, service, background job, queue, API, webhook, database read/write surface, AI tool, agent, or team handoff.

Mental model: A contract has parties, ownership, direction, semantics, data shape, lifecycle, failure behavior, compatibility rules, operational promises, trust boundaries, observability, and tests. A schema describes shape; a contract describes what both sides may safely rely on.

Why it exists: Integrations fail when each side has a private interpretation of "what the other side does." A written contract lets teams deploy independently, lets agents/tools call systems safely, and makes drift visible before it becomes a production incident.

What it is NOT: It is not detailed REST resource design, event envelope/topic design, stored-data modeling, post-failure debugging, or ADR writing after the contract is chosen. It owns the cross-boundary promise and routes detailed protocol work to the relevant neighbor skill.

One-line analogy: A system contract is a load-bearing join: the parts can move independently only because the join's shape, tolerances, and failure modes are known.

Common misconception: A JSON Schema, TypeScript type, OpenAPI file, or tool definition is not automatically the whole contract. Those artifacts are useful syntax and tooling surfaces, but the real contract also includes semantics, permissions, compatibility, deployment order, and what happens when something fails.