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
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.
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.
1---2name: event-contract-design3description: 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`).4license: MIT5---67# Event Contract Design
89## Coverage
1011Design 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.
1213## Philosophy
1415An 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.
1617Do 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.
1819## Method
20211. Name the producer, owner, intended consumers, and event purpose.
222. Separate business event type from transport topic or queue name.
233. Define envelope fields: id, type, source, time, subject, schema version, correlation, causation, tenant, and idempotency key.
244. Define payload schema with required, optional, nullable, and deprecated fields.
255. State ordering, delivery, retry, replay, and dead-letter expectations.
266. Define compatibility rules: additive fields, breaking changes, versioning, deprecation, and consumer migration.
277. Add observability fields needed to reconstruct publishing and consumption failures.
288. Provide at least one positive and one negative contract fixture.
2930## Evals
3132This skill ships a comprehension-eval artifact at [`examples/evals/event-contract-design.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/event-contract-design.json). The checklist below is the authoring gate for async event contracts; the eval file is the grader surface.
3334## Verification
3536- [ ] Producer, owner, and consumers are named
37- [ ] Event type, topic/channel, envelope, and payload are distinct
38- [ ] Required, optional, nullable, and deprecated fields are explicit
39- [ ] Idempotency, ordering, retry, replay, and dead-letter behavior are stated
40- [ ] Compatibility rules distinguish additive from breaking changes
41- [ ] Correlation and causation IDs cross async boundaries
42- [ ] Positive and negative fixtures exist for contract testing
4344## Do NOT Use When
4546| Use instead | When |
47|---|---|
48| `event-storming` | You are still discovering domain events, commands, policies, aggregates, or timelines. |
49| `system-interface-contracts` | The boundary is not specifically asynchronous events or messages. |
50| `webhook-integration` | You are implementing inbound provider webhooks, signatures, retries, and raw payload handling. |
51| `api-design` | You are designing HTTP endpoints, status codes, pagination, filtering, or error envelopes. |
52| `observability-modeling` | The event contract is settled and the task is telemetry design. |
Run npx skillmds@latest add aibot88/event-contract-design 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.
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`). It is listed under Product & Planning on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
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.
Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.
aibot88 (@aibot88) published this skill. Their other Agent Skills are listed on their SkillMD profile.
aibot88