pi-config/skills/project-diagramming-mermaid/SKILL.md

name, description, version

name	description	version
project-diagramming-mermaid	Use Mermaid to create or update a project diagram. Outline a codebase, project, or system using Mermaid syntax inside standard Markdown fenced blocks, then render it to PNG/SVG (and keep the Mermaid source) under the project's docs/ directory. Use when the user asks to map, outline, diagram, or visualize a codebase/project/system, or to update an existing project diagram. After producing the Mermaid diagram, prompt the user to also create or update the Archify doc. Per-project only — never global.	1.0.0

project-diagramming-mermaid

Diagram a codebase or project with Mermaid, render to image files, all under the project's docs/ directory.

When to use

• User asks to outline/map/visualize a codebase, project, system, or data flow at a high level.
• User asks to update an existing Mermaid project diagram.
• User asks to document the home network, Docker containers, or any infra — but see the Obsidian note below.

Workflow (overview)

1. Scope — clarify target: whole project, a subsystem, or a specific flow. Focus on high-level dependencies and data flows. Avoid complex layout overlaps (prefer <project>/docs/ artifacts that are readable, not exhaustive).
2. Author Mermaid source — write the diagram as a fenced ```mermaid block in the appropriate Markdown doc. See "Where the source lives" below.
3. Save source — write the Mermaid source to <project>/docs/<topic>.mmd.
4. Render — render to <project>/docs/diagrams/<topic>.png (and optionally .svg) via mmdc.
5. Prompt Archify — after the Mermaid diagram is done, ask the user: "Create/update the Archify doc for this too?" (see project-diagramming-archify skill). Do this automatically, not just when asked.

Where the source lives

Artifacts for a project go under that project's docs/ — everything is per-project in this setup:

• Source (single source of truth): <project>/docs/<topic>.mmd
• Markdown doc with the fenced block: the project's main doc(s), e.g. <project>/docs/README.md, <project>/docs/<topic>.md, <project>/README.md — anywhere the user wants the diagram visible (Obsidian renders ```mermaid natively).
• Rendered images: <project>/docs/diagrams/<topic>.png (+ .svg when requested)

If <project>/docs/ does not exist, create it. Never write diagram artifacts outside the project directory.

Writing good Mermaid

High-level, readable diagrams — not layout spaghetti:

• Flowchart (graph TD / flowchart LR) for dependencies and data flows. Use A --> B for dependency/data flow, A -.-> B for optional, subgraphs for grouping.
• Sequence (sequenceDiagram) for request/API flows with participants.
• Class (rare) for type structure; ER (erDiagram) for data model; stateDiagram-v2 for lifecycle.
• Keep node labels short. Add them with A[Label text]. Edge labels A -->|"verb"| B.
• Avoid deeply nested subgraphs and crossing edges — if it gets busy, split into multiple diagrams per topic.
• Prefer flowchart LR for wide dependency chains (reads better on screens), graph TD for hierarchies.

Example:

flowchart LR
  U[User] --> W[Web UI] --> API[API Gateway] --> DB[(Postgres)]
  API --> Q[Message Queue] --> W1[Worker] --> DB

Rendering with mmdc (mermaid-cli)

• mmdc is provided by nixpkgs mermaid-cli (pkgs.mermaid-cli, v11.16.0) installed in home.packages on .27 / .13 / .51. It bundles its own Chromium from the Nix store — deterministic, offline, private. See system-architect skill for machine details.
• Check availability: which mmdc. If missing, it's a Nix install (home.nix home.packages) — NOT an npm install (Nix store is read-only). Tell the user.

Commands:

# PNG (default 4x for crispness with --scale; choose scale for size)
mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.png --scale 2 -b white

# SVG (vector, good for docs)
mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.svg

# Use a theme/style: -t dark|neutral|forest|base
mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.png --theme neutral

After rendering, verify the file exists and is non-trivial in size (a few KB+). If mmdc fails, read the error — most failures are syntax errors in the diagram; fix and re-run.

Prompt the user for the Archify follow-up

After a successful Mermaid diagram, always ask (or offer via the flow below):

"Diagram saved to <project>/docs/diagrams/<topic>.png. Create/update the Archify doc too?"

If yes (or user asked originally), invoke the project-diagramming-archify skill — Archify accepts Mermaid (flowchart → workflow/architecture, sequence → sequence, stateDiagram → lifecycle) directly, so the handoff is cheap.

Per-project activation

This skill is activated per project with /config-add skill project-diagramming-mermaid (never globally — reduces context bloat). If it's not available in the current project, that's expected; assets activate per project via the pi-config extension.

Related

• project-diagramming-archify — interactive HTML architecture maps (the client-facing output).
• pi-mermaid extension — renders ```mermaid blocks as ASCII in the TUI for quick in-chat preview + parser warnings/errors.
• nixos-workflow skill — how Pi assets are managed (Gitea pi-config, per-machine clones).
• system-architect skill — machine/infra reference for .27/.13/.51 etc.

Obsidian documentation (context, if asked)

These tools (Mermaid, Archify, Vikunja, Outline) are documented as tools in Obsidian: 300 areas/360 Dev-Ops Network Computers/Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline.md, plus Home Network Map Overview.md and Docker Containers.md link to it. Do not recreate diagram versions of the network/container docs.