Skip to content
Back to search

skills

SkillWorks with Claude CodeGitHub

Opinionated skills for AI coding agents to create stunning diagrams and visualizations directly in Markdown. These skills extend agent capabilities across diagram generation, data visualization, and technical documentation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/markdown-viewer-skills/badge.svg)](/listings/markdown-viewer-skills)

HTML

<a href="/listings/markdown-viewer-skills"><img src="/api/listings/markdown-viewer-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Quick Install (Recommended)

npx skills add markdown-viewer/skills

This method works with multiple AI coding agents (Claude Code, Codex, Cursor, etc.) and discovers the `documd-visuals` package.

Manual Installation

**For Claude Code (Manual)**

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

**For claude.ai**

Add the package to project knowledge or paste `SKILL.md` contents into the conversation.

**For GitHub Copilot / VS Code**

Packages are automatically detected when placed in `.github/skills/` directory.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 257 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # docu.md skills
  2. Agent skills for the [docu.md](https://docu.md) Markdown pipeline. One skill package, organised by **what
  3. the reader wants**, with the rendering engines behind it as implementation references.
  4. **242 verified examples · 183 scenarios · 31 goal domains · 5 engines**, every figure coloured from one of
  5. **nine themes** defined in `styles/` and generated from a source table, gated by `scripts/check-all.mjs`
  6. (theme drift · contrast · block render · block coverage · theme usage · structure) plus
  7. `scripts/verify-examples.mjs` for the full render pass.
  8. Skills follow the [Agent Skills](https://agentskills.io/) format.
  9. ---
  10. ## 🧭 Quick Navigation
  11. **[🚀 Installation](#-installation)** • **[🧩 The Package](#-the-package)** • **[⚙️ Engines](#-engines)** • **[�️ The `documd` CLI](#-the-documd-cli)** • **[�🔀 Migrated Skills](#-migrated-skills)** • **[🔗 Links](#-links)**
  12. ---
  13. ## 🚀 Installation
  14. ### Quick Install (Recommended)
  15. ```bash
  16. npx skills add markdown-viewer/skills
  17. ```
  18. This method works with multiple AI coding agents (Claude Code, Codex, Cursor, etc.) and discovers the
  19. `documd-visuals` package.
  20. ### Manual Installation
  21. **For Claude Code (Manual)**
  22. ```bash
  23. cp -r skills/documd-visuals ~/.claude/skills/
  24. ```
  25. **For claude.ai**
  26. Add the package to project knowledge or paste `SKILL.md` contents into the conversation.
  27. **For GitHub Copilot / VS Code**
  28. Packages are automatically detected when placed in `.github/skills/` directory.
  29. ---
  30. ## 🧩 The Package
  31. ```
  32. skills/
  33. ├── documd-visuals/ ← the skill package — the only skill here, and the only thing installed
  34. │ ├── SKILL.md ← router: iron rules, 31 goals, capability boundaries
  35. │ ├── converting.md ← the documd CLI: install, formats, flags, what survives an export
  36. │ ├── catalog/ ← every scenario: domain, engines, tier, example files
  37. │ ├── goals/ ← one guide per goal domain
  38. │ ├── engines/ ← per-engine reference + coverage/ ledgers (units, then examples by goal)
  39. │ ├── examples/ ← 242 verified examples, grouped by goal domain
  40. │ └── styles/ ← palette.md (the contract) + themes/<theme>.md (values + a block per engine)
  41. ├── research/ ← engine dossiers: coverage ledgers + verification notes (repo-only, never shipped)
  42. └── scripts/ ← repo-level gates (not shipped)
  43. ```
  44. The package is self-contained: it never cites `research/` or `scripts/`, and the gate fails the build if
  45. it does. If you install the package, everything it references is inside it — and every file inside it is
  46. reachable from `SKILL.md`, which `validate-skills.mjs` enforces. The one exception is `LICENSE.md`: a legal
  47. attachment is not routing content, so it ships with the package without being linked from the router.
  48. `research/` and `scripts/` are **not discovered as skills**: the CLI finds a skill by locating a
  49. `SKILL.md`, and neither directory contains one. Verified — `npx skills add ./skills --list` reports
  50. exactly one skill, `documd-visuals`.
  51. ### How a request is routed
  52. 1. `SKILL.md` matches the reader's intent to one of **31 goal domains**, grouped into four meta-clusters:
  53. data & metrics · process & systems · infrastructure & governance · knowledge & expression.
  54. 2. `goals/<domain>.md` lists that domain's scenarios with the example files that implement them.
  55. 3. `engines/<engine>.md` covers the chosen engine's limits and anti-patterns.
  56. ### Goal domains
  57. | Meta cluster | Domains |
  58. |---|---|
  59. | 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 |
  60. | B — process & systems | engineering-operations · incident-management · process-and-workflow · software-design · software-behaviour · dependencies-and-relations · system-architecture |
  61. | C — infrastructure & governance | cloud-architecture · data-platform · network-topology · security-and-compliance · enterprise-architecture · organization-and-roles · people-and-hiring |
  62. | D — knowledge & expression | knowledge-and-outline · planning-and-roadmap · migration-and-rollout · comparison-and-selection · internal-documents · catalogues-and-inventories · customer-and-partner-comms |
  63. ## ⚙️ Engines
  64. **Recommended — write new content with these**
  65. | Fence | Engine | Use it for |
  66. |---|---|---|
  67. | `plantuml` / `puml` | draw-uml 1.5.2 → drawio2svg | UML, ArchiMate, BPMN, process, cloud/network/security architecture, dependency graphs, 9,514 stencil icons |
  68. | `vega` / `vega-lite` | vega 6.4.0 / vega-lite 6.4.3 | charts that need data transforms, faceting, statistics |
  69. | `echarts` | echarts 6.1.0 | report-grade charts, dashboards, gauges, annotations |
  70. | `infographic` | @antv/infographic 0.2.20 | template-driven infographics: roadmaps, sequences, comparisons |
  71. | (bare HTML) | built in | system architecture diagrams, cards, memos and page-level layouts |
  72. **Anything else is not recommended.** The package documents no other engine, and new content uses the
  73. five above; the one place the excluded names are listed is the `SKILL.md` description, so an agent
  74. recognises them when a user asks for one and can say no.
  75. ## 🛠️ The `documd` CLI
  76. This package draws figures **as text in the Markdown**, rendered live by the viewer — an author never
  77. pre-renders anything. The **`documd` CLI** is the optional export half: it renders a whole Markdown
  78. document to a finished file, and a diagram source to an image. It is documented inside the package —
  79. `documd-visuals/converting.md`, linked from `SKILL.md` — so an agent that installs the skill knows the
  80. export path exists.
  81. **Installing the skill does not install the CLI, and the installer cannot be made to.** `npx skills add`
  82. copies or symlinks files into an agent's skills directory; the Agent Skills format has no install-hook
  83. field, and the CLI runs no scripts of its own during `add`. There is no point at which a skill package
  84. could trigger `npm install`. Treat the CLI as a separate tool that the skill points at.
  85. Nothing has to be installed to use it:
  86. ```bash
  87. npx @markdown-viewer/documd report.md report.docx # also .pdf .epub .html
  88. npx @markdown-viewer/documd architecture.puml architecture.svg # also .png
  89. ```
  90. Install it once if the same command runs repeatedly — this provides the `documd` binary:
  91. ```bash
  92. npm install -g @markdown-viewer/documd
  93. ```
  94. > ⚠️ **Use the scope.** The bare name `documd` on npm is an unrelated package ("markdown object
  95. > notation"). `npx documd` fetches that one, not this CLI. Always write `@markdown-viewer/documd`.
  96. The npm release carries the same version as the extension, so a `npx` run is the build documented here.
  97. ## 🔀 Migrated Skills
  98. This repository used to ship 14 engine- and domain-named skills. They are now one package, and their content
  99. was **rewritten, not copied**:
  100. | Old skill | New home |
  101. |---|---|
  102. | `uml` | `engines/plantuml.md`, `engines/plantuml-stencils/`, `examples/software-design/`, `examples/software-behaviour/` |
  103. | `cloud` · `network` · `security` · `iot` · `data-analytics` | `examples/cloud-architecture/`, `network-topology/`, `security-and-compliance/`, `data-platform/` |
  104. | `archimate` · `bpmn` · `mindmap` | `examples/enterprise-architecture/`, `process-and-workflow/`, `knowledge-and-outline/` |
  105. | `vega` · `graphviz` · `infographic` | `engines/vega.md`, `engines/infographic.md` — the graph examples were re-authored as `plantuml` rectangles |
  106. | `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 |
  107. There are no compatibility stubs: the CLI discovers a skill by locating a `SKILL.md`, so a stub directory
  108. would be ignored rather than installed — and would only add a dead directory to the repository. Reinstall
  109. to get the new package.
  110. ---
  111. ## 📖 Package Development
  112. ### Gates
  113. ```bash
  114. node scripts/check-all.mjs # every theme gate at once
  115. node scripts/validate-skills.mjs # layout, budgets, catalog, fences, language, theme reachability
  116. node scripts/build-themes.mjs --check # theme files match the source tables
  117. node scripts/build-catalog.mjs --check # catalog ↔ filesystem consistency
  118. node scripts/build-goals.mjs --check # goal docs match the catalog
  119. node scripts/sync-engine-indexes.mjs --check # shipped template index matches the installed engine
  120. node scripts/build-coverage.mjs --check # coverage ledgers match the catalog
  121. node scripts/verify-examples.mjs --dir documd-visuals/examples --all # render every example
  122. ```
  123. `check-all.mjs` runs the theme gates — drift (`build-themes.mjs --check`), contrast
  124. (`check-palette-contrast.mjs`, per theme), block render (`verify-blocks.mjs`), block coverage
  125. (`apply-block.mjs --all --check`), off-theme literals (`check-palette-usage.mjs --strict`) — and
  126. `validate-skills.mjs`, which also enforces that `styles/palette.md` and every `styles/themes/*.md`
  127. stay reachable from `SKILL.md`, the goal docs and the engine references; add `--with-examples` for
  128. the full render pass. All must exit 0.
  129. `build-themes.mjs` regenerates `documd-visuals/styles/themes/*.md` from `scripts/themes.json` —
  130. **edit the JSON, not the generated theme files**.
  131. `build-catalog.mjs` and `build-goals.mjs` regenerate
  132. `documd-visuals/catalog/scenarios.{json,md}` and `documd-visuals/goals/*.md` from
  133. `documd-visuals/catalog/scenarios.tsv` — **edit the TSV, not the generated files**.
  134. ### Budgets
  135. | File | Budget |
  136. |---|---|
  137. | `documd-visuals/SKILL.md` | 300 lines / 12 KB body (frontmatter description: 1024 characters — the Agent Skills limit) |
  138. | `goals/*.md` | 200 lines |
  139. | `engines/*.md` | 300 lines (generated `plantuml-stencils/` exempt) |
  140. | `examples/**/*.md` | 120 lines target, 200 hard limit (verbose Vega specs) |
  141. | `engines/coverage/*.md` | 330 lines (generated: curated unit tables + every example grouped by goal) |
  142. ### Adding an example
  143. 1. Write `documd-visuals/examples/<domain>/<scenario>.md` in the standard shape:
  144. *Best for / Avoid when / Answers* → the fenced block → *Data Shape / Key Options / Pitfalls /
  145. Alternatives* → a `<!-- source: … -->` line.
  146. 2. Add a row to `catalog/scenarios.tsv`: `domain <TAB> scenario <TAB> engine <TAB> file`.
  147. 3. `node scripts/build-catalog.mjs --apply && node scripts/build-goals.mjs`.
  148. 4. `node scripts/verify-examples.mjs --dir documd-visuals/examples --all`.
  149. ### Code fence reference
  150. | Engine | Fence | Output |
  151. |---|---|---|
  152. | PlantUML (draw-uml) | ` ```plantuml ` / ` ```puml ` | SVG |
  153. | Vega-Lite / Vega | ` ```vega-lite ` / ` ```vega ` | PNG |
  154. | ECharts | ` ```echarts ` | PNG |
  155. | Infographic | ` ```infographic ` | PNG |
  156. | HTML/CSS | (no fence, raw HTML) | HTML |
  157. ---
  158. ## 🔗 Links
  159. - [Markdown Viewer Extension](https://docu.md) - The rendering engine behind these skills
  160. - [Agent Skills Format](https://agentskills.io/) - Standard format for AI agent skills
  161. - [Chrome Extension](https://chromewebstore.google.com/detail/markdown-viewer/jekhhoflgcfoikceikgeenibinpojaoi) - Install for Chrome and Chromium browsers
  162. - [Edge Extension](https://microsoftedge.microsoft.com/addons/detail/documd-markdown-viewer/iphmkjlbnogmhofmmcahdhodiilokfca) - Install from Microsoft Edge Add-ons
  163. - [Firefox Add-on](https://addons.mozilla.org/firefox/addon/markdown-viewer-extension/) - Install for Firefox
  164. - [Obsidian Plugin](https://community.obsidian.md/plugins/markdown-viewer-extension) - Install from the Obsidian community directory
  165. - [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=xicilion.markdown-viewer-extension) - Install for VS Code
  166. ---
  167. ## 🤝 Contributing
  168. Contribute to the single package, not to new engine-named skills:
  169. 1. Find the goal domain your example belongs to in `documd-visuals/catalog/scenarios.tsv` (or open
  170. `SKILL.md` to see the router). If no domain fits, propose one — domains hold 3–8 scenarios.
  171. 2. Write the example and register it in the TSV (see *Adding an example* above).
  172. 3. Run all four gates; a failing render or a stale catalog blocks the change.
  173. 4. Keep statements traceable: every example ends with `<!-- source: … -->` pointing at the engine docs.
  174. ---
  175. ## 📄 License
  176. **The skill package (`documd-visuals/`) is [CC-BY-4.0](LICENSE)** — use it, copy it, adapt it and
  177. redistribute it, including commercially and including the examples, with attribution. The same text ships
  178. inside the package as [`documd-visuals/LICENSE.md`](documd-visuals/LICENSE.md), so an installed copy
  179. carries its own terms. The grant covers the whole repository, including the repo-only tooling in
  180. `scripts/` and the dossiers in `research/` — neither directory is shipped or discovered as a skill.
  181. **The `documd` CLI and the rendering engines are separate works under GPL-3.0-only.**
  182. `@markdown-viewer/documd`, `@markdown-viewer/draw-uml` and `@markdown-viewer/drawio2svg` are not part of
  183. this package and are not covered by the CC-BY-4.0 grant above; installing the skill does not license them.
  184. **Attribution, in practice.** CC-BY-4.0 asks for it when you share the package, and only then. Vendor it and
  185. keep `LICENSE.md` beside it, or put one credit line in your project's notices — both satisfy it. Writing
  186. documents *with* the skill, and documents that stay inside your organisation, require nothing at all. Never a
  187. per-figure credit. Full detail: [`documd-visuals/LICENSE.md`](documd-visuals/LICENSE.md).
  188. **Third-party names** used throughout this package — PlantUML, AWS, Azure, Cisco, ArchiMate, ECharts,
  189. Vega, AntV and others — are the trademarks of their respective owners, referenced only to describe the
  190. syntax and icon sets this package documents. No trademark rights are granted.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.