markdown-viewer/skills 是一套专为 AI 编码代理设计的 Markdown 图表技能集合，提供 15 种技能覆盖 7 类渲染引擎，使代理能在 Markdown 中直接生成流程图、架构图、数据可视化等专业图表。本文详细介绍项目定位、解决的问题、适用场景、安装步骤及使用方法，帮助开发者快速集成并提升技术文档质量。
markdown-viewer/skills 是一套为 AI 编码代理设计的 Markdown 图表技能集，通过 15 种预定义技能覆盖 7 类渲染引擎，使代理能在 Markdown 文档中直接生成流程图、架构图、数据可视化等专业图表，提升技术文档的视觉表现力。
markdown-viewer/skills 是一套专为 AI 编码代理设计的 Markdown 图表技能集合，旨在扩展代理在技术文档中创建专业可视化的能力。项目提供 15 种技能，覆盖 7 类渲染引擎，包括流程图（Mermaid）、数据图表（Vega）、信息图表（Infographic）、思维导图（Canvas）、依赖图（Graphviz），以及基于 HTML/CSS 的架构图（Architecture）和信息卡（Infocard），还有基于 PlantUML 的 8 种领域特定技能（UML、云架构、网络拓扑、安全架构、ArchiMate、BPMN、数据 analytics、IoT）。这些技能使 AI 代理能根据描述自动生成符合行业标准的图表，无缝集成到 Markdown 文档中，提升技术文档的直观性和专业性。
传统 AI 编码代理在生成技术文档时通常只能输出纯文本，缺乏绘制专业图表的能力，导致文档表现力不足、沟通效率低下。本项目通过预定义的技能模板和语法，解决了 AI 代理无法创建复杂图表的问题。代理现在可以自动生成 ArchiMate 企业架构、BPMN 业务流程、云基础设施图、数据可视化等多种图表，且符合领域标准（如 PlantUML 宏、mxgraph 图标），确保图表的语义准确性和视觉规范性，从而显著降低文档制作成本，提升技术沟通质量。
本项目适用于需要在 Markdown 文档中嵌入专业图表的各类场景：软件架构设计（系统层图、微服务架构）、流程建模（业务工作流、审批流程）、数据可视化（统计图表、信息卡片）、基础设施规划（云资源拓扑、网络布局）、安全合规设计（威胁模型、零信任架构）以及知识整理（思维导图、概念地图）。开发者、架构师、技术文档撰写者和团队均可利用这些技能，快速生成高质量图表，用于设计文档、运维手册、分析报告、演示材料等，实现文档与图表的无缝集成。
项目提供多种安装方式以适配不同 AI 代理环境。快速安装（推荐）使用 npx 命令：`npx skills add markdown-viewer/skills`，该方式支持 Claude Code、Codex、Cursor 等代理。手动安装：对于 Claude Code，复制技能目录到 `~/.claude/skills/`；对于 claude.ai，将技能添加到项目知识或粘贴 SKILL.md 内容到对话；对于 GitHub Copilot / VS Code，将技能放置在项目 `.github/skills/` 目录下即可自动检测。具体安装步骤以各代理官方文档为准，仓库中未明确给出所有代理的详细配置流程。
在 Markdown 文档中使用图表技能时，需用特定代码 fences 包裹图表代码。例如，Mermaid 图表使用 ` mermaid `，Vega 图表使用 ` vega-lite ` 或 ` vega `，PlantUML 技能使用 ` plantuml ` 或 ` puml `。对于 architecture 和 infocard 等嵌入式技能，直接使用模板语法生成 HTML/CSS，无需代码 fences。详细语法、模板和最佳实践请参考各技能目录下的 SKILL.md 文件；具体示例可查看 examples/ 或 layouts/ 目录中的 Markdown 文件。图表渲染依赖于对应引擎（如 Mermaid、PlantUML、Vega）的支持，需确保渲染环境已配置。
项目采用模块化技能设计，每个图表引擎独立为技能模块，通过代码 fences 调用，便于维护和扩展。技能遵循 Agent Skills 格式，提供结构化文档。对于 PlantUML 技能（如 ArchiMate、BPMN），使用自定义语义宏（如 Rel_Realization、Rel_Flow）表达丰富关系，并集成 mxgraph 图标库以符合领域标准。文档模式驱动，每个示例文件包含 Pattern Notes，说明设计模式、宏用法和最佳实践，指导 AI 代理生成规范图表。示例按业务场景组织，便于代理根据上下文选择合适技能。嵌入式技能（architecture、infocard）直接输出 HTML/CSS，实现杂志级排版效果。
推荐使用 `npx skills add markdown-viewer/skills` 快速安装；对于 Claude Code 可手动复制技能目录到 `~/.claude/skills/`；GitHub Copilot/VS Code 需将技能放置在 `.github/skills/` 目录下。具体安装方式请参考 README 安装部分。
项目设计为兼容多种 AI 代理，包括 Claude Code、Codex、Cursor、GitHub Copilot 等。快速安装命令 `npx skills add` 适用于多个代理；手动安装路径因代理而异，详见 README 中的 Manual Installation 部分。
在 Markdown 文件中使用对应的代码 fences 包裹图表代码，例如 ` mermaid ` 用于流程图，` plantuml ` 用于 PlantUML 图表，` vega-lite ` 用于数据图表。嵌入式技能（如 architecture）直接使用模板语法生成 HTML/CSS。详细语法参考各技能的 SKILL.md 文件。
是的，每个技能目录下包含 SKILL.md 详细文档和 examples/（或 layouts/）示例文件，展示各种图表的编写模式、模板和最佳实践。例如，archimate/examples/ 提供了应用集成、业务能力等场景的 PlantUML 示例，bpmn/examples/ 提供了审批工作流等示例。
部分技能支持样式定制。architecture 和 infocard 技能提供多种布局和样式模板（如 13 种布局 × 12 种风格），可通过模板参数调整；PlantUML 技能支持通过宏和参数控制颜色、图标等外观，具体选项参考各 SKILL.md 中的语法说明。