documd-visuals: An Agent Skill Package for Diagrams and Data Visualizations in Markdown

What documd-visuals solves: routing over raw engine access

AI coding agents can generate diagrams in any number of formats, but without guidance they often pick the wrong engine for the problem, mix styles across a document, or use a diagram type that the target renderer does not support. documd-visuals addresses this by providing a router: a SKILL.md file that maps the reader's intent to one of 31 goal domains and then to the correct engine and example.

The package contains 242 verified examples organized by goal domain, 183 scenarios, 9 color themes, and gate scripts that check theme drift, contrast, block render, block coverage, theme usage, and structure. Every example is checked by scripts/check-all.mjs and scripts/verify-examples.mjs before the package ships. This means the examples in the package are not illustrative placeholders; they are verified outputs.

The README describes the package as organized by what the reader wants rather than by which rendering engine produces it. An agent working on a system architecture diagram does not need to decide between PlantUML and bare HTML; the routing logic in SKILL.md makes that decision based on the goal domain.

The routing mechanism: SKILL.md and goal domains

Every request goes through three steps. SKILL.md matches the intent to one of 31 goal domains, grouped into four meta-clusters: data and metrics (nine domains including service-reliability, ops-monitoring, and product-metrics), process and systems (eight domains including incident-management and software-design), infrastructure and governance (nine domains including cloud-architecture, network-topology, and security-and-compliance), and knowledge and expression (seven domains including planning-and-roadmap and comparison-and-selection).

Once a domain is identified, the corresponding file in goals/ lists the domain's scenarios and example files. The engines/ directory contains per-engine reference documentation and coverage ledgers that show which example goals each engine handles.

The package is self-contained. The README states that every file SKILL.md references is inside the package, enforced by validate-skills.mjs. An agent that installs the skill has everything it needs to route and generate diagrams without fetching additional files from the research/ or scripts/ directories, which are not discovered as skills.

Installing the skill in Claude Code, Codex, and Cursor

The recommended installation method uses the skills CLI:

npx skills add markdown-viewer/skills

This works with multiple AI coding agents, including Claude Code, Codex, and Cursor. The command discovers the documd-visuals package and installs it into the agent's skills directory.

For Claude Code manual installation, copy the skill package directly:

cp -r skills/documd-visuals ~/.claude/skills/

For GitHub Copilot and VS Code, packages are automatically detected when placed in the .github/skills/ directory of a repository. For claude.ai, the SKILL.md content can be added to project knowledge or pasted into the conversation.

The package is confirmed to be exactly one skill. The README notes that `npx skills add ./skills --list` reports exactly one skill: documd-visuals. The research/ and scripts/ directories in the repository root are not skills because they contain no SKILL.md.

The five recommended engines and what they cover

The package recommends five engines for new content:

The plantuml engine (draw-uml 1.5.2 rendering to drawio2svg) covers UML diagrams, ArchiMate, BPMN, process flows, cloud and network architecture, security architecture, and dependency graphs. The README states it has access to 9,514 stencil icons.

The vega and vega-lite engines (versions 6.4.0 and 6.4.3) cover charts that need data transforms, statistical operations, or faceting. The echarts engine (version 6.1.0) handles report-grade charts, dashboards, gauges, and annotated charts. The infographic engine (@antv/infographic 0.2.20) handles template-driven infographics including roadmaps, sequences, and comparisons. Bare HTML is the fifth option, used for system architecture diagrams, cards, memos, and page-level layouts.

The README is explicit: anything other than these five is not recommended. The SKILL.md router includes the excluded engine names only so an agent can recognize and decline requests for them. Previously the repository shipped 14 separate skills organized by engine and domain name. Those were consolidated and rewritten into the current single documd-visuals package.

The documd CLI: a separate tool the skill points at

The skill package handles diagram routing. The documd CLI handles rendering a complete Markdown document to a finished file or a diagram source to an image. The README is explicit that installing the skill does not install the CLI. The Agent Skills format has no install-hook field, and the CLI cannot be triggered during `npx skills add`.

The CLI does not need a local installation to use:

npx @markdown-viewer/documd report.md report.docx

This converts a Markdown document to a .docx file. The CLI also accepts .pdf, .epub, and .html as output formats. For a diagram source file:

npx @markdown-viewer/documd architecture.puml architecture.svg

For repeated use, install the CLI globally to avoid the npx download overhead:

npm install -g @markdown-viewer/documd

The README warns that the bare name `documd` on npm is an unrelated package. Always use `@markdown-viewer/documd` with the full scope to get the correct CLI.

Limitations: no license and the mermaid comparison

The repository lists no license. The prompt confirms this: License is unknown. A package with no license is legally all-rights-reserved by default under most jurisdictions. Teams that need to formally clear intellectual property rights before adopting a dependency cannot use documd-visuals without a clear license statement. This is a real gap for corporate or open-source projects with license policies.

The last push to the repository was on 2026-05-26.

For engineers who need only basic flowcharts, sequence diagrams, or entity-relationship diagrams in documentation that will live on GitHub or GitLab, mermaid is a widely known alternative. mermaid diagrams render natively on GitHub, GitLab, Obsidian, and many Markdown-aware editors without additional tooling or a CLI. Its limitation is a narrower set of supported diagram types compared to the five engines in documd-visuals, particularly for complex infographics, annotated dashboards, or security architecture with standard iconography. The documd-visuals skill earns its place in workflows where those richer diagram types are needed and the docu.md rendering pipeline is already part of the stack.

Editorial conclusion

documd-visuals is the right choice for an AI coding agent workflow where diagrams and data visualizations need to be consistent in style and generated reliably across 31 documented use-case domains. The package has no listed license, which is a real obstacle for teams that need to confirm intellectual property terms before adopting a dependency. Engineers who only need basic flowcharts or sequence diagrams in a Markdown document that renders on GitHub or GitLab may find that mermaid, which requires no additional tooling in those platforms, covers their use case without adopting the docu.md pipeline.

Frequently asked questions

Official sources

1. Issues
2. markdown-viewer/skills on GitHub
3. README