AsyncAPI specification handling for event-driven API documentation. Parse, validate, and generate documentation for message-based APIs including Kafka, MQTT, WebSocket, and AMQP systems.
Generates and validates AsyncAPI documentation for event-driven APIs including Kafka, MQTT, WebSocket, and AMQP systems.
npx claudepluginhub a5c-ai/babysitterThis skill is limited to using the following tools:
README.mdGenerate and validate documentation for event-driven APIs using the AsyncAPI specification with support for multiple messaging protocols.
Invoke this skill when you need to:
| Parameter | Type | Required | Description |
|---|---|---|---|
| specPath | string | Yes | Path to AsyncAPI specification |
| outputDir | string | No | Documentation output directory |
| generator | string | No | html, markdown, react (default: html) |
| validate | boolean | No | Run spec validation (default: true) |
| lint | boolean | No | Run Spectral linting (default: true) |
| generateCode | boolean | No | Generate client/server stubs |
| codeLanguage | string | No | Code generation target language |
{
"specPath": "./asyncapi.yaml",
"outputDir": "docs/async",
"generator": "html",
"validate": true,
"lint": true,
"generateCode": true,
"codeLanguage": "typescript"
}
docs/async/
├── index.html # Main documentation page
├── servers.html # Server/broker documentation
├── channels/
│ ├── user-events.html # Channel documentation
│ └── order-events.html
├── messages/
│ ├── UserCreated.html # Message documentation
│ └── OrderPlaced.html
├── schemas/
│ ├── User.html # Schema documentation
│ └── Order.html
├── bindings/ # Protocol bindings
│ └── kafka.html
├── search.json # Search index
└── asyncapi.json # Bundled spec
asyncapi: 3.0.0
info:
title: User Events API
version: 1.0.0
description: |
Event-driven API for user management operations.
## Overview
This API publishes events when user data changes.
Consumers can subscribe to specific channels to receive
real-time updates.
## Authentication
All connections require a valid API key passed in the
connection headers.
contact:
name: API Team
email: api-team@example.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
production:
host: kafka.example.com:9092
protocol: kafka
description: Production Kafka cluster
security:
- $ref: '#/components/securitySchemes/sasl'
tags:
- name: production
description: Production environment
staging:
host: kafka-staging.example.com:9092
protocol: kafka
description: Staging environment
channels:
userCreated:
address: user.events.created
messages:
UserCreatedMessage:
$ref: '#/components/messages/UserCreated'
description: |
Published when a new user account is created.
**Trigger**: User registration completion
**Frequency**: ~1000 events/day
userUpdated:
address: user.events.updated
messages:
UserUpdatedMessage:
$ref: '#/components/messages/UserUpdated'
operations:
publishUserCreated:
action: send
channel:
$ref: '#/channels/userCreated'
summary: Publish user created event
description: |
Publishes an event when a new user is created.
Events are partitioned by user ID.
tags:
- name: users
bindings:
kafka:
groupId: user-service
clientId: user-publisher
subscribeUserCreated:
action: receive
channel:
$ref: '#/channels/userCreated'
summary: Subscribe to user created events
description: |
Subscribe to receive notifications when new users
are created. Ideal for:
- Welcome email services
- Analytics tracking
- Audit logging
components:
messages:
UserCreated:
name: UserCreated
title: User Created Event
summary: Event published when a user is created
contentType: application/json
traits:
- $ref: '#/components/messageTraits/commonHeaders'
payload:
$ref: '#/components/schemas/UserCreatedPayload'
examples:
- name: NewUser
summary: Standard user creation
payload:
userId: "usr_123456"
email: "john@example.com"
createdAt: "2026-01-24T10:30:00Z"
source: "web-signup"
UserUpdated:
name: UserUpdated
title: User Updated Event
summary: Event published when user data changes
contentType: application/json
payload:
$ref: '#/components/schemas/UserUpdatedPayload'
schemas:
UserCreatedPayload:
type: object
description: Payload for user created events
required:
- userId
- email
- createdAt
properties:
userId:
type: string
description: Unique user identifier
pattern: "^usr_[a-zA-Z0-9]+$"
examples:
- "usr_123456"
email:
type: string
format: email
description: User's email address
createdAt:
type: string
format: date-time
description: Timestamp of user creation
source:
type: string
enum:
- web-signup
- mobile-app
- admin-portal
- api
description: Registration source
UserUpdatedPayload:
type: object
required:
- userId
- updatedAt
- changes
properties:
userId:
type: string
description: Unique user identifier
updatedAt:
type: string
format: date-time
changes:
type: array
items:
type: object
properties:
field:
type: string
oldValue:
type: string
newValue:
type: string
messageTraits:
commonHeaders:
headers:
type: object
properties:
correlationId:
type: string
description: Correlation ID for distributed tracing
format: uuid
timestamp:
type: string
format: date-time
description: Event timestamp
version:
type: string
description: Schema version
securitySchemes:
sasl:
type: scramSha256
description: SASL/SCRAM-SHA-256 authentication
channels:
orderEvents:
address: orders.events
bindings:
kafka:
topic: orders.events.v1
partitions: 12
replicas: 3
topicConfiguration:
cleanup.policy:
- delete
retention.ms: 604800000 # 7 days
segment.bytes: 1073741824
messages:
OrderCreated:
bindings:
kafka:
key:
type: string
description: Order ID used as partition key
schemaIdLocation: header
schemaIdPayloadEncoding: confluent
asyncapi: 3.0.0
info:
title: Real-time Notifications API
version: 1.0.0
servers:
production:
host: ws.example.com
protocol: wss
description: WebSocket server for real-time notifications
channels:
notifications:
address: /notifications/{userId}
parameters:
userId:
description: The user ID to receive notifications for
messages:
Notification:
$ref: '#/components/messages/Notification'
bindings:
ws:
query:
type: object
properties:
token:
type: string
description: Authentication token
required:
- token
asyncapi: 3.0.0
info:
title: IoT Sensor API
version: 1.0.0
servers:
production:
host: mqtt.example.com:8883
protocol: mqtts
description: MQTT broker for IoT devices
channels:
sensorReadings:
address: sensors/{sensorId}/readings
parameters:
sensorId:
description: Unique sensor identifier
messages:
SensorReading:
$ref: '#/components/messages/SensorReading'
bindings:
mqtt:
qos: 1
retain: false
bindingVersion: '0.2.0'
# Validate specification
asyncapi validate asyncapi.yaml
# Validate with custom rules
asyncapi validate asyncapi.yaml --rule-file .spectral.yaml
# Generate HTML documentation
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o docs
# Generate Markdown
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/markdown-template -o docs
# Generate React app
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/react-component -o docs
# TypeScript types
asyncapi generate models asyncapi.yaml typescript -o src/types
# Java models
asyncapi generate models asyncapi.yaml java -o src/main/java
# Python models
asyncapi generate models asyncapi.yaml python -o src/models
extends:
- "@asyncapi/spectral-ruleset"
rules:
# Require descriptions
asyncapi-info-description: error
asyncapi-channel-description: warn
asyncapi-operation-description: warn
# Require examples
asyncapi-message-examples: warn
# Schema validation
asyncapi-payload-unsupported-schemaFormat: error
asyncapi-schema: error
# Custom rules
operation-summary-required:
description: Operations must have summaries
given: "$.operations[*]"
then:
field: summary
function: truthy
severity: warn
message-content-type:
description: Messages must specify content type
given: "$.components.messages[*]"
then:
field: contentType
function: truthy
severity: error
channels:
paymentCompleted:
address: payments.completed.v1
description: |
## Payment Completed Events
Published when a payment is successfully processed.
### Use Cases
- Order fulfillment initiation
- Customer notification
- Financial reconciliation
### Consumer Guidelines
- Process events idempotently (use `paymentId` for deduplication)
- Acknowledge within 30 seconds
- Implement dead letter queue handling
### SLA
- **Latency**: Events published within 1s of payment completion
- **Ordering**: Events are ordered by `paymentId` within partition
- **Retention**: 7 days
components:
schemas:
Payment:
type: object
title: Payment
description: |
Represents a completed payment transaction.
## Versioning
This schema follows semantic versioning. Breaking changes
will result in a new major version.
## Privacy
Contains PII - handle according to data protection policies.
required:
- paymentId
- amount
- currency
properties:
paymentId:
type: string
format: uuid
description: Unique payment identifier
x-field-extra-annotation: "@Id"
amount:
type: number
format: decimal
description: Payment amount in minor units (cents)
minimum: 0
examples:
- 1999
- 50000
currency:
type: string
pattern: "^[A-Z]{3}$"
description: ISO 4217 currency code
examples:
- USD
- EUR
- GBP
{
"devDependencies": {
"@asyncapi/cli": "^1.0.0",
"@asyncapi/html-template": "^2.0.0",
"@asyncapi/markdown-template": "^1.0.0",
"@asyncapi/generator": "^1.0.0",
"@asyncapi/modelina": "^3.0.0",
"@stoplight/spectral-cli": "^6.0.0",
"@asyncapi/spectral-ruleset": "^1.0.0"
}
}
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.