CloudEvents

CloudEvents is a specification for describing event data in a common way, published by the CloudEvents project, a CNCF graduated project. Version 1.0.2 defines the context attributes every event carries, event formats that serialize them, and protocol bindings that map them onto transports. With this skill the agent produces and consumes conformant events and picks the right format and binding.

Follow the workflow below step by step. Every rule here comes from a source in Sources, with the section it cites. When a rule and the pinned source disagree, the source wins; when the source has a newer revision than the pin, follow the refresh steps.

Inputs (fill in, or ask before starting)

• Role: producer, consumer, or intermediary (a broker or router that forwards events).
• Transport: HTTP (including webhooks), Kafka, AMQP, MQTT, NATS, or several.
• Revision: CloudEvents 1.0.2 for the core specification, formats and bindings. Subscriptions and Pagination are drafts at 0.1-wip; Draft posture: track, pinned to the main-branch text read on 2026-10-02.
• Sources: when refreshing this skill or when a rule looks out of date, re-read every URL in Sources first, check the CloudEvents releases page and README documents table for a newer release (the main branch is 1.0.3-wip), and update the pins.

Invariants

1. Four attributes are required: id, source, specversion and type (spec, REQUIRED Attributes). specversion is "1.0".
2. source + id is unique per distinct event. A re-sent duplicate may keep the same id, and consumers may treat identical source and id as duplicates (spec, id).
3. Attribute names are lower-case ASCII letters and digits only, and should not exceed 20 characters. Extension attributes follow the same naming and type rules (spec, Attribute Naming Convention, Extension Context Attributes).
4. time is RFC 3339, and all producers for one source are consistent in how they set it (spec, time).
5. Every implementation supports the JSON format (spec, Overview). In JSON, extensions are top-level members, the media type is application/cloudevents+json, and data and data_base64 are mutually exclusive (JSON format § 2, § 3, § 3.1).
6. HTTP receivers detect the content mode from Content-Type: application/cloudevents means structured, application/cloudevents-batch means batched, anything else means binary (HTTP binding § 3). In binary mode, datacontenttype maps to Content-Type and must not also appear as ce-datacontenttype (HTTP binding § 3.1.1).
7. Batched mode is only used when the receiver asked for it, and every event in a batch has the same specversion (HTTP binding § 1.3, § 3.3).
8. Intermediaries forward events of 64 KByte or less; consumers should accept at least 64 KByte (spec, Size Limits).
9. No sensitive information in context attributes, because producers, consumers and intermediaries may log them (spec, Privacy and Security).

Workflow

1. Design the event type. Choose a reverse-DNS type, a source URI-reference, and the subject, dataschema and datacontenttype you need. -> references/attributes.md ✓ Each event type has a documented type, source pattern, data schema and the optional attributes it uses.
2. Add extensions only when needed. Prefer a documented extension, such as traceparent for tracing or partitionkey for Kafka keys, over a new one. -> references/attributes.md ✓ Every extension name follows the naming rule and has a definition.
3. Pick the format. Use JSON unless the transport or consumers need Avro or Protobuf; decide how data is encoded. -> references/formats.md ✓ A sample event serializes and validates against the 1.0.2 JSON Schema.
4. Map onto the transport. Choose binary or structured content mode per binding and map attributes to headers or the body. -> references/bindings.md ✓ A sample HTTP or Kafka message exists for each content mode you support.
5. Secure delivery. For webhooks, implement the abuse-protection handshake and the response codes; apply protocol-level security everywhere. -> references/bindings.md ✓ Webhook targets answer the OPTIONS validation request and return the status codes the webhook spec requires.
6. Check the draft specs before relying on them. If the design needs subscriptions, discovery or paginated listings, read their status first. -> references/drafts.md ✓ No production dependency rests on a draft without a recorded pin.

Verify before done

• Every event has id, source, specversion: "1.0" and type.
• JSON events validate against the 1.0.2 cloudevents.json schema (the schema does not check attribute names, so check those separately).
• All attribute and extension names match ^[a-z0-9]+$ and are 20 characters or fewer.
• Binary-mode HTTP messages carry ce- headers with percent-encoded values and no ce-datacontenttype.
• Kafka binary-mode messages use ce_ headers, and the record key follows the binding's key-mapping rule.
• Events stay within 64 KByte on the least efficient route.
• No secrets or personal data are carried in context attributes.

Reference index

• references/attributes.md: required and optional attributes, the type system, extension rules, and the documented extensions. Load for steps 1 and 2.
• references/formats.md: the JSON format, data and data_base64, the batch format, the JSON Schema, and the Avro and Protobuf formats. Load for step 3.
• references/bindings.md: HTTP binary, structured and batched modes, header encoding, the webhook spec, and the Kafka, AMQP, MQTT and NATS bindings. Load for steps 4 and 5.
• references/drafts.md: the status of Subscriptions, Discovery and Pagination, with summaries. Load for step 6.

Related skills

• ocsf to put security and audit events in a CloudEvent's data: npx skills add ScaleDockHQ/scaledock-skills --skill ocsf.
• opentelemetry-genai for tracing AI workloads that emit events: npx skills add ScaleDockHQ/scaledock-skills --skill opentelemetry-genai.
• asyncapi to document the channels that carry the events: npx skills add ScaleDockHQ/scaledock-skills --skill asyncapi.

Sources

Status uses the publishing body's own maturity term. Checked is the date the source was last read.

• CloudEvents specification repository and README: CNCF graduated project, main branch (documents table and project status), checked 2026-10-02.
• CloudEvents v1.0.2 release: Released, ce@v1.0.2 (2022-02-06), checked 2026-10-02.
• CloudEvents - Version 1.0.2: Released, 1.0.2, checked 2026-10-02.
• JSON Event Format for CloudEvents: Released, 1.0.2, checked 2026-10-02.
• CloudEvents JSON Schema: Released, 1.0.2, checked 2026-10-02.
• Avro Event Format for CloudEvents: Released, 1.0.2, checked 2026-10-02.
• Protobuf Event Format for CloudEvents: Released, 1.0.2, checked 2026-10-02.
• HTTP Protocol Binding for CloudEvents: Released, 1.0.2, checked 2026-10-02.
• HTTP 1.1 Web Hooks for Event Delivery: Released, 1.0.2, checked 2026-10-02.
• Kafka Protocol Binding for CloudEvents: Released, 1.0.2, checked 2026-10-02.
• AMQP Protocol Binding for CloudEvents: Released, 1.0.2, checked 2026-10-02.
• MQTT Protocol Binding for CloudEvents: Released, 1.0.2, checked 2026-10-02.
• NATS Protocol Binding for CloudEvents: Released, 1.0.2, checked 2026-10-02.
• CloudEvents Extension Attributes (documented extensions): Released, 1.0.2, checked 2026-10-02.
• Distributed Tracing extension: Released, 1.0.2, checked 2026-10-02.
• Partitioning extension: Released, 1.0.2, checked 2026-10-02.
• CloudEvents Subscriptions API: working draft, Version 0.1-wip (main branch), Draft posture: track, checked 2026-10-02.
• xRegistry specification repository: release candidate, v1.0-rc4 (core and registries), checked 2026-10-02.
• xRegistry Pagination: working draft, Version 0.1-wip (main branch), Draft posture: track, checked 2026-10-02.