Markdown 与 Mermaid 文档编写

问题在哪

科学报告、ADR、README 里常见两类痛点：关系用长段 prose 描述，review 和 git diff 都费劲；一上来就用 matplotlib 或 AI 出图，产物是二进制或托管图，无法作为版本库里的单一事实来源。此技能把「带 Mermaid 的 .md」定为默认交付格式：图表是文本，GitHub/GitLab/Notion/VS Code 可直接渲染，以后仍可导出 PNG，但源码始终可改、可比对。

技能如何工作

核心是一条三阶段工作流，其中阶段 1 为必选——即便后续用 Python 或 AI 做出版级图，Mermaid 源码仍须入库。

1. 识别文档类型：从 PR 记录、Issue、ADR、研究论文、操作指南等 9 类模板择一开局。
2. 读样式指南：references/markdown_style_guide.md（单 H1、H2 用 emoji、脚注引用外部声明、表格优于散文等）；写 Mermaid 前读 references/mermaid_style_guide.md 及对应 references/diagrams/*.md。
3. 选对图类型：覆盖 24 种（流程图、时序图、ER、甘特、C4、雷达 radar-beta、XY xychart-beta 等），按用例匹配而非一律 flowchart。
4. 内联编写并提交：图表贴在相关段落旁；强制规则包括不用 %%{init}、不用内联 style（仅 classDef）、节点 ID 用 snake_case、支持类型使用 accTitle/accDescr。

与其它文档类技能配合时，它充当文档与可视化层：例如 scientific-schematics 的 PNG 以 Mermaid 作结构说明；scientific-writing 负责正文，本技能负责结构图。

边界与注意

• 阶段 2/3：真实数据散点、逼真插图等 Mermaid 表达不了时再上 matplotlib/seaborn 或 AI 图像，但不替代阶段 1 的 .md。
• 常见坑：雷达图必须用 radar-beta 与 axis/curve 语法，与 XY 图表关键字不同；不支持无障碍注释的类型需在代码块上方用斜体说明。
• 样式与模板内容源自 SuperiorByteWorks-LLC/agent-project（Apache-2.0），技能包内保留归属说明。