# Karvey Diagram

> karvey-diagram

- Skill: `mauricioquezadahaintech/karvey-diagram` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mauricioquezadahaintech/karvey-diagram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mauricioquezadahaintech/karvey-diagram/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: MauricioQuezadaHaintech (https://skillmd.com/u/mauricioquezadahaintech)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mauricioquezadahaintech/karvey-diagram

---


# karvey-diagram

## Purpose

A **cross-cutting** skill of the Karvey Method — it is a **support layer**, NOT a phase. **It does not change `spec.json:phase`** nor advance the method's flow. Its only job is to turn a natural-language description into an **editable and rendered** diagram.

Inspired by gstack's `/diagram`: natural language in, diagram out (mermaid source + editable `.excalidraw` + rendered SVG/PNG). Designed to work **offline-friendly**: if no render tool is available, it degrades cleanly to source-only.

It is especially useful as support for:
- **karvey-architecture** — architecture and data-flow diagrams.
- **docs** in general — any document of the change that needs a diagram.

## When to use it

When the user asks for a diagram: "flow diagram", "architecture diagram", "make me a mermaid", "export this to excalidraw", etc. It can be invoked at any point of the Karvey cycle without altering the phase state.

## Steps

1. **Understand what is to be diagrammed.**
   - Read the user's natural-language description (and the `--type` if passed).
   - If the context lives in the repo (spec, architecture docs, code), use Read/Glob/Grep to understand entities, components, flows and relationships before drawing.
   - Infer the diagram type if not specified: `flow` (flow/process), `sequence` (sequence/interaction), `architecture` (components/data flow), `er` (entity-relationship / data model).

2. **Generate the mermaid source.**
   - Produce the correct mermaid block for the chosen type (`flowchart`, `sequenceDiagram`, `erDiagram`, etc.).
   - Keep names clear and consistent with the change's spec/architecture.
   - This is the minimum guaranteed output — it is always delivered, even if there is no render.

3. **(Optional) Editable `.excalidraw` version.**
   - If the user wants to edit it by hand or present it, also generate an `.excalidraw` file (Excalidraw JSON) equivalent to the diagram.
   - If a mermaid→excalidraw conversion tool is available, use it; if not, build a simple `.excalidraw` with the main nodes and edges.

4. **Render to SVG/PNG if a tool is available (detect; degrade if not).**
   - Detect render tools, in order of preference: `mmdc` (mermaid-cli) → `npx @mermaid-js/mermaid-cli` → equivalent container/local.
   - Check availability before invoking (e.g. `command -v mmdc`). If there is network/tool, render `SVG` (preferred for being vectorial) and/or `PNG`.
   - **Offline-friendly degradation:** if there is no render tool at all, do NOT fail — deliver the mermaid source (and the `.excalidraw` if requested) and explicitly indicate that the render is pending and how to generate it locally.

5. **Save in the correct location.**
   - If the change is active, save in `docs/spec/changes/{change-id}/` (next to the change's spec/docs).
   - If a change-id does not apply, save where the context corresponds (relevant docs/architecture folder).
   - Name descriptively: `<name>.mmd`, `<name>.excalidraw`, `<name>.svg` / `<name>.png`.

## Important

- **It does not advance the phase.** This skill never writes nor modifies `spec.json:phase` nor the state of the Karvey Method. It is pure visualization support.

---
*Part of the Karvey™ Method — © HainTech, by Mauricio Quezada Ibáñez · Apache 2.0 · see `karvey/LICENSE` and `karvey/TRADEMARK.md`.*