A GitHub skill pack teaches coding agents to draw diagrams inside Markdown files
The markdown-viewer/skills package gives AI coding agents 242 worked examples for text-based diagrams, and it installs with a single command.
The short version
- One installable skill, documd-visuals, covers 31 goal domains, 183 scenarios and 242 verified examples.
- Install with npx skills add markdown-viewer/skills; it works with Claude Code, Codex and Cursor.
- Diagrams are written as text in the Markdown and drawn live by a viewer, not pre-rendered.
- A separate command-line tool, documd, exports documents to DOCX, PDF, EPUB or HTML. It is not installed with the skill.
- The skill content is CC-BY-4.0; the export tool and rendering engines are GPL-3.0-only.
Why it matters
If you keep documentation in Markdown, an agent can now draw architecture or process diagrams as editable text instead of a pasted screenshot. Text diagrams can be reviewed and tracked in version history. The catch is that the agent draws what it believes is true, so you still have to check it.
What the package is
As github.com reported on the project's page, markdown-viewer/skills is a set of instructions for AI coding agents, called skills, that help them produce diagrams inside Markdown documents. Markdown is a plain-text format for writing documentation. Here, a diagram is written as text in the file and drawn by a viewer when you open it.
Everything is bundled into one skill package named documd-visuals. The project says it used to ship 14 separate skills named after engines and domains. Those were folded into this single package and their content was rewritten, not copied. There are no compatibility stubs, so anyone who installed the old skills needs to reinstall.
The package's headline numbers are 242 verified examples, 183 scenarios, 31 goal domains and 5 rendering engines. Every figure takes its colours from one of nine themes.
How an agent finds its way around
The package opens with a router file, SKILL.md, which matches what the user wants to one of the 31 goal domains. The domains sit in four broad clusters: data and metrics, process and systems, infrastructure and governance, and knowledge and expression.
From there, a guide for each domain lists its scenarios and points to example files. Separate reference files cover each rendering engine's limits and common mistakes. The idea is that an agent reads only what the request needs rather than the whole library.
The project also says the package names engines it does not recommend. They are mentioned in the description only so the agent recognises a request for one and can decline it. Third-party names in the docs, such as PlantUML, ECharts, Vega and AntV, are described as references to syntax and icon sets, not endorsements.
Installing it, and the separate export tool
The main route is one command: npx skills add markdown-viewer/skills. The project says this works across several coding agents, including Claude Code, Codex and Cursor. There are manual routes too. For Claude Code you copy the folder into a skills directory. For claude.ai you add the package to project knowledge or paste in the SKILL.md contents. GitHub Copilot and VS Code pick packages up from a .github/skills/ directory.
The skill does not install the documd command-line tool, and the project says the installer cannot do so. That tool is optional. It turns a whole Markdown document into a finished file such as DOCX, PDF, EPUB or HTML, and can turn a diagram source into an SVG or PNG image. The skill documents how to use it, so the agent knows the export path exists.
One warning from the project is worth repeating. Always type the scoped name, @markdown-viewer/documd. The bare name documd on npm belongs to an unrelated package.
Quality checks and licensing
The repository includes scripts that act as gates before changes are accepted. They check that theme files match their source tables, that colours have enough contrast, that every example renders, and that every file in the package can be reached from the router. The project says a failing render or a stale catalog blocks a change.
On licensing, the skill package itself is CC-BY-4.0. You can copy, adapt and redistribute it, including commercially, with credit when you share the package. Using it to write documents requires nothing. The export tool and the rendering engines are separate works under GPL-3.0-only, and installing the skill does not license them.
What to keep in mind
This is a narrow utility, not a breakthrough. It also appeared on Hacker News with one point and no comments, so there is little outside feedback yet. The numbers above come from the project's own description, and we have not run it ourselves.
The usual limits of AI-drawn diagrams apply. A single wrong character can stop a text diagram from rendering. Models tend to handle relationships between things better than tidy layout. And the agent draws what it believes the code does, which may not be what the code actually does. The sensible habit is the same as with any agent output: treat the diagram as a claim and verify it.
What to watch
- Whether the project gains users and outside feedback beyond its first day on Hacker News.
- How well the diagrams hold up on large, messy real-world codebases rather than the bundled examples.
- Whether other agent tools adopt the same skills format so one package works everywhere.
Try it
In a throwaway repository, run npx skills add markdown-viewer/skills. Ask your agent to diagram one module, then ask it to list every claim the diagram makes and check three by hand.
Sources and links
- Reportinggithub.com: the article we sourced
Liked it? Say why
Add a line for other readers.
No account needed. We never show your email. Comments with links, ads or abuse are held and not shown. Your comment shows after a quick check.
Listen to the AI Wire headlines
Listen to the AI WireListen to our daily AI shows every morning: on your commute, in the shower, wherever you are
Listen to the daily showsFirst reported by github.com · Read the original. Written by the SI Agent News Desk from the reporting above.Written with AI from the source above. Every number is checked against the source. Spot a mistake? Corrections.
