catalog-documentation-creator

What this skill does

# EventCatalog Documentation Creator

Generate properly formatted EventCatalog documentation files following project conventions and best practices.

## Instructions

### Step 1: Locate or Create the User's Catalog

Before generating any files, ask the user: **"Do you already have an EventCatalog project, or would you like to create a new one?"**

**If they already have a catalog:**
- Ask: **"Where is your EventCatalog project?"** — It could be:
  - A repo they've cloned locally (e.g., `~/projects/my-catalog/`)
  - A folder on their machine
  - A monorepo with the catalog in a subdirectory
- Verify it looks like an EventCatalog project by checking for an `eventcatalog.config.js` file or known directories (`services/`, `agents/`, `events/`, `domains/`, etc.)
- Read the existing structure to understand whether they use **nested** (domains/services/agents/events) or **flat** (top-level services/, agents/, events/) organization

**If they don't have a catalog yet:**
- Ask where they'd like to create it (default: current directory)
- Run the following command to scaffold a new empty catalog:
  ```bash
  npx @eventcatalog/create-eventcatalog@latest my-catalog --empty
  ```
  (Replace `my-catalog` with the user's preferred name)
- This creates a ready-to-use EventCatalog project with the correct structure
- All generated documentation files go inside this new catalog directory

CRITICAL: All generated files must be written to the user's catalog directory, not just displayed. Always ask where they want resources documented — never assume.

### Step 2: Understand What the User Wants to Document

Ask the user what they want to document. Common scenarios:

- A single service or agent and its messages
- An event, command, or query
- A full domain with nested services
- A business flow across services and agents
- A channel (Kafka topic, RabbitMQ queue, etc.)
- A container (database, cache, queue)

Gather this information before generating:
- Resource name and purpose
- Version (default to `0.0.1` for new resources)
- Message relationships (what it sends/receives)
- Channel routing (what channels messages flow through)
- Containers (what databases/caches the service reads from or writes to)
- Agent model/provider and tools when documenting agents
- Schema format if applicable (JSON Schema, Avro, Protobuf)

If the user points you at a codebase (not the catalog), analyze it to extract services, agents, messages, schemas, and relationships — then generate the corresponding catalog documentation.

### Step 3: Check the Existing Catalog

If the catalog directory already has resources, read the existing files to understand:
- Naming conventions (PascalCase IDs? kebab-case?)
- Folder structure (nested under domains or flat?)
- Which owners/teams are already defined
- Badge styles and patterns used
- Schema formats in use (JSON Schema, Avro, etc.)

Match new documentation to these existing conventions.

If the user has the EventCatalog MCP server connected:

1. Use `getResources` to see what already exists in the catalog
2. Use `getResource` to check conventions used in existing entries (naming patterns, owner formats, badge styles)
3. Use `findResourcesByOwner` to suggest consistent ownership
4. Use `getSchemaForResource` to match existing schema formats

This ensures new documentation is consistent with what's already in the catalog.

### Step 4: Generate the Documentation

Generate files following the resource-specific references. Consult the appropriate reference file for the resource type:

- `references/services.md` — Services with sends/receives, channel routing, containers
- `references/agents.md` — Agents with model metadata, tools, sends/receives, containers, and flows
- `references/events.md` — Events with schemas, payload examples, producer/consumer code
- `references/commands.md` — Commands with REST operations and schemas
- `references/queries.md` — Queries with REST operations and response schemas
- `references/domains.md` — Domains with subdomains, services, and business context
- `references/flows.md` — Business flows with steps, branching, and external systems
- `references/channels.md` — Channels with routing, protocols, and parameters
- `references/containers.md` — Containers (databases, caches, queues) with data classification
- `references/ubiquitous-language.md` — Ubiquitous language terms per domain (DDD glossary/dictionary)
- `references/teams-and-users.md` — Teams and users (ownership)
- `references/components.md` — Components (NodeGraph, Schema, Mermaid, Tabs, etc.) and resource references (`[[type|Name]]` wiki-style links)

Every resource file MUST include:

- Valid YAML frontmatter between `---` delimiters
- `id` field matching existing catalog conventions
- `name` as human-readable display name
- `version` as semantic version string
- `summary` as a concise 1-2 sentence description

CRITICAL: Always use `index.mdx` as the filename for resources (services, agents, events, commands, queries, domains, flows, channels). Teams and users use `{id}.mdx` files directly. Place files in the correct folder path following the nested structure pattern:

```
domains/{DomainName}/services/{ServiceName}/events/{EventName}/index.mdx
domains/{DomainName}/agents/{AgentName}/index.mdx
```

Or flat structure if the catalog uses that pattern:

```
services/{ServiceName}/index.mdx
agents/{AgentName}/index.mdx
events/{EventName}/index.mdx
```

### Step 5: Validate the Output

Before presenting the files to the user, verify:

- YAML frontmatter has `---` delimiters on both sides
- All `id` fields are consistent (no spaces, match folder name)
- All `version` fields are valid semver strings (e.g., `0.0.1`)
- All message references in `sends`/`receives` include `id` and optionally `version`
- Channel routing uses `to`/`from` fields correctly in sends/receives
- Schema files referenced in `schemaPath` actually exist or are generated
- `<NodeGraph />` component is included for architecture visualization
- Owner IDs reference real teams/users in the catalog

## Common Patterns

### Documenting a Service That Processes Messages

When a user says "document my payment service that receives OrderCreated events and sends PaymentProcessed events":

1. Generate the service `index.mdx` with `receives` and `sends` arrays
2. If messages flow through channels, add `to`/`from` fields to the sends/receives
3. Generate each event `index.mdx` if they don't already exist in the catalog
4. Include `<NodeGraph />` in the service body to show message flow
5. Add example payload sections for each message
6. Place files in the correct nested folder structure

### Documenting an Agent

When a user says "document my support agent that reads order data and uses Zendesk":

1. Generate the agent `index.mdx` with `model`, `tools`, `receives`/`sends`, `readsFrom`/`writesTo`, and `flows` where known
2. Generate or reference events/commands/queries the agent consumes or produces
3. Generate containers for data stores the agent reads or writes
4. Include `<AgentTools />` when tools are documented
5. Include `<NodeGraph />` so the agent appears in architecture visualizations
6. If the agent belongs to a domain, add it to the domain's `agents` frontmatter

### Documenting a Domain

CRITICAL: A domain MUST have at least one service or agent. Never create an empty domain. If the user describes a domain, ensure services or agents are identified and generated for it.

When a user wants to document a full domain:

1. Identify the services and agents that belong to this domain. If the user hasn't specified any, ask them: "What services or agents belong to this domain?" Do NOT create an empty domain.
2. Generate the domain `index.mdx` with the `services` field listing every service and the `agents` field listing every agent
3. Generate each service and agent within the domain
4. Generate each message referenced by the services and agents
5. Generate channels if the user describes messaging infrastructure
6.