跳转到使用指南
diagram作者 Garry Tan

Diagram Skill.

Claude Code 和 Codex 的图表 skill:将描述或 Mermaid 源码转换为可编辑的 Excalidraw 文件以及渲染的 SVG 和 PNG。

  • Diagrams & Data Visualization
  • Diagram
garrytan/gstack · diagram/SKILL.mdSKILL.md
--- name: diagram description: Turn an English description (or mermaid source) into a diagram triplet: the source, an editable .excalidraw file you can open on excalidraw.com, and rendered SVG + PNG. (gstack) --- ## When to invoke this skill ## Step 1 — Author the diagram ## Step 2 — Stage the render bundle (once per session) ## Step 3 — Render the triplet ## Step 4 — Show and deliver ## Rules
从 2026-09-14 的上游文件读取的前言和章节标题 · 完整 16,276 字符

01 功能说明

该 diagram skill 在 Claude Code 和 Codex 中的功能

摘要、工作流与产物,均读自该 skill 的 SKILL.md。

来自 SKILL.md读取于 2026-09-14 · 非实际运行记录

以 skill 自身的术语

将英文描述或 Mermaid 源码转换为一套三件套图表:Mermaid 源文件(.mmd)、可在 excalidraw.com 打开的可编辑 Excalidraw 文件(.excalidraw),以及渲染后的 SVG 和 PNG 输出。渲染完全通过本地回环服务器离线完成——运行时使用 Aside 浏览器,否则使用 gstack 自带的无头浏览器。

流程图(graph LR/TD)和序列图会生成完全可编辑的 Excalidraw 场景,包含真实的方框、箭头和文字。其他 Mermaid 图表类型(状态图、类图、甘特图)会渲染为 SVG/PNG,并作为 Excalidraw 文件中的单一图像元素导出——可移动、可标注,但不可编辑元素本身。Mermaid 源文件始终是用于迭代的唯一事实来源。

它产出什么

  • 一个 Mermaid 源文件(.mmd),作为对 LLM 友好的交换格式和唯一事实来源。
查看示例提示词 ↗

工作方式

  1. 01
    编写 Mermaid 源码

    编写符合用户需求的 Mermaid 代码。管线/流程优先使用 graph LR,层级结构优先使用 graph TD。

  2. 02
    每个会话中暂存一次渲染包

    将 diagram-render.html 暂存到 gstack 的渲染暂存目录 ${TMPDIR:-/tmp}/gstack-render 中,按 bundle SHA 进行内容寻址。

  3. 03
    用一条命令渲染三件套

    编写 .mmd 文件,然后使用暂存好的 bundle 运行 gstack-render。

  4. 04
    展示并交付

    内联读取 PNG,让用户看到图表。列出三元组路径,并说明该 .excalidraw 文件可在 excalidraw.com 打开进行编辑。

02 找到适合场景

何时使用 diagram Skill

当任务是此类图表和图形时,在 Claude Code 或 Codex 中使用 diagram skill。适用范围和限制来自该 skill 自己的文件。

适合场景

  • 用户请求制作图表、绘制架构图、创建流程图、绘制这个图,或将某个流程可视化。
  • 为文档生成清晰的矢量图表,同时为聊天、issue 或 README 生成栅格化输出。
  • 生成可编辑的 Excalidraw 文件,用户可在 excalidraw.com 打开、移动方框并继续编辑。

了解边界

  • 单个场景中节点数超过 15 个的图表——应拆分为多个图表以提高可读性。
  • 状态图、类图、甘特图等非流程图/非序列图类型的 Mermaid,会生成可移动但元素不可编辑的 Excalidraw 文件。

需要提供的信息

  • 英文描述或 Mermaid 源码用户提供要创建的图表描述,或提供现有的 Mermaid 源码进行渲染。

03 Skill 内部

diagram skill 赋予 Claude Code 和 Codex 的规则

SKILL.md 为 Agent 设定的 8 条具体指令、默认值与限制——文件中真正改变结果的部分。

  1. 绝不在未渲染的情况下交付

    仅有 .mmd 文件并不算是一张图表。如果无法渲染(缺少 bundle 或没有可用浏览器),需说明阻塞原因并停止。

  2. 流程图与序列图完全可编辑

    流程图(graph LR/TD)和序列图会转换为完全可编辑的 Excalidraw 场景,具有真正的方框、箭头和文字。其他 Mermaid 类型则导出为单个图片元素。

  3. 将源码进行 Base64 编码以便浏览器传输

    通过 base64 将 Mermaid 源码传输到渲染页面,以避免解析源码中的反引号、${ } 和反斜杠。切勿将文件内容直接拼接进 JS 模板字符串中。

  4. 输出目录遵循 Git 上下文

    当当前工作目录是 git 仓库时写入 ./diagrams/(用户可提交的产物),否则写入 /tmp/gstack-diagrams/。根据主题以 kebab-case 生成 slug,最长 40 个字符。

  5. PNG 宽度固定为 1950px

    栅格化后的 PNG 始终为 1950 像素宽,相当于 6.5 英寸尺寸下 300dpi 的效果。

  6. 渲染完全离线进行

    diagram-render bundle 是自包含的,并通过 loopback 提供服务。不依赖 CDN,也不联网。

  7. 重新渲染已编辑的 Excalidraw 而不改动 Mermaid

    当用户编辑了 .excalidraw 文件并想要重新渲染时,直接加载该场景文件并导出 SVG/PNG——不要从 Mermaid 源码重新生成。

  8. PDF 目标场景中优先嵌入 .mmd

    对于要放入 PDF 的图表,请提醒用户 make-pdf 原生支持渲染 Mermaid 代码块——在 markdown 中嵌入 .mmd 比嵌入 PNG 更好。

04 投入使用

在 Claude Code 或 Codex 中安装 diagram

一条 npx skills add 命令,然后在你的 Agent 中执行第一个任务和对结果的清单检查。

将 diagram 添加到 Claude Code、Codex 或您的 Agent

在你的项目中运行;安装程序会询问要把它添加到哪个 Agent。

Terminal
npx skills add https://github.com/garrytan/gstack --skill diagram

用于 diagram/SKILL.md 的通用 skills CLI 形式;仓库可能会记录其自己的路径。

给 Skill 分配第一个图表和图示任务

按 skill 自身的术语撰写;把括号中的部分换成你的内容。

Starter prompt
Create a flowchart showing the build pipeline for [my TypeScript project]. Include lint, test, build, and deploy stages with their dependencies. Use graph LR layout and output to ./diagrams/.

来源:依据 SKILL.md,按 skill 自身的术语撰写。

检查首次结果

SKILL.md 本身如何描述正确的结果:

  • 内联读取 PNG 输出,验证图表渲染正确并符合用户的请求。
  • 检查 gstack-render 输出中的 ERROR: 行,判断是否存在 Mermaid 解析错误——如有,修复 .mmd 并重试。
  • 检查 PAGE_ERRORS 输出中是否有 'Error processing Mermaid diagram',以确认 Excalidraw 转换器何时回退为单个图像元素。
  • 确认 gstack-render 输出中出现全部三条 OK <path> 行,确认 SVG、PNG 和 Excalidraw 文件均已写入。
  • 对于编辑后的 Excalidraw 重新渲染,可忽略 PAGE_ERRORS 中无害的 WorkerInTheMainChunkError——SVG/PNG 是正确的。

在 OpenDesign 中从其 SKILL.md 链接导入 diagram:Plugins → Add → Skill → Import from link,然后在顶部栏中选择它。

05 开源、可追溯

来源、许可与验证

本页面事实的来源,以及最后检查时间。

Author
Garry Tan
Repository
github.com/garrytan/gstack 分支 main
Skill 文件
diagram/SKILL.md 验证时记录的内容校验和;提交 71f6048
License
MIT 来自 LICENSE。
仓库星标数
132,921 GitHub 快照于 2026-09-14 拍摄,针对整个 garrytan/gstack 仓库,该仓库在此目录中包含 7 个 skills。不是 diagram 的评分或使用计数。
已由 OpenDesign 验证
2026-09-14 已检查源文件、路径、许可文本和 star 数量。未内置在 OpenDesign 主程序(检查日期 2026-08-28);本页面未记录实际运行。

SKILL.md 内部

  1. 何时调用此 skill用于图表、架构、流程图或可视化请求;SVG/PNG 使用 Mermaid 样式,Excalidraw 具有手绘美感。
  2. 步骤 1 — 编写图表编写 Mermaid 源代码;流程图和序列图会成为完全可编辑的 Excalidraw,其他类型则以单个图像导出。
  3. 步骤 2 — 暂存渲染包(每个会话一次)将 diagram-render.html 复制到 gstack 的渲染暂存目录,按 SHA 进行内容寻址,绝不覆盖并发会话。
  4. 步骤 3 — 渲染三元组写入 .mmd,使用 base64 编码的源代码运行 gstack-render,输出 SVG/PNG/Excalidraw;检查解析错误和 PAGE_ERRORS。
  5. 步骤 4 — 展示并交付内联读取 PNG,列出三元组路径,注明 Excalidraw 的可编辑性;如需更改,编辑 .mmd 并重新渲染。
  6. 规则未渲染前绝不交付;对于 PDF 目标,提醒用户 make-pdf 原生渲染 Mermaid 代码块。
  7. 完成状态三元组交付后为 DONE;若缺少渲染包或没有可用浏览器,则为 BLOCKED。
Skill 自身的描述
「将英文描述(或 mermaid 源码)转换为图表三件套:源码、可在 excalidraw.com 打开的可编辑 .excalidraw 文件,以及渲染后的 SVG + PNG。(gstack)」

来自 SKILL.md 的前言描述。完整文件约 16,276 字符。在 GitHub 上阅读完整文件。

06 安装之前

关于 diagram Skill 的常见问题

以下回答来自 2026-09-14 读取到的 SKILL.md,而非某次实际运行的记录。

如果缺少渲染包或没有可用浏览器会怎样?

该 skill 会停止,并提示您在 gstack 仓库中运行 bun run build:diagram-render 来构建渲染包,或者在 gstack 的浏览器未构建时打开 Aside(macOS 15+)。该 skill 绝不会替您安装 Aside,也不会替换为 CDN 或其他渲染器。

Diagram

在真实的图表与图示任务上运行 diagram。

下载 OpenDesign,从其 SKILL.md 链接导入 diagram,粘贴上方提示,并在结果前阅读计划。

终端
npx skills add https://github.com/garrytan/gstack --skill diagram

OpenDesign 桌面客户端

一套设计系统,让每一次创作都保持品牌一致

在完整的 Vibe Design Workspace 中,用同一套品牌规则生成网页、PPT、可交互原型、数据看板、图像与 HTML 视频。连接本地 Codex、Claude Code、Cursor 等编程助手,即可免费创作。

  • 覆盖网页、PPT、原型、数据看板、图像与视频
  • 140+ 设计系统,以及完整模板与技能库
  • 连接本地 Codex 与 21+ 款编程助手 · 免费使用
免费下载

支持 macOS 与 Windows