asyncapi-design

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:

1. Invoke docs-management skill for event-driven patterns
2. Verify AsyncAPI 3.0 syntax via MCP servers (context7 for latest spec)
3. 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

1. Identify events - What significant occurrences need to be communicated?
2. Define channels - What topics/queues will carry these events?
3. Design messages - What data does each event contain?
4. Choose protocol - Kafka, RabbitMQ, MQTT, etc.?
5. Add bindings - Protocol-specific configuration
6. Document security - Authentication and authorization
7. Version strategy - How will events evolve?
8. 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