前言¶

在文档、评审和方案里画图时，常见做法是手写 Mermaid，或让模型「随便写一段」再自己改语法。后者往往出现箭头写错、中文标签未加引号、节点名过长导致布局错乱等问题，图在 Markdown 预览里直接报错。

下面介绍 SkillHub 上的 Mermaid Diagram（坐标 @clawhub_pupujanet-eng/mermaid-diagram）。它把「选图类型、遵守输出规则、对照语法参考」写进 Skill 说明，引导 Agent 生成语法有效的 Mermaid，覆盖流程图、时序图、思维导图、ER 图、用户旅程等常见类型。该 Skill 标注 requires_api_key=false，不依赖额外 API Key。

这是什么¶

Mermaid Diagram 是一套面向编码助手的 Agent Skill（基于通用 SKILL.md 格式），由 pupujanet-eng 维护，经 clawhub 分发，在 SkillHub 归类为 dev-programming，当前版本 1.0.0。

一句话定位：根据文字或产品描述，生成可直接放进 Markdown 的 Mermaid 代码块，并尽量规避常见语法错误。

• SkillHub 页面：https://www.skillhub.cn/skills/clawhub_pupujanet-eng/mermaid-diagram
• 上游说明：https://clawhub.ai/pupujanet-eng/mermaid-diagram
• 安装入口（API 坐标）：https://api.skillhub.cn/zcwl/mermaid-diagram

核心功能¶

以下能力均来自上游 Skill 文档，已核对。

支持的图表类型¶

Skill 内有一张「需求 → 推荐类型 → Mermaid 关键字」对照表，便于按场景选型：

输出规则¶

Agent 按 Skill 约定输出时，应做到：

1. 始终用 ```mermaid 代码块包裹结果。
2. 用户用中文描述时，节点与标签优先使用中文。
3. 复杂图可用 %% 注释标出分区含义。
4. 节点名尽量简短（文档建议不超过约 10 个字符），减轻布局问题。
5. 输出前在逻辑上自检语法，并避免：带空格或中文的标签未加引号、箭头语法混用（--> / --- / ->>）、括号未闭合等。

参考材料¶

Skill 提到 references/diagram-patterns.md，内含产品经理常用图模式与完整示例；当用户指定图类型或需要多节点复杂图时，Agent 应读取该参考。

安装与启用¶

通过 SkillHub（推荐国内环境）¶

先确认本机是否已有 SkillHub CLI：

command -v skillhub && skillhub --version

未安装时，可按官方安装文档执行完整安装或仅 CLI：

# 完整安装（CLI + 默认 Skill，推荐）
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

# 仅安装 CLI
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

安装本 Skill 时，必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 且可能不被识别。在 Cursor 中，常用路径为：

skillhub install @clawhub_pupujanet-eng/mermaid-diagram --dir ~/.cursor/skills/

也可将下面提示词发给 AI，让其按 https://skillhub.cn/install/skillhub.md 完成安装：

请根据 https://skillhub.cn/install/skillhub.md，安装 `@clawhub_pupujanet-eng/mermaid-diagram`。

其他客户端的常见 skills 目录（摘自 SkillHub 安装文档，便于对照）：

• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下的 .agents/skills/

通过 OpenClaw / ClawHub¶

上游页面给出的安装命令为：

openclaw skills install @pupujanet-eng/mermaid-diagram

坐标在 SkillHub 侧为 @clawhub_pupujanet-eng/mermaid-diagram，与 ClawHub 的 @pupujanet-eng/mermaid-diagram 为同一技能的不同命名空间，以你当前使用的商店 CLI 为准。

安装后按所用 Agent 的要求重启或刷新 skills 目录，使 Skill 生效。

典型用法¶

启用 Skill 后，用自然语言描述「要画什么、给谁看」即可；Agent 应选对图表类型并返回 mermaid 代码块。下列片段来自上游 Quick Syntax Reference，可直接作为对话示例或自检模板。

流程图示例：

flowchart TD
    A[开始] --> B{判断条件}
    B -- 是 --> C[执行操作]
    B -- 否 --> D[结束]
    C --> D

时序图示例：

sequenceDiagram
    用户->>服务端: 发起请求
    服务端->>数据库: 查询数据
    数据库-->>服务端: 返回结果
    服务端-->>用户: 响应

思维导图示例：

mindmap
  root((产品名))
    功能A
      子功能1
      子功能2
    功能B

实际对话中可以更具体，例如：「用 flowchart TD 画用户登录分支，中文标签」「画 API 下单的 sequenceDiagram，包含支付回调」。复杂场景可明确要求 Agent 查阅 diagram-patterns.md。

适用场景与注意¶

适合谁

• 需要在 PR、设计文档、Wiki 里快速插入 Mermaid 的开发者。
• 希望减少「模型输出图语法报错、反复手改」的场景。
• 产品、架构讨论中需要流程、时序、ER、旅程等标准图类型，且希望输出规则统一。

使用注意

• Skill 约束的是生成规范，不替代你在目标平台（GitHub、Notion、自建渲染器）上对 Mermaid 版本与特性的兼容性验证。
• 节点过多时，即使语法正确也可能布局拥挤；可要求拆分多张图或缩短节点名。
• SkillHub 页面展示的评分、下载量会随时间变化；以页面当前数据为准。

结尾¶

Mermaid Diagram 把图表类型选型、输出格式与常见语法坑写进 Skill，让 Agent 在「图解」类任务里更稳定地交出可渲染的 Mermaid。若要从国内商店安装，可从 SkillHub 页面或安装 API 坐标入手：

https://www.skillhub.cn/skills/clawhub_pupujanet-eng/mermaid-diagram

https://api.skillhub.cn/zcwl/mermaid-diagram