{"slug": "skills-for-ai-coding-agents-to-create-diagrams-in-markdown", "title": "Skills for AI coding agents to create diagrams in Markdown", "summary": "A skill package called documd-visuals has been published for AI coding agents including Claude Code, Codex and Cursor, installable via `npx skills add markdown-viewer/skills` or by copying it into `~/.claude/skills/`, that lets agents generate diagrams in Markdown. The package ships 242 verified examples across 183 scenarios, 31 goal domains and 5 rendering engines, with every figure coloured from one of nine themes defined in `styles/` and generated from a source table. Repo-level gates `scripts/check-all.mjs` (theme drift, contrast, block render, block coverage, theme usage, structure) and `scripts/verify-examples.mjs` enforce the examples, and the package is self-contained so it never cites the repo-only `research/` and `scripts/` directories.", "body_md": "Agent skills for the [docu.md](https://docu.md) Markdown pipeline. One skill package, organised by **what\nthe reader wants**, with the rendering engines behind it as implementation references.\n\n**242 verified examples · 183 scenarios · 31 goal domains · 5 engines**, every figure coloured from one of\n**nine themes** defined in `styles/` and generated from a source table, gated by `scripts/check-all.mjs`\n(theme drift · contrast · block render · block coverage · theme usage · structure) plus\n`scripts/verify-examples.mjs` for the full render pass.\n\nSkills follow the [Agent Skills](https://agentskills.io/) format.\n\n**[🚀 Installation](#-installation)** • **[🧩 The Package](#-the-package)** • **[⚙️ Engines](#-engines)** • **[�️ The `documd` CLI](#-the-documd-cli)** • **[�🔀 Migrated Skills](#-migrated-skills)** • [🔗 Links](#-links)\n\n```\nnpx skills add markdown-viewer/skills\n```\n\nThis method works with multiple AI coding agents (Claude Code, Codex, Cursor, etc.) and discovers the\n`documd-visuals` package.\n\n**For Claude Code (Manual)**\n\n```\ncp -r skills/documd-visuals ~/.claude/skills/\n```\n\n**For claude.ai**\n\nAdd the package to project knowledge or paste `SKILL.md` contents into the conversation.\n\n**For GitHub Copilot / VS Code**\n\nPackages are automatically detected when placed in `.github/skills/` directory.\n\n```\nskills/\n├── documd-visuals/        ← the skill package — the only skill here, and the only thing installed\n│   ├── SKILL.md           ← router: iron rules, 31 goals, capability boundaries\n│   ├── converting.md      ← the documd CLI: install, formats, flags, what survives an export\n│   ├── catalog/           ← every scenario: domain, engines, tier, example files\n│   ├── goals/             ← one guide per goal domain\n│   ├── engines/           ← per-engine reference + coverage/ ledgers (units, then examples by goal)\n│   ├── examples/          ← 242 verified examples, grouped by goal domain\n│   └── styles/            ← palette.md (the contract) + themes/<theme>.md (values + a block per engine)\n├── research/              ← engine dossiers: coverage ledgers + verification notes (repo-only, never shipped)\n└── scripts/               ← repo-level gates (not shipped)\n```\n\nThe package is self-contained: it never cites `research/` or `scripts/`, and the gate fails the build if\nit does. If you install the package, everything it references is inside it — and every file inside it is\nreachable from `SKILL.md`, which `validate-skills.mjs` enforces. The one exception is `LICENSE.md`: a legal\nattachment is not routing content, so it ships with the package without being linked from the router.\n\n`research/` and `scripts/` are **not discovered as skills**: the CLI finds a skill by locating a\n`SKILL.md`, and neither directory contains one. Verified — `npx skills add ./skills --list` reports\nexactly one skill, `documd-visuals`.\n\n1. `SKILL.md` matches the reader's intent to one of**31 goal domains** , grouped into four meta-clusters:\ndata & metrics · process & systems · infrastructure & governance · knowledge & expression.\n2. `goals/<domain>.md` lists that domain's scenarios with the example files that implement them.\n3. `engines/<engine>.md` covers the chosen engine's limits and anti-patterns.\n\n| Meta cluster | Domains | \n|---|---|\n| A — data & metrics | service-reliability · ops-monitoring · delivery-throughput · goal-and-status-reporting · product-metrics · business-reporting · go-to-market · cost-and-budget · data-exploration | \n| B — process & systems | engineering-operations · incident-management · process-and-workflow · software-design · software-behaviour · dependencies-and-relations · system-architecture | \n| C — infrastructure & governance | cloud-architecture · data-platform · network-topology · security-and-compliance · enterprise-architecture · organization-and-roles · people-and-hiring | \n| D — knowledge & expression | knowledge-and-outline · planning-and-roadmap · migration-and-rollout · comparison-and-selection · internal-documents · catalogues-and-inventories · customer-and-partner-comms | \n\n**Recommended — write new content with these**\n\n| Fence | Engine | Use it for | \n|---|---|---|\n| `plantuml` /`puml` | draw-uml 1.5.2 → drawio2svg | UML, ArchiMate, BPMN, process, cloud/network/security architecture, dependency graphs, 9,514 stencil icons | \n| `vega` /`vega-lite` | vega 6.4.0 / vega-lite 6.4.3 | charts that need data transforms, faceting, statistics | \n| `echarts` | echarts 6.1.0 | report-grade charts, dashboards, gauges, annotations | \n| `infographic` | @antv/infographic 0.2.20 | template-driven infographics: roadmaps, sequences, comparisons | \n| (bare HTML) | built in | system architecture diagrams, cards, memos and page-level layouts | \n\n**Anything else is not recommended.** The package documents no other engine, and new content uses the\nfive above; the one place the excluded names are listed is the `SKILL.md` description, so an agent\nrecognises them when a user asks for one and can say no.\n\nThis package draws figures **as text in the Markdown**, rendered live by the viewer — an author never\npre-renders anything. The **`documd` CLI** is the optional export half: it renders a whole Markdown\ndocument to a finished file, and a diagram source to an image. It is documented inside the package —\n`documd-visuals/converting.md`, linked from `SKILL.md` — so an agent that installs the skill knows the\nexport path exists.\n\n**Installing the skill does not install the CLI, and the installer cannot be made to.** `npx skills add`\ncopies or symlinks files into an agent's skills directory; the Agent Skills format has no install-hook\nfield, and the CLI runs no scripts of its own during `add`. There is no point at which a skill package\ncould trigger `npm install`. Treat the CLI as a separate tool that the skill points at.\n\nNothing has to be installed to use it:\n\n```\nnpx @markdown-viewer/documd report.md report.docx                 # also .pdf .epub .html\nnpx @markdown-viewer/documd architecture.puml architecture.svg    # also .png\n```\n\nInstall it once if the same command runs repeatedly — this provides the `documd` binary:\n\n```\nnpm install -g @markdown-viewer/documd\n```\n\n**Use the scope.** The bare name `documd` on npm is an unrelated package (\"markdown object\nnotation\"). `npx documd` fetches that one, not this CLI. Always write `@markdown-viewer/documd`.\n\n⚠️ \n\nThe npm release carries the same version as the extension, so a `npx` run is the build documented here.\n\nThis repository used to ship 14 engine- and domain-named skills. They are now one package, and their content\nwas **rewritten, not copied**:\n\n| Old skill | New home | \n|---|---|\n| `uml` | `engines/plantuml.md` ,`engines/plantuml-stencils/` ,`examples/software-design/` ,`examples/software-behaviour/` | \n| `cloud` ·`network` ·`security` ·`iot` ·`data-analytics` | `examples/cloud-architecture/` ,`network-topology/` ,`security-and-compliance/` ,`data-platform/` | \n| `archimate` ·`bpmn` ·`mindmap` | `examples/enterprise-architecture/` ,`process-and-workflow/` ,`knowledge-and-outline/` | \n| `vega` ·`graphviz` ·`infographic` | `engines/vega.md` ,`engines/infographic.md` — the graph examples were re-authored as`plantuml` rectangles | \n| `architecture` ·`infocard` | `engines/html-css.md` (rules, the seven architecture shapes, page skeletons, connectors); the layout set was recovered into`examples/system-architecture/` , and the card prototypes became`examples/internal-documents/` ,`catalogues-and-inventories/` ,`customer-and-partner-comms/` ; the rest of the 90-file design library was triaged out | \n\nThere are no compatibility stubs: the CLI discovers a skill by locating a `SKILL.md`, so a stub directory\nwould be ignored rather than installed — and would only add a dead directory to the repository. Reinstall\nto get the new package.\n\n```\nnode scripts/check-all.mjs                                           # every theme gate at once\nnode scripts/validate-skills.mjs                                     # layout, budgets, catalog, fences, language, theme reachability\nnode scripts/build-themes.mjs --check                                 # theme files match the source tables\nnode scripts/build-catalog.mjs --check                               # catalog ↔ filesystem consistency\nnode scripts/build-goals.mjs --check                                  # goal docs match the catalog\nnode scripts/sync-engine-indexes.mjs --check                          # shipped template index matches the installed engine\nnode scripts/build-coverage.mjs --check                               # coverage ledgers match the catalog\nnode scripts/verify-examples.mjs --dir documd-visuals/examples --all  # render every example\n```\n\n`check-all.mjs` runs the theme gates — drift (`build-themes.mjs --check`), contrast\n(`check-palette-contrast.mjs`, per theme), block render (` verify-blocks.mjs`), block coverage\n(`apply-block.mjs --all --check`), off-theme literals (` check-palette-usage.mjs --strict`) — and\n`validate-skills.mjs`, which also enforces that `styles/palette.md` and every `styles/themes/*.md`\nstay reachable from `SKILL.md`, the goal docs and the engine references; add `--with-examples` for\nthe full render pass. All must exit 0.\n`build-themes.mjs` regenerates `documd-visuals/styles/themes/*.md` from `scripts/themes.json` —\n**edit the JSON, not the generated theme files**.\n`build-catalog.mjs` and `build-goals.mjs` regenerate\n`documd-visuals/catalog/scenarios.{json,md}` and `documd-visuals/goals/*.md` from\n`documd-visuals/catalog/scenarios.tsv` — **edit the TSV, not the generated files**.\n\n| File | Budget | \n|---|---|\n| `documd-visuals/SKILL.md` | 300 lines / 12 KB body (frontmatter description: 1024 characters — the Agent Skills limit) | \n| `goals/*.md` | 200 lines | \n| `engines/*.md` | 300 lines (generated `plantuml-stencils/` exempt) | \n| `examples/**/*.md` | 120 lines target, 200 hard limit (verbose Vega specs) | \n| `engines/coverage/*.md` | 330 lines (generated: curated unit tables + every example grouped by goal) | \n\n1. Write `documd-visuals/examples/<domain>/<scenario>.md` in the standard shape:*Best for / Avoid when / Answers* → the fenced block →*Data Shape / Key Options / Pitfalls /\nAlternatives* → a`<!-- source: … -->` line.\n2. Add a row to `catalog/scenarios.tsv` :`domain <TAB> scenario <TAB> engine <TAB> file` .\n3. `node scripts/build-catalog.mjs --apply && node scripts/build-goals.mjs` .\n4. `node scripts/verify-examples.mjs --dir documd-visuals/examples --all` .\n\n| Engine | Fence | Output | \n|---|---|---|\n| PlantUML (draw-uml) | ```` ``` plantuml ```` /```` ``` puml ```` | SVG | \n| Vega-Lite / Vega | ```` ``` vega-lite ```` /```` ``` vega ```` | PNG | \n| ECharts | ```` ``` echarts ```` | PNG | \n| Infographic | ```` ``` infographic ```` | PNG | \n| HTML/CSS | (no fence, raw HTML) | HTML | \n\n- [Markdown Viewer Extension](https://docu.md) - The rendering engine behind these skills\n- [Agent Skills Format](https://agentskills.io/) - Standard format for AI agent skills\n- [Chrome Extension](https://chromewebstore.google.com/detail/markdown-viewer/jekhhoflgcfoikceikgeenibinpojaoi) - Install for Chrome and Chromium browsers\n- [Edge Extension](https://microsoftedge.microsoft.com/addons/detail/documd-markdown-viewer/iphmkjlbnogmhofmmcahdhodiilokfca) - Install from Microsoft Edge Add-ons\n- [Firefox Add-on](https://addons.mozilla.org/firefox/addon/markdown-viewer-extension/) - Install for Firefox\n- [Obsidian Plugin](https://community.obsidian.md/plugins/markdown-viewer-extension) - Install from the Obsidian community directory\n- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=xicilion.markdown-viewer-extension) - Install for VS Code\n\nContribute to the single package, not to new engine-named skills:\n\n1. Find the goal domain your example belongs to in `documd-visuals/catalog/scenarios.tsv` (or open`SKILL.md` to see the router). If no domain fits, propose one — domains hold 3–8 scenarios.\n2. Write the example and register it in the TSV (see *Adding an example* above).\n3. Run all four gates; a failing render or a stale catalog blocks the change.\n4. Keep statements traceable: every example ends with `<!-- source: … -->` pointing at the engine docs.\n\n**The skill package (`documd-visuals/`) is [CC-BY-4.0](https://github.com/markdown-viewer/skills/blob/main/LICENSE)** — use it, copy it, adapt it and\nredistribute it, including commercially and including the examples, with attribution. The same text ships\ninside the package as [`documd-visuals/LICENSE.md`](https://github.com/markdown-viewer/skills/blob/main/documd-visuals/LICENSE.md), so an installed copy\ncarries its own terms. The grant covers the whole repository, including the repo-only tooling in\n`scripts/` and the dossiers in `research/` — neither directory is shipped or discovered as a skill.\n\n**The `documd` CLI and the rendering engines are separate works under GPL-3.0-only.**\n`@markdown-viewer/documd`, `@markdown-viewer/draw-uml` and `@markdown-viewer/drawio2svg` are not part of\nthis package and are not covered by the CC-BY-4.0 grant above; installing the skill does not license them.\n\n**Attribution, in practice.** CC-BY-4.0 asks for it when you share the package, and only then. Vendor it and\nkeep `LICENSE.md` beside it, or put one credit line in your project's notices — both satisfy it. Writing\ndocuments *with* the skill, and documents that stay inside your organisation, require nothing at all. Never a\nper-figure credit. Full detail: [`documd-visuals/LICENSE.md`](https://github.com/markdown-viewer/skills/blob/main/documd-visuals/LICENSE.md).\n\n**Third-party names** used throughout this package — PlantUML, AWS, Azure, Cisco, ArchiMate, ECharts,\nVega, AntV and others — are the trademarks of their respective owners, referenced only to describe the\nsyntax and icon sets this package documents. No trademark rights are granted.", "url": "https://wpnews.pro/news/skills-for-ai-coding-agents-to-create-diagrams-in-markdown", "canonical_source": "https://github.com/markdown-viewer/skills", "published_at": "2026-11-16 06:27:50+00:00", "updated_at": "2026-11-16 06:53:00.196222+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["documd-visuals", "Claude Code", "Codex", "Cursor", "GitHub Copilot", "VS Code", "claude.ai"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/skills-for-ai-coding-agents-to-create-diagrams-in-markdown", "markdown": "https://wpnews.pro/news/skills-for-ai-coding-agents-to-create-diagrams-in-markdown.md", "text": "https://wpnews.pro/news/skills-for-ai-coding-agents-to-create-diagrams-in-markdown.txt", "jsonld": "https://wpnews.pro/news/skills-for-ai-coding-agents-to-create-diagrams-in-markdown.jsonld"}}