AsyncAPI Design Skill

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

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

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:

Related Skills (Cross-Plugin)

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