diegosouzapw 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-managementskill 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