Ask an LLM to "draw our architecture" and you usually get one of two disappointing results: an ASCII sketch, or a wall of brittle Canvas/JavaScript that half-runs. The problem isn't the model — it's the target format.MarkdyScript is diagram-native: a small, line-based, strictly-validated DSL made of semantic nodes, groups, beats, flow operators, and cues. That gives AI agents a stable compile target that is easy to generate, validate, revise, and review in pull requests.

Why diagram-native text is the right AI target

Small grammar. Nodes, groups, beats, cues, and four flow operators — a model can learn it from one canonical reference page.
Deterministic. The same text always renders the same diagram, so results are reproducible and diffable.
Content-Adaptive Sizing. The model never needs to guess pixel coordinates, manual offsets, or canvas resolutions — Markdy automatically derives the optimal aspect ratio and dimensions from the generated items.
Line-numbered errors. When the model gets something wrong, the parser points at the exact line, so the agent can self-correct.
No runtime to hallucinate. There's no imperative API surface to invent — just declarative diagram statements.

How to prompt for a Markdy diagram

Point the model at the canonical Markdy agent guide(grammar, node kinds, examples), then describe the system in plain English. The model should fetch the guide before writing code, use the current syntax rather than model memory, and output one complete .markdy scene:

Follow https://markdy.com/AGENT.md and write one complete MarkdyScript scene. I want to explain a URL shortener to my engineering team: first a user creates a short link, then someone opens that short link and gets redirected. Include the API, URL service, Redis cache, and database. Make it clear enough for a short demo.

You get back a complete, runnable scene:

scene theme=paper
layout LR

browser Browser
gateway Gateway "API Gateway"
service Shortener "URL Shortener"
cache Redis "Hot URL Cache"
database UrlDB "URL Store"

group storage: Redis UrlDB

beat create:
  Browser -> Gateway "POST /shorten" -> Shortener
  Shortener -> UrlDB "store slug" & Shortener ~> Redis "warm cache"
  Browser <- Shortener "short.ly/a7"

beat finish:
  glow storage color=#22c55e

Paste it straight into the playground to verify it. If it doesn't parse, hand the line-numbered error back to the model and ask it to fix that line — the loop is fast and reliable.

Works with the tools you already use

MarkdyScript is plain text, so it works with any assistant that accepts URL context — Claude, ChatGPT, Gemini, GitHub Copilot, Cursor, Windsurf, and coding agents that read llms.txt. Keep the diagram in your repo and the same agent can update it whenever the system changes, exactly likediagrams as code.

Validate what the AI produced

Trust, but verify. Run markdy lint scene.markdy in CI, or render the scene inAstro or MDX docs so a broken diagram fails your build instead of shipping. Deterministic output means AI-generated diagrams stay reviewable — not magic you can't audit.