Skip to main content
skill CX Codex

flow-wizard — Claude Code skill: what it does, how to install

flow-wizard guides developers through documenting business workflows in EventCatalog step by step. Links flow steps to services, events, and AI agents already in your catalog.

MIT 616 installs ★ 16 updated 2026-10-26

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add event-catalog/skills --skill flow-wizard -a claude-code
Open on GitHub

What flow-wizard does

The skill conducts a structured interview to break an end-to-end process into sequential sections. First, it locates the local EventCatalog setup by checking for eventcatalog.config.js or querying the EventCatalog MCP server via getResources. Projects lacking a catalog can still proceed. In that scenario, steps stay as plain text descriptions without linked resources.

During each section, the wizard assigns specific step types like services, messages, actors, data containers, or AI agents. It checks catalog files for matching IDs and versions. Referencing a missing component triggers the refs/resource-exists linter error. To avoid broken builds, the skill prompts you to create the missing resource first or record a plain text placeholder.

What it helps with

  • map end-to-end architecture workflows into structured catalog stages
  • cross-reference message flows with existing events, commands, and services
  • prevent refs/resource-exists linter errors before saving new flow files
  • document agentic workflows involving tools, actors, and databases

Example prompts for the agent

  • Help me document the end-to-end checkout flow in EventCatalog
  • Walk through our user onboarding process and map it to our auth service and events
  • Create a flow diagram for our support triage agent handling incoming tickets

How to install flow-wizard

1Skills CLI (Vercel)

npx skills add event-catalog/skills --skill flow-wizard -a claude-code

2Manually: put the files in place

~/.claude/skills/flow-wizard/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/flow-wizard/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about flow-wizard

How to install flow-wizard in Claude Code?

Run npx skills add event-catalog/skills --skill flow-wizard -a claude-code in your terminal. Alternatively, place the file at ~/.claude/skills/flow-wizard/SKILL.md.

What does flow-wizard do?

It interviews you about a system process and structures it into sections. Then it matches each action to documented services, messages, channels, or agents.

Can flow-wizard work without an existing EventCatalog?

Yes. It documents steps as plain text summaries so you can link specific catalog resources later.

Source text

SKILL.md · MIT
---
name: flow-wizard
description: Guides users through documenting business flows step-by-step in EventCatalog, including services, agents, messages, channels, systems, data stores, actors, and external systems. Use when user asks to "document a flow", "map a business process", "create a flow diagram", "walk through a process", "document an end-to-end flow", "map an agent workflow", or "map out how something works in my architecture".
license: MIT
metadata:
  author: eventcatalog
  version: "1.0.0"
---

# Flow Documentation Wizard

An interactive, conversational skill that guides users through documenting business flows in EventCatalog — step by step, section by section — while cross-referencing their existing catalog resources.

## Instructions

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

Before anything else, you need to find the user's EventCatalog project so you can cross-reference existing resources.

Ask: **"Do you have an EventCatalog project I can look at? If so, where is it?"**

- If they provide a path, verify it's an EventCatalog project by checking for `eventcatalog.config.js` or known directories (`services/`, `agents/`, `events/`, `domains/`, `systems/`, `flows/`).
- If they have the EventCatalog MCP server connected, use `getResources` to discover what's in the catalog.
- If they don't have one, that's fine — you'll document steps as plain text descriptions without resource references. Let them know they can still create a useful flow and add resource links later.

Once located, scan the catalog to build an inventory of existing resources:
- Read existing services, agents, events, commands, queries, domains, systems, channels, containers (data stores), data products, and flows
- Note their IDs, names, and versions — you'll use these to suggest matches as the user walks through their flow

### Step 2: Ask What Flow They Want to Document

Ask: **"What flow would you like to document? Describe the end-to-end process you're trying to capture."**

Let the user describe the flow in their own words. Examples:
- "User signs up, gets a welcome email, and is added to our CRM"
- "Order is placed, payment is processed, inventory is reserved, and the order is shipped"
- "A customer submits a support ticket, it gets triaged, assigned to an agent, and resolved"
- "A support agent receives an order event, looks up order context, and updates the support case"

From their description, break the flow into **sections** (high-level stages). Present these sections back to the user for confirmation:

**Example response:**
> Based on your description, I can see roughly these sections:
> 1. **User Registration** — the user signs up
> 2. **Welcome Communication** — welcome email is sent
> 3. **CRM Integration** — user is added to the CRM
>
> Does that look right? We'll walk through each one in detail. Feel free to add, remove, or reorder sections.

Wait for confirmation before proceeding.

### Step 3: Walk Through Each Section

Go through each section **one at a time**. For each section, ask the user to describe what happens. The user leads the conversation — you follow.

For each section, ask something like:

**"Let's start with [Section Name]. What happens here? Who or what triggers it, and what happens as a result?"**

As the user describes what happens, you need to:

#### A. Identify the Step Type

From their description, determine which kind of step(s) this section involves. Each step is **one** of these (see `references/flows.md` for the exact shapes):

- **Actor** — a person or role does something (e.g., "the user clicks sign up", "the admin approves")
- **Service** — a service in their architecture processes something (e.g., "our auth service handles registration")
- **Agent** — an AI agent reasons, invokes tools, or automates part of the process (e.g., "the refund agent reviews the case")
- **Message** — an event, command, or query is exchanged (e.g., "a UserRegistered event is fired")
- **Channel** — where a message travels, when it matters (e.g., "it goes onto the orders Kafka topic")
- **System** — a whole system takes part, internal or external (e.g., "the billing platform handles it")
- **Container** — a data store is read or written (e.g., "we save it to the orders database")
- **Data product** — an analytical data product is produced or consumed
- **Sub-flow** — the process hands off to another documented flow (e.g., "then the refund flow starts")
- **External System** — a third-party system that isn't in the catalog (e.g., "we call Stripe for payment", "Twilio sends the SMS")
- **Custom** — anything else worth drawing (a manual review, a UI, a scheduled job)
- **Plain step** — a titled box that points at nothing (e.g., "the cancellation is rejected")

A single section may produce multiple steps (e.g., a user action triggers a command, which is handled by a service, which emits an event). A step can never be two things at once — "the service emits an event" is two steps.

#### B. Cross-Reference the Catalog

For each step the user describes, search their EventCatalog (if available) for matching resources:

1. **Services** — Does the service they mention exist in the catalog? Search by name, ID, or similar terms.
2. **Agents** — Does the AI agent, assistant, copilot, or autonomous worker they mention exist in the catalog?
3. **Events/Commands/Queries** — Does the message they describe match something already documented? Look for exact matches and close matches (e.g., user says "order created event" → search for `OrderCreated`, `OrderPlaced`, etc.).
4. **Channels** — Are there channels relevant to how this message flows?
5. **Systems** — Is this a documented system (including external systems with `scope: external`, e.g. Stripe)? Prefer a `system` step over `externalSystem` when it is.
6. **Containers / data products** — Is the data store or data product they mention documented?
7. **Domains** — Does this step fall within a documented domain?

**If you find a match**, tell the user:

> I found a **[resource type]** called `[ResourceName]` (version `[version]`) in your catalog that looks like it matches. Would you like to reference it in this step?

If they say yes, use the resource's actual `id` and `version` in the flow step.

**If you find multiple possible matches**, present them and let the user choose:

> I found a few resources that might match what you're describing:
> - `OrderCreated` (event, v1.0.0) — "Emitted when a new order is placed"
> - `OrderPlaced` (event, v0.0.1) — "Published when checkout completes"
>
> Which one fits, or is this something new?

**If you find no match**, that's perfectly fine — but don't point at a resource that doesn't exist. A `service`, `agent`, `message`, `channel`, `system`, `container`, `dataProduct` or `flow` pointer to something missing fails the linter (`refs/resource-exists`, an error by default). Ask the user which they prefer:
- **Create the resource first** — document it with the `catalog-documentation-creator` skill, then point the step at it. Best for services, agents and messages that really exist.
- **Describe it without a pointer** — a plain titled step (`id` + `title` + `summary`), or a `custom` step with an icon. Good for things they don't want to document yet.
- If it's a person/role, use `actor`
- If it's a third-party tool/API that isn't in the catalog, use `externalSystem`

Let the user know: **"I didn't find this in your catalog. I'll [create it / describe it as a plain step] for now. You can document the full resource later and point the step at it."**

#### C. Confirm Each Section Before Moving On

After processing a section, summarize what you've captured for that section and ask the user to confirm before moving to the next one.

**Example:**
> Here's what I've captured for **Payment Processing**:
>
> 1. `ProcessPayment` command is sent (matched to your existing `ProcessPayment` command v0.0.1)
> 2. `PaymentService` handles the payment (matched to your existing `PaymentService` v1.2.0)
> 3. `FraudReviewAgent` reviews fraud signals (matched to your existing `FraudReviewAgent` v0.0.1)
> 4. Calls **Stripe** (external system) to charge the card
> 5. `PaymentProcessed` event is emitted (not in your catalog yet — want me to create it first, or describe it as a plain step for now?)
>
> Does that look right? Anything to add or change?

### Step 4: Handle Branching and Edge Cases

As you walk through sections, watch for:

- **Branching paths** — "If payment succeeds, we continue; if it fails, we notify the user"
  - Ask: **"It sounds like there's a decision point here. What are the possible paths?"**
  - Document these as `next_steps` (plural) with labels for each branch

- **Loops** — "The service retries if the external call fails"
  - Document as a step that references back to an earlier step via `next_step`

- **Error/failure paths** — "If validation fails, we send back an error"
  - These are terminal steps or branch to a notification/error handling step

- **Parallel paths** — "While payment processes, we also reserve inventory"
  - Document as separate branches from a common step using `next_steps`

When you detect branching, explicitly confirm the paths with the user:

> **"It sounds like there's a fork here. After [step], these things could happen:**
> 1. [Success path] → continues to [next section]
> 2. [Failure path] → [what happens]
>
> **Is that right? Are there other outcomes?"**

### Step 5: Build the Flow Summary

After walking through all sections, present a complete summary of the flow before generating the file:

> **Here's the complete flow: [Flow Name]**
>
> 1. [Step 1 summary] → [Step 2]
> 2. [Step 2 summary] → [Step 3]
> 3. [Step 3 summary] → branches to [Step 4a] or [Step 4b]
> ...
>
> **Resources matched from your catalog:** [list of matched resources]
> **New resources (not yet in catalog):** [list of unmatched items]
>
> Ready to generate the flow file?

### Step 6: Generate the Flow File

Once the user confirms, generate the flow `index.mdx` file following the format in `references/flows.md`.

**Rules for generation:**

1. Use the user's catalog directory. Ask where the flow should be saved if unclear — `flows/{FlowName}/index.mdx`, `domains/{Domain}/flows/{FlowName}/index.mdx`, or under a system (`systems/{System}/flows/{FlowName}/index.mdx`) depending on their catalog structure. If the flow belongs to a domain or system, also add it to that domain's or system's `flows` frontmatter — the folder alone doesn't link them.

2. For **matched resources** (found in catalog), use the exact `id` and `version` from the catalog. `title` is optional — it defaults to the resource's name, so only set it when a different label reads better:
   ```yaml
   - id: "payment_processing"
     service:
       id: "PaymentService"
       version: "1.2.0"
   ```

   Agent steps use the `agent` field:
   ```yaml
   - id: "fraud_review"
     agent:
       id: "FraudReviewAgent"
       version: "0.0.1"
   ```

   Channel, system, container, data product and sub-flow steps use the same `{ id, version }` shape under `channel`, `system`, `container`, `dataProduct` or `flow`.

3. For **unmatched resources** the user chose not to create yet, write a plain step (no pointer) or a `custom` step:
   ```yaml
   - id: "send_welcome_email"
     title: "Send Welcome Email"
     summary: "WelcomeEmailRequested is sent (not documented yet)"
   ```

4. For **actors**, use the role or persona name:
   ```yaml
   - id: "user_initiates_signup"
     title: "User Signs Up"
     actor:
       name: "Customer"
   ```

5. For **external systems**, include name, summary, and URL if known:
   ```yaml
   - id: "stripe_charges_card"
     title: "Stripe Payment"
     externalSystem:
       name: "Stripe"
       summary: "Third-party payment processor"
       url: "https://stripe.com"
   ```

6. Connect all steps with `next_step` or `next_steps` as appropriate.

7. Terminal steps (end of flow or end of a branch) should have no `next_step`.

8. The body should be `<NodeGraph />`.

   Never add a `type` field to steps (it's ignored), and put any custom step metadata in `x-` keys — unknown keys fail the build.

9. Set `version` to `0.0.1` for new flows.

10. Write a meaningful `summary` that describes the end-to-end business process.

### Step 7: Validate and Write

Before writing the file:

1. Verify all step IDs are unique within the flow
2. Verify all `next_step` / `next_steps` references point to valid step IDs, and no step has both
3. Verify every pointer matches a resource id (and version, if set) in the catalog
4. Verify no step points at two things, and there are no unknown keys (custom ones must start with `x-`)
5. Verify the YAML frontmatter is valid
6. Verify `<NodeGraph />` is in the body

Write the file to the user's catalog directory. If the catalog has a `lint` script (catalogs from `create-eventcatalog` run `eventcatalog-linter`), run `npm run lint` and fix anything it reports.

After writing, let the user know:
- Where the file was saved
- Which resources were matched from their catalog
- Which resources are new/unmatched — suggest they can document these later using the `catalog-documentation-creator` skill, especially new agents
- They can view the flow visualization in EventCatalog by running their dev server, and group it by domain, system or team from the flow page (or open it grouped with `<Flow id="..." lanes="team" />`)

## Conversation Guidelines

- **The user leads.** You ask questions and guide, but the user describes what happens in their own words. Don't assume or invent steps.
- **One section at a time.** Don't rush ahead. Confirm each section before moving on.
- **Be helpful with matches.** When you find catalog resources that match, proactively suggest them — but always let the user decide.
- **Be honest about misses.** If nothing in the catalog matches, say so plainly and document it descriptively.
- **Keep it conversational.** This is a guided walkthrough, not a form to fill out. Be natural and responsive.
- **Suggest, don't dictate.** If the user's description doesn't perfectly map to a step type, suggest what you think fits and ask if that's right.
- **Handle complexity gracefully.** If a flow gets complex (many branches, loops), help the user keep track by summarizing periodically.

## Searching the Catalog

When searching for matching resources, use these strategies:

1. **Exact ID match** — search for the exact name mentioned (e.g., "OrdersService" → look for `OrdersService`)
2. **Fuzzy match** — search for variations (e.g., "orders service" → try `OrdersService`, `OrderService`, `orders-service`)
3. **Semantic match** — if the user says "the thing that handles payments", search for services with "payment" in the name or summary
4. **Browse by type** — if you know it's an event, search events specifically
5. **Agent terms** — if the user says "assistant", "copilot", "worker", "reviewer", or "agent", search `agents/` before treating it as an external system

If the EventCatalog MCP server is available:
- Use `getResources` to list all resources
- Use `getResource` to get details on a specific resource
- Use `findResourcesByOwner` to explore resources by team

If reading the filesystem directly:
- Look in `services/`, `agents/`, `events/`, `commands/`, `queries/`, `domains/`, `systems/`, `flows/`, `channels/`, `containers/`, `data-products/` directories (they can also be nested under domains and systems)
- Read `index.mdx` files to check `id`, `name`, `version`, and `summary` fields

## Quality Checklist

Before delivering the flow file:

1. Every step has a unique `id`
2. Every step has a clear label — a `title`, or a pointer whose resource name reads well (title defaults to it)
3. Every step is at most one thing (`actor`, `service`, `agent`, `message`, `channel`, `system`, `container`, `dataProduct`, `flow`, `custom`, or `externalSystem`), and no step has a `type` field
4. All `next_step` and `next_steps` references point to valid step IDs within the flow
5. No orphaned steps (every step is reachable from the first step, except via branching)
6. Every pointer matches a resource in the catalog (no placeholders — they fail `refs/resource-exists`)
7. The flow has a clear start (first step) and at least one terminal step (no `next_step`)
8. YAML frontmatter is valid with `---` delimiters
9. File is named `index.mdx`
10. `<NodeGraph />` is in the body
11. `version` is a valid semver string
12. `summary` describes the business process meaningfully

© eventcatalog · MIT · event-catalog/skills

Similar skills

All skills for Writing and docs →

From the same set5

Project sponsors

Companies that keep this analytics open