
markdown-viewer 发布 documd-visuals 技能包,让 AI 编程代理在 Markdown 中生成图表
来源标题:Skills for AI coding agents to create diagrams in Markdown
markdown-viewer 推出面向 docu.md Markdown 管线的 documd-visuals 技能包,可通过 npx skills add 安装,兼容 Claude Code、Codex、Cursor 等 AI 编程代理。该包按读者目标组织,内置 5 个渲染引擎,并提供 242 个经核验的示例、183 个场景和 31 个目标领域。图表配色取自 styles/ 中定义的九种主题,由脚本检查主题漂移、对比度和渲染覆盖。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
docu.md Markdown 管线的 Agent skills。一个 skill 包,按读者的目标组织,背后是各渲染引擎作为实现参考。242 个经过验证的示例 · 183 个场景 · 31 个目标域 · 5 个引擎,每张图都从 styles/ 中定义的九种主题之一取色,并由源表生成,由 scripts/check-all.mjs 把关(主题漂移 · 对比度 · 块渲染 · 块覆盖 · 主题使用 · 结构),另有 scripts/verify-examples.mjs 负责完整渲染验证。
🚀 安装 • 🧩 包结构 • ⚙️ 引擎 • 🖥️ documd CLI • 🔀 迁移的 Skills • 🔗 链接
快速安装(推荐) npx skills add markdown-viewer/skills 此方式适用于多种 AI 编码代理(Claude Code、Codex、Cursor 等),并会自动发现 documd-visuals 包。 cp -r skills/documd-visuals ~/.claude/skills/ 对于 claude.ai 将包添加到项目知识库,或将 SKILL.md 内容粘贴到对话中。 当包放置在 .github/skills/ 目录下时会被自动检测。
skills/ ├── documd-visuals/ ← skill 包 —— 这里唯一的 skill,也是唯一被安装的内容 │ ├── SKILL.md ← 路由:铁律、31 个目标、能力边界 │ ├── converting.md ← documd CLI:安装、格式、参数、导出后保留的内容 │ ├── catalog/ ← 每个场景:领域、引擎、层级、示例文件 │ ├── goals/ ← 每个目标域一份指南 │ ├── engines/ ← 每个引擎的参考 + coverage/ 台账(先按单元,再按目标列示例) │ ├── examples/ ← 242 个经过验证的示例,按目标域分组 │ └── styles/ ← palette.md(契约)+ themes/<theme>.md(取值 + 每个引擎一个块) ├── research/ ← 引擎档案:覆盖台账 + 验证笔记(仅仓库内,从不随包发布) └── scripts/ ← 仓库级把关脚本(不随包发布)
该包是自包含的:它从不引用 research/ 或 scripts/,一旦引用,把关脚本会让构建失败。如果你安装了该包,它引用的一切都在包内——而包内每个文件都能从 SKILL.md 到达,这一点由 validate-skills.mjs 强制执行。唯一的例外是 LICENSE.md:法律附件不属于路由内容,因此它随包发布,但不从路由中链接。
research/ 和 scripts/ 不会被当作 skill 发现:CLI 通过定位 SKILL.md 来发现 skill,而这两个目录都不包含 SKILL.md。已验证——npx skills add ./skills --list 恰好报告一个 skill:documd-visuals。
SKILL.md 将读者的意图匹配到 31 个目标域之一,这些目标域分为四个元簇:数据与指标 · 流程与系统 · 基础设施与治理 · 知识与表达。 goals/<domain>.md 列出该域的场景及实现它们的示例文件。 engines/<engine>.md 涵盖所选引擎的限制与反模式。
目标域 元簇 域 A — 数据与指标 service-reliability · ops-monitoring · delivery-throughput · goal-and-status-reporting · product-metrics · business-reporting · go-to-market · cost-and-budget · data-exploration B — 流程与系统 engineering-operations · incident-management · process-and-workflow · software-design · software-behaviour · dependencies-and-relations · system-architecture C — 基础设施与治理 cloud-architecture · data-platform · network-topology · security-and-compliance · enterprise-architecture · organization-and-roles · people-and-hiring D — 知识与表达 knowledge-and-outline · planning-and-roadmap · migration-and-rollout · comparison-and-selection · internal-documents · catalogues-and-inventories · customer-and-partner-comms
⚙️ 引擎 推荐——用这些编写新内容 其他引擎均不推荐。该包不记录任何其他引擎,新内容使用上述五种;被排除的引擎名称只在一处列出,即 SKILL.md 的描述中,这样当用户要求使用某个引擎时,代理能识别它们并拒绝。
该包将图形绘制为 Markdown 中的文本,由查看器实时渲染——作者从不需要预先渲染任何内容。documd CLI 是可选的导出部分:它将整个 Markdown 文档渲染为成品文件,将图表源码渲染为图片。它在包内有文档——documd-visuals/converting.md,从 SKILL.md 链接——因此安装了该 skill 的代理知道导出路径的存在。
安装 skill 并不会安装 CLI,也无法让安装器做到这一点。npx skills add 会将文件复制或符号链接到代理的 skills 目录;Agent Skills 格式没有 install-hook 字段,CLI 在 add 期间也不运行任何自己的脚本。skill 包在任何环节都无法触发 npm install。请将 CLI 视为 skill 所指向的独立工具。
npx @markdown-viewer/documd report.md report.docx # 也支持 .pdf .epub .html npx @markdown-viewer/documd architecture.puml architecture.svg # 也支持 .png 如果同一命令需要反复运行,请安装一次——这会提供 documd 二进制: npm install -g @markdown-viewer/documd ⚠️ 务必带上 scope。npm 上的裸名 documd 是一个无关的包("markdown object notation")。npx documd 拉取的是那个包,而不是这个 CLI。请始终写 @markdown-viewer/documd。 npm 发布的版本与扩展版本一致,因此 npx 运行的就是此处记录的构建。
本仓库过去发布 14 个以引擎和领域命名的 skill。现在它们合并为一个包,其内容是重写的,而非复制的:
没有兼容性存根:CLI 通过定位 SKILL.md 来发现 skill,因此存根目录会被忽略而不是被安装——只会给仓库增加一个死目录。请重新安装以获取新包。
把关 node scripts/check-all.mjs # 一次性运行所有主题把关 node scripts/validate-skills.mjs # 布局、预算、目录、围栏、语言、主题可达性 node scripts/build-themes.mjs --check # 主题文件与源表一致 node scripts/build-catalog.mjs --check # 目录 ↔ 文件系统一致 node scripts/build-goals.mjs --check # 目标文档与目录一致
(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。