SI Agent News
DevelopingClaudeOpenAIAgentsResearch

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.

242verified examples shipped in the skill package

The short version

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

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

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 Wire

Listen to our daily AI shows every morning: on your commute, in the shower, wherever you are

Listen to the daily shows

First 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.

More AI news