AI Agent图表生成Skill：用GitHub开源模板实现稳定可复用的数据可视化

GitHub 上开源项目很多但能把 AI Agent 的图表生成能力沉淀成一套可复用 Skill 的项目并不多。我维护的这个图表 Skill 最近完成了一次大更新重点补上了两类高频模板六边形图表生成器和中心数字辐射图同时重构了参数说明、目录结构和生成脚本的调用方式。这篇文章以这个项目为主线把图表 Skill 的定位、目录结构、SKILL.md 的写法、两个新模板的实现细节、完整调用流程以及常见问题排查路径都展开讲一遍适合正在给 AI 编程工具编写自定义技能、需要把图表输出稳定复现到报告或数据看板里的开发者。Skill 和普通脚本最大的区别是它是“给 Agent 看”的能力描述文件。如果只是写一个临时脚本每次都要重新解释如何使用而做成 Skill 之后Agent 能根据需求描述自动决定是否调用、调用哪个模板、传入什么格式的数据。这意味着同样一句话不需要每次重复生成一套风格迥异的图表代码输出会稳定很多。1. GitHub 上的图表 Skill 解决的是什么问题1.1 Skill 不是插件而是一套“指令 模板 脚本”的能力包很多人第一次接触 Skill 时会把它理解成插件或扩展包实际上它更像一份“给 AI Agent 的说明书 可执行脚本 渲染模板”。在常见的 AI 编程工具里Skill 通过一个SKILL.md文件描述自身能力Agent 读取到这份文件后会根据用户请求判断是否触发该 Skill再按照文件里的步骤调用脚本和模板完成输出。图表生成很适合做成 Skill原因是 AI 直接写图表代码时经常出现这些问题每次生成的 ECharts 配置风格不一致有的用option对象有的直接改 HTML维护困难。同一个需求反复解释比如“中心数字要大”“线条要动态”“背景深色”每次都要重新描述一遍。图表库脚本要么从 CDN 加载要么内联网络不稳定时输出不可用。数据格式没有校验维度数量和 series 数量对不上时只报一个很隐晦的空白页。Skill 把这些问题收敛成三层由SKILL.md描述触发条件和生成流程由scripts/负责数据校验和 HTML 拼接由templates/提供可直接复用的图表模板。Agent 不需要每次从零设计页面只需要按模板填数据。1.2 图表 Skill 的边界把一次性的图表生成变成可复用能力图表 Skill 的适用场景很明确数据分析报告、周报月报、技术方案对比、监控大屏、汇报 PPT 里的配图。它的边界也很清楚它不负责数据处理不负责数据库连接只负责把已经整理好的结构化数据渲染成视觉图表。在这个项目里核心能力被拆成几个模板柱状图、折线图、饼图等基础图表用于常规数据展示。六边形图表生成器适合展示 6 个维度的能力画像或方案对比。中心数字辐射图像数据大屏里“中心是数字占比周围散发长短不一的动态线条”那种效果。这样做的好处是每个模板只解决一类问题。想要六边形能力对比就传 6 个指标和得分想要科技感大屏就传一个核心数字和标签生成逻辑不会被无关参数拖累。1.3 这次大更新的三条主线这次更新的重点可以归纳为三条。第一条是新增模板。六边形图表生成器面向能力评估和方案对比中心数字辐射图面向大屏数据展示这两个模板在之前的版本里要么没有要么只能用临时方案拼凑。第二条是参数统一。旧版本里不同模板的字段命名不一致有的叫label有的叫name有的用color有的用colorsAgent 调用时经常猜错。现在所有模板统一使用一套约定type、title、data以及模板专属的config字段。第三条是脚本和文档重构。generate.js现在会在生成 HTML 之前先做数据校验校验失败会明确提示缺少哪个字段而不是直接输出一个空白页面。同时每个模板都补了examples/下的示例 JSON方便验证。2. 安装与目录结构先把 Skill 放到 Agent 能读到的位置2.1 环境要求安装这个 Skill 之前先确认环境满足下表要求。这里区分了学习环境和生产环境学习时只要能打开 HTML 即可正式使用还需要考虑脚本依赖和输出管理。依赖项学习环境生产环境说明Git需要需要拉取仓库代码AI 编程工具需要需要支持 Skill 机制的客户端如 Claude Code、Cursor 或同类 Agent 工具Node.js可选建议generate.js依赖 Node 运行学习环境也可直接复制模板浏览器需要需要预览生成的 HTML 图表ECharts 本地文件可选建议生产环境建议把echarts.min.js放到assets/本地目录避免依赖外网 CDN如果原项目没有给出明确版本要求落地前要先确认自己使用的 AI 工具支持哪种 Skill 目录规范以及 Node.js 版本是否满足脚本语法要求。2.2 获取项目并放入 Skills 目录获取项目的方式和普通开源项目一样使用git clone即可。仓库地址以实际维护的 GitHub 地址为准下面的命令是通用示例git clone https://github.com/your-name/chart-skill.git cd chart-skill克隆完成后需要把整个项目放到 AI 工具能识别到的 Skills 目录里。不同工具的路径不同以 Claude Code 为例常见做法是放到用户的~/.claude/skills/目录下mkdir -p ~/.claude/skills cp -r chart-skill ~/.claude/skills/这里要注意Skill 目录名最好和SKILL.md里的name字段保持一致否则部分工具可能无法正确加载。如果本机访问 GitHub 仓库不稳定不要去寻找第三方镜像或加速工具直接稍后重试或从仓库 Release 页面下载官方压缩包再解压安全性更有保障。2.3 项目目录拆解完整的目录结构大致如下chart-skill/ ├── SKILL.md ├── scripts/ │ ├── generate.js │ ├── validate.js │ └── templates/ │ ├── hexagon.html │ ├── radial_ratio.html │ ├── line_bar.html │ └── pie.html ├── assets/ │ └── echarts.min.js ├── examples/ │ ├── hexagon.json │ └── radial_ratio.json └── README.md各目录分工如下SKILL.md是 Skill 的入口Agent 首先读取这个文件。scripts/generate.js负责根据输入 JSON 和模板生成最终 HTML 文件。scripts/validate.js负责数据校验在生成前拦截错误。templates/存放各图表模板模板之间尽量独立互不引用。assets/存放本地资源比如echarts.min.js。examples/存放示例数据每个模板至少对应一个 JSON。这样的结构能让“描述能力”和“实现逻辑”分离。修改图表样式时只需要调整模板不需要改动SKILL.md新增图表类型时只需要增加模板和示例不影响已有能力。2.4 学习环境与生产环境的差异学习环境里想快速看效果可以直接打开templates/下的 HTML 文件把示例 JSON 里的数据手动填进option或脚本变量里浏览器刷新就能看到图表。生产环境则要额外注意几点必须固定 ECharts 版本不要每次从 CDN 拉取不同的版本否则图表渲染结果可能漂移。输出目录要可配置不要在模板里写死绝对路径。数据校验要放在生成之前不能让错误数据进入 HTML。生成的 HTML 文件要加上时间戳或唯一 ID避免覆盖历史报告。如果图表数据来自用户输入HTML 里插入数据前必须做转义防止脚本注入。3. 核心文件 SKILL.mdAgent 如何知道该调用它3.1 frontmatter 的 name 和 description 决定触发时机SKILL.md的文件头是一段 YAML 格式的 frontmatter这里的description直接决定了 Agent 什么时候会调用这个 Skill。--- name: chart-skill description: 当用户需要生成柱状图、折线图、饼图、六边形能力图、中心数字辐射图等可视化图表时使用这个 Skill。 ---description要覆盖常见的触发场景同时不能写得太长。实际操作中Agent 会把这个描述和其他 Skill 的描述放在一起做匹配如果描述太泛比如只写“生成图表工具”Agent 可能无法判断该用它还是用它旁边的另一个 Skill如果描述写得太死比如只写“生成六边形图”用户说“帮我画一个能力对比图”时又可能触发不了。推荐的写法是“场景 图表类型 结果”三要素。例如description: 用于数据可视化场景支持柱状图、折线图、饼图、六边形能力图、中心数字辐射图输出独立 HTML 文件。3.2 正文指令要写得像给开发者的注释SKILL.md的正文部分是给 Agent 看的操作说明。它不需要写完整的教程但必须写清楚执行顺序和模板选择规则。# 图表生成 Skill 1. 阅读用户需求判断图表类型。 2. 将用户提供的数字整理成对应模板要求的 JSON 数据。 3. 调用 scripts/validate.js 检查数据完整性。 4. 调用 scripts/generate.js 生成独立 HTML 文件。 5. 告诉用户输出文件的完整路径和浏览器预览方式。 模板选择规则 - 方案对比、能力评估、6 个维度以内 → hexagon.html - 核心占比数字 动态视觉背景 → radial_ratio.html - 时间序列趋势 → line_bar.html - 分类占比 → pie.html 通用数据格式 { type: hexagon, title: 图表标题, data: { ... } }这样写有两个好处。一是 Agent 每一步做什么都由清单明确约束不会跳过校验直接生成二是模板选择规则用“场景 → 模板”的映射表达Agent 根据用户需求做匹配的准确率更高。3.3 常见书写误区第一个误区是在SKILL.md里写太长的代码示例。Agent 的上下文窗口有限文档越长越容易丢失关键信息建议只保留模板选择规则和最小数据格式。第二个误区是写死路径。不要把输出路径写成/Users/xxx/output应该写成相对路径或环境变量形式例如./output/否则换一台机器就失效。第三个误区是忽略错误处理说明。正常情况下模板会渲染成功但遇到数据缺失时 Agent 应该怎么办建议在SKILL.md里明确写一句数据不完整时先提示用户补充不要强行生成。4. 新增模板解析六边形图表和中心数字辐射图4.1 六边形图表用 ECharts radar 实现能力画像六边形图表生成器的本质是一个 6 指标的雷达图把 6 条轴线围成的视觉区域做成六边形。它适合展示方案在多个维度上的能力强弱例如稳定性、性能、可维护性、安全、扩展性和成本。下面是一个模板中用到的核心配置const option { radar: { indicator: [ { name: 稳定性, max: 100 }, { name: 性能, max: 100 }, { name: 可维护性, max: 100 }, { name: 安全, max: 100 }, { name: 扩展性, max: 100 }, { name: 成本, max: 100 } ], shape: polygon, radius: 65%, axisName: { color: #475569 }, splitArea: { areaStyle: { color: [#f8fafc, #f1f5f9] } } }, series: [ { type: radar, data: [ { value: [85, 78, 92, 70, 88, 60], name: 方案 A }, { value: [70, 85, 65, 90, 74, 80], name: 方案 B } ], areaStyle: { opacity: 0.15 } } ] };这个配置的关键点有三个indicator的数量决定了图形是几边形模板固定为 6 个指标所以视觉上是六边形。max值决定每个维度的满分如果不同维度量纲不一致要先归一化处理否则面积会被某个大数量级维度压扁。shape: polygon让雷达图的外圈和分割线呈现多边形样式这正是“六边形感”的来源如果改成默认值就会显示成圆形网格。一个常见坑是indicator有 6 项但series[0].data[0].value里只填了 5 个数字或者反过来。ECharts 对这种错误通常不会在控制台报明显异常表现就是图形少了一条边或多出一个怪异折角排查时要先数清楚数量是否一致。4.2 中心数字辐射图用 Canvas 画动态数据大屏中心数字辐射图是这次更新里科技感最强的一个模板效果是页面中心放一个数字占比周围有长短不一的动态线条不断散发像声波或雷达扫描。这个效果用 Canvas 实现会比直接用 ECharts 更简洁因为线条数量多、每帧都要更新位置和透明度Canvas 的绘制开销更低。!DOCTYPE html html langzh-CN head meta charsetUTF-8 title中心数字辐射图/title style body { margin: 0; background: #0f172a; display: flex; align-items: center; justify-content: center; height: 100vh; } .wrap { position: relative; text-align: center; } canvas { display: block; } .core { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); color: #e2e8f0; } .core .num { font-size: 56px; font-weight: 700; } .core .label { font-size: 16px; color: #94a3b8; } /style /head body div classwrap canvas idradarLines width440 height440/canvas div classcore div classnum>{ type: hexagon, title: 技术方案对比, data: { indicators: [ { name: 稳定性, max: 100 }, { name: 性能, max: 100 }, { name: 可维护性, max: 100 }, { name: 安全, max: 100 }, { name: 扩展性, max: 100 }, { name: 成本, max: 100 } ], series: [ { name: 方案 A, value: [85, 78, 92, 70, 88, 60] }, { name: 方案 B, value: [70, 85, 65, 90, 74, 80] } ] } }中心数字辐射图的结构更简单{ type: radial_ratio, title: 系统可用率, data: { coreValue: 86%, coreLabel: 系统可用率, lineCount: 48, radiusMin: 60, radiusMax: 180, backgroundColor: #0f172a } }校验脚本validate.js会检查上面两个结构的必填项。六边形图要求indicators和series都存在且indicators.length等于每个value数组的长度中心数字辐射图要求coreValue非空。校验失败时脚本会输出明确的错误信息而不是继续生成。5.2 调用过程Agent 按 SKILL.md 执行用户提出需求后Agent 的处理流程大致是读取SKILL.md确认用户需求属于图表生成。根据模板选择规则确定使用hexagon还是radial_ratio。把用户提供的数字、标题、标签整理成上面 JSON 结构。运行数据校验脚本。调用generate.js生成 HTMLnode scripts/generate.js --input examples/hexagon.json --output output/hexagon.html将输出文件的路径和预览方式反馈给用户。generate.js做的事情本质上是一次模板替换读取 HTML 模板把 JSON 数据中的字段写入对应的变量位置。比如中心数字辐射图模板里的>div idchart stylewidth: 100%; height: 600px;/div如果容器只写了宽度没写高度ECharts 初始化时会拿不到高度导致渲染区域为 0。补齐height后刷新页面即可。第四步如果页面能显示但图形不正确回到数据校验。用validate.js检查 JSON通常能直接定位到指标数量和数值数量不一致的问题。这个排查顺序的核心思路是先确认资源有没有加载再确认容器有没有尺寸最后才怀疑数据。顺序反了往往会反复修改数据却解决不了问题。7. 最佳实践与扩展方向7.1 维护图表 Skill 的可复用清单给这个项目维护代码时我整理了一份发布前检查清单每次更新都按它过一遍[ ]SKILL.md的description是否覆盖新增模板的所有触发场景。[ ] 每个模板是否有对应的examples/示例 JSON。[ ] 模板是否为单 HTML 或明确依赖本地assets/不隐式依赖外网 CDN。[ ] 数据校验逻辑覆盖所有必填字段和数组数量一致性。[ ] 输出文件名包含时间戳或唯一 ID避免覆盖历史文件。[ ] 用户输入内容写入 HTML 前做了转义避免脚本注入。[ ] 深色背景模板和浅色背景模板的配色在明暗两种环境下都可读。[ ] 更新模板后用所有 examples 重新生成一遍并人工打开页面验证。7.2 扩展方向图表 Skill 的能力可以从几个方向继续扩展。第一个方向是增加图表类型。当前模板覆盖了雷达图、辐射图和基础图表还可以加入桑基图、地图、热力图。每增加一种类型需要同步补一套模板、一个示例 JSON 和SKILL.md里的选择规则。第二个方向是支持更多数据输入格式。目前模板接收的是结构化 JSON可以扩展为直接读取 CSV、Excel 或数据库查询结果由脚本负责字段映射和数据类型转换。第三个方向是接入自动化报告流程。生成的 HTML 可以直接作为报告页面归档也可以进一步转成 PDF 快照这样 Skill 不仅能服务于交互式对话还能在定时任务里自动产出图表。第四个方向是模板参数化配置。把配色、字体、动画速度等视觉选项全部提取到config字段中让 Agent 在生成前根据用户偏好自动调整避免每次修改模板源码。7.3 给新贡献者的建议如果想参与这类开源 Skill 项目的维护先不要急着写新模板。建议先读懂SKILL.md的执行流程再用examples/里的数据完整跑通生成和预览链路最后观察一次 Agent 真实调用时的日志理解哪里容易出错。新提交模板时务必遵守一条原则模板必须能脱离 Skill 独立运行。也就是说把模板 HTML 直接拖进浏览器不依赖 Agent 的上下文也能显示示例效果。这样既能方便维护者审查也能让用户在拿到文件后第一时间看到结果。维护 GitHub 上的开源项目长期最有价值的部分不是某一次漂亮的更新而是每份模板、每段说明和每个示例都能被后来者在真实场景里复用。图表 Skill 这次更新的目标也正是让 Agent 生成的图表从“偶尔能用”变成“稳定可复用”。