# Monodraw LLM

> Draw a diagram as a real editable Monodraw document, not a picture. Use for draw me a diagram of this, sketch this architecture in ASCII, turn this ASCII or text diagram into a real diagram, recreate this screenshot as a diagram, recreate or debug a `.monopic` or `.monojson` file. Boxes become draggable frames, arrows become attached connectors. Use it even when Monodraw is never named. Not for charts or plots, which are dataviz; not for a diagram drawn inside a web artifact, which is artifact-diagramming; not for UI mockups or wireframes, which is design.

- Skill: `p404/monodraw-llm` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add p404/monodraw-llm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/p404/monodraw-llm/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: p404 (https://skillmd.com/u/p404)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/p404/monodraw-llm

---


# Monodraw LLM

Generate Monodraw v5 object graphs with editable frames, containers, text, shadows, borders, connectors, free endpoints, and line-pinned labels. Emit both native `.monopic` and inspectable `.monojson` files.

## Request to command

| You are asked | Do this |
|---|---|
| draw me a diagram of this, sketch this architecture | draft an ASCII preview when useful, write a compact spec JSON, then `"$CLI" generate spec.json -o out.monopic` and `"$CLI" validate out.monopic` |
| turn this ASCII or text diagram into a real diagram | treat the sketch as the blueprint, map boxes to nodes/groups and arrows to edges, keep its layout, then generate. See "Convert an ASCII sketch" |
| recreate this screenshot as a diagram | write explicit `position`, `width`, `height` and styles read off the image, generate, open in Monodraw, iterate from a fresh screenshot |
| recreate this `.monopic` or legacy v3 file 1:1 | `"$CLI" extract-spec source.monopic -o source.spec.json`, regenerate, then diff the renderer output. See "Recreate an existing document 1:1" |
| what is in this file, why does it look wrong | `"$CLI" inspect diagram.monopic`, then `unpack` and `validate`, before editing anything |
| convert between the two formats | `"$CLI" unpack diagram.monopic diagram.monojson` and `"$CLI" pack diagram.monojson diagram.monopic` |
| check a folder of documents still round-trips | `"$CLI" regress path/to/files -o regression-output`, then report the exact-render result or the remaining diffs |

Hand the task back if what is wanted is a chart or plot (`dataviz`), a diagram drawn inside a
web artifact or page (`artifact-diagramming`), or a UI mockup or wireframe (`design`). The only
thing this skill produces is a Monodraw document.

Resolve the directory containing this `SKILL.md` as `SKILL_DIR`. Claude Code exposes it as `${CLAUDE_SKILL_DIR}`; in Codex, use the discovered skill path. Then use the bundled wrapper:

```bash
CLI="$SKILL_DIR/scripts/monodraw-llm"
```

The wrapper runs the source checkout it sits inside, otherwise an installed `monodraw-llm` on
`PATH`. With neither it exits 127 and prints the `python3 -m pip install -e .` instruction. Do
that and retry; do not fall back to hand-writing `.monopic` bytes.

## Convert an ASCII sketch to editable Monodraw

When the user asks for an ASCII diagram and a Monodraw export, use this two-stage workflow:

1. Draft or refine the text diagram in the conversation. If the user already supplied one, use it as the design contract.
2. Map every box to a `node` or `group`; map nested boundaries to parent/child groups.
3. Map arrows and lines to `edges`, including direction, attachment sides, labels, dashed styles, and deliberately free endpoints.
4. Preserve horizontal/vertical ordering and whitespace relationships with explicit `position`, `width`, and `height` values when layout fidelity matters.
5. For a label that must move with its connector, add a `line_positions` entry plus a node or annotation with a matching `pin`. An edge `label` alone creates an editable but absolutely positioned midpoint label.
6. Generate, validate, and open or render the result when Monodraw is available.

Do not paste the full ASCII drawing into one Monodraw text frame. The goal is a diagram made from separate editable native objects. The LLM performs the semantic translation; the CLI performs deterministic serialization.

## Create a new editable diagram

1. Read `references/spec.md` before writing a non-trivial spec.
2. Use concise multiline labels and stable semantic IDs.
3. Represent visual boundaries as `groups`; represent components as `nodes`.
4. Attach edges to frame sides. Use free points only when a connector deliberately ends in open space.
5. Use explicit positions for screenshot fidelity. Use ranks/automatic layout for a new architecture.
6. Generate and validate:

```bash
"$CLI" generate diagram.json -o diagram.monopic
"$CLI" validate diagram.monopic
open -a Monodraw diagram.monopic
```

The generate command writes the `.monopic` plus a readable `.monojson` sibling unless `--monopic-only` is passed.

Use `assets/multi-region-checkout.json` as the primary complex authored example. It exercises nested regions, service and data tiers, shadows, routed incident paths, and pinned labels. For a 1:1 example, extract any existing `.monopic` and preserve the resulting explicit geometry and z-order.

## Recreate an existing document 1:1

Extract a source spec instead of manually reverse-engineering its internal IDs:

```bash
"$CLI" extract-spec source.monopic -o source.spec.json
"$CLI" generate source.spec.json -o recreated.monopic
monodraw -u -w source.monopic > original.txt
monodraw -u -w recreated.monopic > recreated.txt
diff -u original.txt recreated.txt
```

Preserve these fields when editing an extracted spec:

- `position`, `width`, and `height` for exact geometry.
- Separate `name` and `label` values when both exist.
- `z_order`, which Monodraw interprets front-to-back.
- `line_positions` and frame `pin` records for labels that follow connectors.
- Explicit connector sides, arrows, free points, line style, and origin.

Do not claim 1:1 fidelity from structural validation alone. Require no renderer diff, or use screenshots when the installed renderer is unavailable.

## Run corpus regression

Use Monodraw's renderer as the authoritative visual oracle:

```bash
"$CLI" regress path/to/files -o regression-output
```

The output contains, per case, the extracted spec, fresh v5 files, original/generated Unicode renders, and a unified diff. It also writes `report.json` and `report.md`.

Pass `--open-failures` only when visual inspection is useful; avoid opening every passing document.

## Inspect and convert

```bash
"$CLI" inspect diagram.monopic
"$CLI" unpack diagram.monopic diagram.monojson
"$CLI" pack diagram.monojson diagram.monopic
"$CLI" validate diagram.monopic diagram.monojson
```

Use `--force` with `pack` only after deliberately accepting validation errors.

## Preserve native editability

- Emit type-20 frames and type-5 connectors, not a raster image or one flattened text block.
- Keep connector endpoints attached to frame side records so dragging/resizing remains useful.
- Use type-24 line positions for pinned labels so labels move with their connectors.
- Place outer containers last in default `z_order`; otherwise they mask their contents.
- Retain the `.monojson` sibling as the reviewable source when practical.
- Re-open the final `.monopic` in Monodraw after any format-level change.

## Load references selectively

- Read `references/spec.md` to author or modify diagram specs.
- Read `references/format.md` when diagnosing serialization, object references, legacy v3 behavior, z-order, or pinned-label problems.