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 Service"
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, Google Antigravity, and coding agents that read llms.txt. You can also plug in the official Model Context Protocol (MCP) server (@markdy/mcp-server) for instant syntax diagnostics, fuzzy typo healing (diagnose_markdy_syntax / fix_markdy_code), and proactive IntelliCode completions (get_intellicode_completions).
Validate what the AI produced
Trust, but verify. Run markdy lint scene.markdy in CI, auto-heal drafts with markdy fmt --fix, or explore predictive suggestions via markdy suggest. Rendering scenes inAstro or MDX docs ensures broken diagrams fail your build instead of shipping. Deterministic output means AI-generated diagrams stay reviewable — not magic you can't audit.