Add archify skill (v2.14), pi-mermaid ext (v0.3.0), project-diagramming-mermaid + project-diagramming-archify skills
- skills/archify: vendored tt-a1i/archify 2.14.0 (MIT), pure Node 18+, zero deps - extensions/pi-mermaid: renders mermaid blocks as ASCII in TUI; deps beautiful-mermaid + mermaid - skills/project-diagramming-*: orchestration skills, per-project docs/ convention
This commit is contained in:
96
skills/project-diagramming-mermaid/SKILL.md
Normal file
96
skills/project-diagramming-mermaid/SKILL.md
Normal file
@@ -0,0 +1,96 @@
|
||||
---
|
||||
name: project-diagramming-mermaid
|
||||
description: 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.
|
||||
version: 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:
|
||||
|
||||
```mermaid
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
Reference in New Issue
Block a user