Event contract design

Skill jacob-balslev/skills/skills/software-architecture/event-contract-design

Public Agent Skills library exported from skill-graph. Install: npx skills add jacob-balslev/skills

Install

npx -y skills add jacob-balslev/skills --skill event-contract-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when designing or reviewing asynchronous event contracts: producer/consumer ownership, event envelope, schema, topic/channel naming, ordering, idempotency, versioning, compatibility, replay, dead-letter behavior, and AsyncAPI/CloudEvents-style documentation. Do NOT use for domain-event discovery (use `event-storming`), broad interface contracts (use `system-interface-contracts`), inbound provider webhook mechanics (use `webhook-integration`), or HTTP endpoint design (use `api-design`).

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

11.2 KB, as published. Nobody here has run it

Event Contract Design

Concept of the skill

Coverage

Design asynchronous event contracts for producers and consumers. Covers event envelope, schema, event type, topic/channel naming, producer ownership, consumer expectations, required and optional fields, idempotency keys, ordering, causation and correlation IDs, schema evolution, replay, dead-letter behavior, compatibility, observability, and machine-readable documentation such as AsyncAPI or CloudEvents-style metadata.

Philosophy of the skill

An event is a public promise once another consumer depends on it. If the payload, ordering, retry, or compatibility rules are implicit, every consumer invents its own interpretation and the event stream becomes shared folklore.

Do not confuse event discovery with event contracts. Discovery asks what happened in the domain. Contract design asks what exactly will be published, consumed, replayed, and evolved.

Method

Name the producer, owner, intended consumers, and event purpose.
Separate business event type from transport topic or queue name.
Define envelope fields: id, type, source, time, subject, schema version, correlation, causation, tenant, and idempotency key.
Define payload schema with required, optional, nullable, and deprecated fields.
State ordering, delivery, retry, replay, and dead-letter expectations.
Define compatibility rules: additive fields, breaking changes, versioning, deprecation, and consumer migration.
Add observability fields needed to reconstruct publishing and consumption failures.
Provide at least one positive and one negative contract fixture.

Evals

This skill ships a comprehension-eval artifact at examples/evals/event-contract-design.json. The checklist below is the authoring gate for async event contracts; the eval file is the grader surface.

Verification

Producer, owner, and consumers are named
Event type, topic/channel, envelope, and payload are distinct
Required, optional, nullable, and deprecated fields are explicit
Idempotency, ordering, retry, replay, and dead-letter behavior are stated
Compatibility rules distinguish additive from breaking changes
Correlation and causation IDs cross async boundaries
Positive and negative fixtures exist for contract testing

Do NOT Use When

Use instead	When
`event-storming`	You are still discovering domain events, commands, policies, aggregates, or timelines.
`system-interface-contracts`	The boundary is not specifically asynchronous events or messages.
`webhook-integration`	You are implementing inbound provider webhooks, signatures, retries, and raw payload handling.
`api-design`	You are designing HTTP endpoints, status codes, pagination, filtering, or error envelopes.
`observability-modeling`	The event contract is settled and the task is telemetry design.