AsyncAPI Design Skill

When to Use This Skill

Use this skill when:

• Designing event-driven APIs - AsyncAPI 3.0 for message-based architectures

• Configuring message brokers - Kafka, RabbitMQ, MQTT, WebSocket bindings

• Implementing in C# - Event contracts, MassTransit, Confluent Kafka

• Event versioning - Schema evolution and backward compatibility

MANDATORY: Documentation-First Approach

Before creating AsyncAPI specifications:

• Invoke docs-management skill for event-driven patterns

• Verify AsyncAPI 3.0 syntax via MCP servers (context7 for latest spec)

• Base all guidance on AsyncAPI 3.0 specification

AsyncAPI vs OpenAPI

Aspect OpenAPI AsyncAPI

Communication Request/Response Event-Driven

Protocol HTTP/HTTPS Kafka, RabbitMQ, MQTT, WebSocket

Initiator Client requests Publisher emits

Pattern Synchronous Asynchronous

Use Case REST APIs Message queues, streaming, IoT

AsyncAPI 3.0 Structure Overview

asyncapi: 3.0.0 info: title: API Title version: 1.0.0

servers: production: host: kafka.example.com:9092 protocol: kafka

channels: orderCreated: address: orders.created messages: orderCreatedMessage: $ref: '#/components/messages/OrderCreated'

operations: publishOrderCreated: action: send channel: $ref: '#/channels/orderCreated'

components: messages: { } schemas: { } securitySchemes: { }

For complete template: See basic-template.md

Quick Reference

Supported Protocols

Protocol Use Case Binding Version

Kafka High-throughput streaming 0.5.0

AMQP (RabbitMQ) Message queuing 0.3.0

MQTT IoT, lightweight messaging 0.2.0

WebSocket Real-time browser comms

For protocol-specific patterns: See protocol-patterns.md

Channel Naming Convention

{domain}.{entity}.{action}.{version} Example: orders.order.created.v1

Workflow

• Identify events - What significant occurrences need to be communicated?

• Define channels - What topics/queues will carry these events?

• Design messages - What data does each event contain?

• Choose protocol - Kafka, RabbitMQ, MQTT, etc.?

• Add bindings - Protocol-specific configuration

• Document security - Authentication and authorization

• Version strategy - How will events evolve?

• Generate code - Use AsyncAPI generator for clients/handlers

References

Load on-demand based on need:

Reference Load When

basic-template.md Creating a new AsyncAPI spec from scratch

protocol-patterns.md Configuring Kafka, RabbitMQ, MQTT, WebSocket

csharp-implementation.md Implementing in .NET/C# with MassTransit or Confluent

event-design-patterns.md Event envelopes, versioning, best practices

Related Skills (Cross-Plugin)

Phase Skill Plugin Purpose

DESIGN asyncapi-design (this skill) formal-specification Architecture research, pattern selection

AUTHORING asyncapi-authoring

spec-driven-development Concrete YAML file creation

Workflow: Design (research event patterns) → Author (create YAML) → Implement (generate code)

MCP Research

For current AsyncAPI patterns and tools:

perplexity: "AsyncAPI 3.0 specification" "event-driven API design patterns" context7: "asyncapi" (for official documentation) ref: "AsyncAPI spec examples" "Kafka binding patterns"

Version History

• v2.0.0 (2026-01-17): Refactored to progressive disclosure pattern

• Extracted 4 reference files (~650 lines)

• Hub reduced from 789 to ~130 lines

• v1.0.0 (2025-12-26): Initial release

Last Updated: 2026-01-17