Mermaiddoc

Mermaiddoc Skill

Command: /mermaiddoc

Create readable Mermaid diagrams for repository documentation.

The skill creates Markdown files with Mermaid code blocks that render directly in GitHub.

The skill mainly creates these diagram types:

flowchart LR
sequenceDiagram

The skill stores generated diagram documentation in:

docs/diagrams/

Purpose

/mermaiddoc helps humans and agents create useful Mermaid diagrams for code documentation.

The goal is to create diagrams that:

• explain one focused concept
• render well in GitHub Markdown
• stay readable in pull requests and repository docs
• use simple Mermaid syntax
• use stable node IDs
• use short labels
• use clear arrows
• avoid visual clutter
• avoid layout tricks that break or look bad on GitHub
• can be maintained as text
• help future humans and agents understand the codebase faster

The goal is not to create decorative diagrams or complete visual models of the whole system.

Supported Diagram Types

Prefer these diagram types:

flowchart LR
sequenceDiagram

Use flowchart LR for:

• architecture overviews
• module dependencies
• request flow
• data flow
• build flow
• deployment flow
• agent workflow
• repository workflow
• command execution flow
• high-level process diagrams
• documentation generation flows

Use sequenceDiagram for:

• runtime interactions
• API calls
• request and response behavior
• agent and tool interactions
• user and system flows
• service-to-service communication
• event handling sequences
• retry sequences
• error handling paths

Do not use other Mermaid diagram types unless the user explicitly asks.

Slash Command

Use this skill when the user calls:

/mermaiddoc

Natural examples:

/mermaiddoc "Create a diagram for the authentication flow"
/mermaiddoc "Show the request lifecycle"
/mermaiddoc "Create a sequence diagram for startup and data processing"
/mermaiddoc "Show the main components of the application"

Choose the diagram type from the request and repository evidence:

1. Use sequenceDiagram when the user describes steps over time, calls, messages, requests, responses, retries, or interactions.
2. Use flowchart LR when the user describes structure, modules, dependencies, ownership, states, or process flow.
3. If both could fit, prefer flowchart LR for documentation overview diagrams.
4. If the intent is unclear, create one focused flowchart LR diagram and mention that a sequence diagram may be useful as a follow-up.

Required Output Files

Create diagram files under:

docs/diagrams/

Create the directory if it does not exist.

Default file format:

docs/diagrams/short-kebab-case-topic.md

Examples:

docs/diagrams/authentication-flow.md
docs/diagrams/request-lifecycle.md
docs/diagrams/agent-skill-workflow.md
docs/diagrams/repository-documentation-flow.md

Each file should be a Markdown file that GitHub can render directly.

Default file structure:

# [Diagram Title]

Purpose: [short purpose]

Source basis:
- [user input, repository files, architecture docs, code scan, or other source]

Diagram type: [flowchart LR | sequenceDiagram]

```mermaid
[diagram]

Notes:

• [important clarification]
• [important limitation]

Do not create image files by default.

Do not create SVG, PNG, or PDF output unless the user explicitly asks.

## Repository Inspection

Inspect the repository when the diagram should reflect existing code.

Use repository inspection when:

- the user mentions a source folder, module, command, API, service, or workflow
- the diagram should describe current architecture
- the user asks for a diagram from the codebase
- the user provides too little detail but the repository likely contains the answer
- existing `REPO_MAP.md`, `ARCHITECTURE.md`, `OPERATIONS.md`, or ADRs can provide useful context

Start with safe read-only inspection.

Recommended first pass:

```bash
pwd
git rev-parse --show-toplevel
git status --short
git ls-files
find . -maxdepth 2 -type f | sort
find . -maxdepth 2 -type d | sort

Inspect existing documentation first when present:

README.md
docs/REPO_MAP.md
docs/ARCHITECTURE.md
docs/API_SURFACE.md
docs/OPERATIONS.md
docs/adr/
docs/

Then inspect likely source and config files:

src/
app/
lib/
packages/
services/
cmd/
api/
routes/
controllers/
workers/
jobs/
config/
package.json
pyproject.toml
go.mod
Cargo.toml
Dockerfile
docker-compose.yml
.github/workflows/

Do not read secrets.

Never print secret values into generated diagrams or notes.

Sensitive files to avoid reading in full:

.env
.env.*
*.pem
*.key
*.crt
id_rsa
id_ed25519
secrets.*
credentials.*

It is acceptable to record that an environment file exists, but do not copy values.

Lightweight Provenance Block

Every generated Markdown diagram document must include a small provenance block near the top, directly after the title and before the purpose.

The block must include only information that is directly available. Do not guess, infer, reconstruct, or invent missing metadata.

Use this format:

> Generated with `ai-craftkit` skill: `mermaiddoc`  
> Source: `` at commit ``  
> Prompt: ``

Diagram Design Rules

Create small diagrams.

A good documentation diagram usually has:

• one clear purpose
• 4 to 9 main nodes for flowcharts
• 2 to 6 participants for sequence diagrams
• short labels
• clear arrows
• no decorative styling
• no dense text blocks
• no large nested structures
• no unnecessary edge labels
• no Mermaid features that are likely to render poorly in GitHub

Avoid:

• huge all-system diagrams
• long prose inside nodes
• deeply nested subgraphs
• many crossing arrows
• too many arrow label variants
• custom CSS
• theme initialization blocks
• unusual shapes without a clear reason
• layout tricks
• diagrams that require Mermaid Live Editor settings to understand

Prefer multiple small diagrams over one large diagram.

If the user asks for a broad diagram, create a focused overview and add notes about what to diagram separately.

GitHub Rendering Rules

Generated Markdown must use Mermaid code blocks:

```mermaid
flowchart LR
    A[Start] --> B[Next]

or:

```md
```mermaid
sequenceDiagram
    participant User
    participant API
    User->>API: Request
    API-->>User: Response

Use plain Mermaid syntax that GitHub renders directly.

Avoid relying on:

- external Mermaid config
- custom themes
- external CSS
- unsupported rendering options
- local editor settings
- generated images
- links that are required to understand the diagram

The Markdown file itself should be useful in GitHub.

## Flowchart Rules

Use `flowchart LR` by default.

`LR` keeps many code documentation diagrams readable because they follow the usual left-to-right direction of cause, dependency, or request flow.

Default structure:

```mermaid
flowchart LR
    User[User] --> Web[Web App]
    Web --> API[API]
    API --> Service[Service]
    Service --> DB[(Database)]

Use stable node IDs.

Good:

flowchart LR
    CLI[CLI Command] --> Skill[Skill Handler]
    Skill --> Template[Template]
    Skill --> Output[docs/diagrams/*.md]

Bad:

flowchart LR
    The user starts the command[The user starts the command] --> The skill looks through a lot of files[The skill looks through a lot of files]

Use short node labels.

Good:

flowchart LR
    Request[Request] --> Router[Router]
    Router --> Handler[Handler]
    Handler --> Service[Service]
    Service --> Repository[Repository]
    Repository --> Database[(Database)]

Use edge labels only when they add meaning.

Good:

flowchart LR
    API[API] -->|reads| Cache[(Cache)]
    API -->|writes| DB[(Database)]

Avoid labeling every edge.

Good:

flowchart LR
    User[User] --> App[App]
    App --> API[API]
    API --> Service[Service]
    Service --> DB[(Database)]

Bad:

flowchart LR
    User[User] -->|uses the browser to open the app| App[App]
    App -->|sends a request over HTTP to the backend API| API[API]
    API -->|calls the business logic layer to process the request| Service[Service]

Use subgraphs only when they make ownership or boundaries clearer.

Good:

flowchart LR
    User[User] --> API[API]

    subgraph Backend
        API --> Service[Service]
        Service --> Repository[Repository]
    end

    Repository --> DB[(Database)]

Avoid many nested subgraphs.

Good arrows for flowcharts:

flowchart LR
    A[Start] --> B[Next]
    B --> C[Done]

Use labeled arrows for meaningful action:

flowchart LR
    Client[Client] -->|HTTP request| API[API]
    API -->|query| DB[(Database)]
    DB -->|result| API
    API -->|HTTP response| Client

Use dotted arrows only for optional, indirect, or asynchronous relationships:

flowchart LR
    Service[Service] -. optional event .-> Queue[Queue]
    Queue -. async processing .-> Worker[Worker]

Use thick arrows sparingly for the main path:

flowchart LR
    Request[Request] ==> Handler[Handler]
    Handler ==> Response[Response]
    Handler -. logs .-> Logger[Logger]

Use database shape for storage:

flowchart LR
    Repository[Repository] --> DB[(Database)]

Use bracket nodes for most modules:

flowchart LR
    Controller[Controller] --> Service[Service]
    Service --> Repository[Repository]

Use rounded nodes for start and end only when useful:

flowchart LR
    Start([Start]) --> Validate[Validate input]
    Validate --> End([Done])

Recommended Flowchart Patterns

Simple Request Flow

flowchart LR
    User[User] --> Web[Web App]
    Web --> API[API]
    API --> Service[Service]
    Service --> Repository[Repository]
    Repository --> DB[(Database)]

Module Boundary

flowchart LR
    subgraph Interface
        CLI[CLI]
        API[API]
    end

    subgraph Core
        Service[Service]
        Policy[Policy]
    end

    subgraph Infrastructure
        Repository[Repository]
        Provider[External Provider]
    end

    CLI --> Service
    API --> Service
    Service --> Policy
    Service --> Repository
    Service --> Provider

Agent Skill Workflow

flowchart LR
    User[User Request] --> Skill[Skill]
    Skill --> Inspect[Inspect Repository]
    Skill --> Generate[Generate Markdown]
    Generate --> Docs[docs/diagrams/*.md]

Decision or Check Flow

flowchart LR
    Input[Input] --> Check{Enough evidence?}
    Check -->|yes| Diagram[Create diagram]
    Check -->|no| Gap[Document gap]
    Diagram --> Output[Markdown file]
    Gap --> Output

Use decision diamonds only for real branching.

Avoid large decision trees.

Sequence Diagram Rules

Use sequenceDiagram for interactions over time.

Default structure:

sequenceDiagram
    actor User
    participant Web as Web App
    participant API
    participant Service
    participant DB as Database

    User->>Web: Submit request
    Web->>API: POST /resource
    API->>Service: Validate and process
    Service->>DB: Save data
    DB-->>Service: Saved
    Service-->>API: Result
    API-->>Web: 201 Created
    Web-->>User: Show confirmation

Use actor for humans when useful.

Use participant for systems, services, modules, or tools.

Prefer aliases when labels need spaces:

sequenceDiagram
    actor Dev as Developer
    participant CLI as CLI Command
    participant Skill as Mermaiddoc Skill
    participant Docs as docs/diagrams

Use solid arrows for calls:

sequenceDiagram
    API->>Service: Process request

Use dotted arrows for responses:

sequenceDiagram
    Service-->>API: Result

Use self messages for local work:

sequenceDiagram
    Service->>Service: Validate input

Use alt for important branches:

sequenceDiagram
    API->>Auth: Validate token
    alt Token valid
        Auth-->>API: User context
        API->>Service: Continue request
    else Token invalid
        Auth-->>API: Reject
        API-->>Client: 401 Unauthorized
    end

Use opt for optional behavior:

sequenceDiagram
    API->>Service: Process request
    opt Cache enabled
        Service->>Cache: Read cached value
        Cache-->>Service: Cached value
    end

Use loop only for real repeated behavior:

sequenceDiagram
    loop Retry up to 3 times
        Worker->>Provider: Send request
        Provider-->>Worker: Temporary failure
    end

Use Note over for short clarifications:

sequenceDiagram
    participant API
    participant Queue

    API->>Queue: Publish job
    Note over API,Queue: Job is processed asynchronously

Avoid long notes.

Avoid too many activation bars because they can make GitHub-rendered sequence diagrams look noisy.

Use activations only when they clarify nested or long-running work:

sequenceDiagram
    participant API
    participant Service

    API->>+Service: Process request
    Service-->>-API: Result

Recommended Sequence Patterns

Request and Response

sequenceDiagram
    actor User
    participant Web as Web App
    participant API
    participant Service
    participant DB as Database

    User->>Web: Submit form
    Web->>API: POST /items
    API->>Service: Create item
    Service->>DB: Insert item
    DB-->>Service: Item saved
    Service-->>API: Created item
    API-->>Web: 201 Created
    Web-->>User: Show success

Agent Tool Interaction

sequenceDiagram
    actor User
    participant Agent
    participant Skill as Mermaid Skill
    participant Repo as Repository
    participant Docs as docs/diagrams

    User->>Agent: Request diagram
    Agent->>Skill: Select diagram type
    Skill->>Repo: Inspect relevant files
    Repo-->>Skill: Evidence
    Skill->>Docs: Write Markdown diagram
    Skill-->>Agent: Report created file
    Agent-->>User: Summarize result

Error Path

sequenceDiagram
    participant Client
    participant API
    participant Auth
    participant Service

    Client->>API: Request protected resource
    API->>Auth: Validate token
    alt Valid token
        Auth-->>API: User context
        API->>Service: Load resource
        Service-->>API: Resource
        API-->>Client: 200 OK
    else Invalid token
        Auth-->>API: Reject
        API-->>Client: 401 Unauthorized
    end

Async Job Flow

sequenceDiagram
    participant API
    participant Queue
    participant Worker
    participant DB as Database

    API->>Queue: Enqueue job
    Queue-->>API: Job accepted
    Worker->>Queue: Fetch job
    Worker->>DB: Update state
    DB-->>Worker: Saved
    Worker-->>Queue: Acknowledge job

Diagram Creation Process

When /mermaiddoc is called, follow this process:

1. Determine the diagram focus from the user request.
2. Decide whether flowchart LR or sequenceDiagram fits better.
3. Inspect repository files if the diagram should reflect existing code.
4. Identify the smallest useful scope.
5. Choose a short diagram title.
6. Choose a stable kebab-case file name.
7. Create docs/diagrams/ if missing.
8. Write one Markdown file with a Mermaid code block.
9. Keep the diagram small and readable.
10. Add notes for assumptions, gaps, or omitted details.
11. Report the created file and the diagram type.

File Naming Rules

Use lower-case kebab-case filenames.

Good:

docs/diagrams/authentication-flow.md
docs/diagrams/request-lifecycle.md
docs/diagrams/adr-generation-workflow.md
docs/diagrams/api-worker-interaction.md

Bad:

docs/diagrams/Diagram1.md
docs/diagrams/big architecture overview.md
docs/diagrams/Auth Flow Final FINAL.md

If the file already exists:

1. Read it first.
2. Preserve useful

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stefanrossmeier
• Source: stefanrossmeier/ai-craftkit
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.