Use event-contract-draft

Draft the contract for an event or message interface (Kafka topics, SNS/SQS, EventBridge, Pub/Sub, RabbitMQ, webhooks) as an AsyncAPI 3.0 document plus a short decisions…

Draft the contract for an event or message interface (Kafka topics, SNS/SQS, EventBridge, Pub/Sub, RabbitMQ, webhooks) as an AsyncAPI 3.0 document plus a short decisions page — past-tense event names, a required envelope with event id for deduplication, the partition key and the ordering it does and doesn't give, at-least-once delivery and how consumers stay idempotent, data minimisation with PII marked, additive-only versioning with dated deprecation, and retention, replay and dead-letter handling.

Reach for it when the user wants to define events, design a Kafka topic or message schema, write an AsyncAPI spec, agree what a producer publishes and what consumers must do, or version an event safely.

Install it

npx skilldrop-cli install event-contract-draft                 # Claude Code, your user folder
npx skilldrop-cli install event-contract-draft --project       # Claude Code, this repo
npx skilldrop-cli install event-contract-draft --ide cursor    # or kiro, codex, antigravity, copilot

It is part of the Solution architect pack: --pack solution-architect installs it with its neighbours.

It ships scripts, so it needs Python 3 (standard library only, nothing to install). What they may touch is declared in its manifest.

Ask for it

Say it the way you would to a colleague. Requests like these route to it:

"Write the AsyncAPI spec for the order events our service publishes to Kafka"
"Define the message schema, envelope and partition key for our payment events topic"
"We need to rename a field on a live SNS/SQS event without breaking the consumers. How do we version it?"
"Draft the EventBridge event contract for InvoicePaid, including what consumers have to do about duplicates"
"If we key our Kafka topic by customerId, is ordering guaranteed for each order?"

Requests like these belong to a different skill, so it shouldn't answer them:

"Draft the OpenAPI spec for the orders REST API: create, fetch and list orders"
"Write a data contract for the orders table the analysts query in the warehouse, with freshness and completeness SLAs"
"Define the data contract for the clickstream topic that feeds the lakehouse, with null-rate and volume checks"

If another skill answers instead, ask for this one by name: "use event-contract-draft".

Check what you get

A good result:

Every event name is a past-tense fact in the producer's domain, one type per schema.
Every message has the full envelope, required, with a stable event id for deduplication.
Every channel names its key, the order it gives and the order it doesn't. No global order.
Each consumer's idempotency is stated: dedupe on id, revision check, or a natural key.
Every field has a consumer; personal data that stays is marked; nothing "just in case".
Breaking changes go through a new field or version with a deprecation date that came from the input or is listed as open.
Retention, replay and dead-letter are stated per channel, with the DLQ owner named or open.
The check result is reported only if it ran, and the document has no FAIL.
Nothing invented: no team names, dates, volumes or retention the input didn't give, except as [assumption].
Every question asked is answered in its own line first, before the contract.
The user's draft stays theirs: each change to their names, fields or shapes is listed with the rule it fixes, and nothing else is changed.
The document is whole: saved complete, or shown complete, never cut off.

See a worked example

order service

Use something else when

A request/response HTTP API — api-contract-draft
A table, dataset or analytics stream's schema, freshness and quality SLAs — data-contract
Deciding whether the system should be event-driven at all, or its components — design-doc

SKILL.md, the instructions the agent reads
Its page on the site
Related: api-contract-draft, data-contract, design-doc

Edit this page on GitHub · View source