如果你最近在用 Claude Code、Codex 或 Cursor 这类 AI 编程助手写数据分析页面大概率会遇到一个很尴尬的局面让 AI 画一张图表它确实画出来了但坐标轴标签挤成一团、千分位分隔符没了、配色辣眼睛数据量大一点页面直接卡死。这不是大模型能力不行而是它在“写代码”和“懂图表”之间缺少一层领域经验的沉淀。这个痛点就是我做这个开源图表 skill 的出发点。简单说我把坐标轴优化、配色规范、性能优化、图表选型这些图表领域的经验全部固化成了一套 AI 编程助手可以直接读取和执行的技能包。这次大更新之后它已经不只是“能画图”而是能把图表做到接近专业前端和数据分析师的水准。这篇文章我会把这次更新的核心内容、使用方式、定制方法以及常见坑都梳理一遍。如果你正在用 AI 编程助手做可视化相关的工作这篇建议收藏。1. 为什么要给 AI 编程助手做一个图表 skill先聊一个本质问题为什么直接让 AI 生成图表效果总是不稳定AI 编程助手本身是通用的代码生成器它知道 ECharts 的语法知道 Plotly 的 API也知道 D3.js 的基本逻辑。但它不知道你的项目中图表的“及格线”在哪里。你如果不告诉它它就不会主动去做这些事情数据量过万时自动切换到 canvas 渲染而不是 svg柱状图标签旋转角度和间隔的自动计算饼图大类超过 8 个时自动合并为“其他”折线图缺数据时用断点而不是强行连线双 Y 轴时主次轴刻度对齐和颜色一致性深色主题下的配色对比度和标签可读性。这些经验分散在很多图表库的文档、设计规范和项目代码里但没有任何一本手册会系统地写给你。普通 prompt 最多只能临时约束其中一两条没法形成稳定的输出质量。Skill 机制解决的正是这个问题。在 Claude Code、Codex 等工具中skill 不是一段简单的提示词而是一个带有目录结构、包含指令、模板、配置和校验规则的完整知识包。当对话内容命中 skill 的触发条件时AI 助手会把 skill 中的内容作为上下文加载再结合当前任务来生成结果。你可以把这个图表 skill 理解为“给 AI 装了图表部门的专业培训手册”。它不是让 AI 换个说法回答你而是让 AI 在生成代码的每一步都按一套已经验证过的标准来执行。2. 图表 skill 的基本原理与设计思路网上很多人把 skill 理解成“高级提示词”这个说法对了一半。从使用效果看skill 确实是通过指令约束模型行为但它的工程化程度远高于普通 prompt。一个标准的 skill 至少包含这三个部分SKILL.md技能的核心指令文件描述技能用途、触发条件、执行流程和输出规范资源文件包括代码模板、配置文件、数据样例、参考文档等AI 生成结果时可以按需参考验证规则输出结果需要满足的自检清单相当于给生成结果加了一道质检流程。我的图表 skill 在最初版本里重点做的是前两部分把常用的图表模板整理好写清楚生成要求。第一版发布后在 GitHub 上收到了不少反馈很多人确实用了起来但同时也暴露了几个明显的问题。其中一个最典型的反馈是图表库绑得太死。第一版主要面向 ECharts但相当一部分用户用的是 Plotly还有一部分人在写 Python 的数据分析脚本需要的是 matplotlib 和 seaborn。另一个问题是模板的风格和团队规范对不上改起来要动很多代码不够灵活。这次大更新就是围绕这些问题展开的。我从三个层面重构了整个 skill 的结构兼容层不再假设你用什么图表库而是通过配置项指定ECharts、Plotly、Chart.js、matplotlib 都可以模板层每个图表类型提供基础模板和进阶模板两套基础模板保证能跑进阶模板追加性能优化和交互细节规则层把坐标轴、颜色、图例、数据格式化、响应式适配等要求独立成规则文件用户可以通过配置开关控制。这个设计的好处是skill 不再是一份只能原样使用的文档而是一套可以按需裁剪的体系。你不用理解每一行模板代码是怎么写的只需要通过配置文件告诉 AI 你想要的风格和约束它就能生成符合要求的图表。3. 这次大更新的核心内容这次更新不是小修小补而是把图表 skill 从“可用”推进到了“好用”的阶段。下面逐条说清楚核心变化。3.1 支持多 Agent 平台之前使用这个 skill 需要手动把 SKILL.md 放到指定目录不同工具的配置方式还不一样。这次更新统一了项目结构并针对主流 Agent 工具的 skill 目录规范做了适配。目前支持以下环境Claude Code把 skill 文件夹放到项目的.claude/skills/目录Codex放到配置的 skills 目录并在配置中启用Cursor通过.cursor/rules/引用规则文件或按 Agent 模式加载。这样你在不同工具之间切换时不需要重新学习整套用法只是目录位置不同而已。3.2 新增图表类型第一版覆盖了常见的柱状图、折线图、饼图、散点图这次更新把覆盖面扩大到了数据分析和可视化场景中更专业的方向。新增的图表类型包括六边形蜂窝图用于展示密度分布和热力关系比如地理位置数据、用户分布密度桑基图用于展示流量流转、资源分配和路径分析雷达图用于多维度指标对比比如产品能力对比、绩效评估箱线图用于展示数据分布和异常值检测词云图用于文本分析和关键词热度展示瀑布图用于展示数据增减过程和构成变化。结构调整后每种图表类型都对应一个独立的模板文件互不影响。你只需要在配置中声明图表类型AI 就会自动加载对应模板和规则。3.3 配置化定制这是这次更新最核心的变化。之前想改样式规范你得手动改模板源码现在所有可调项都收敛到了chart-config.yaml配置文件中。配置文件支持以下维度的定制图表库选择主色调和辅助色坐标系风格包括网格线、轴线、标签旋转角度数据格式化规则包含千分位分隔符、百分比精度响应式断点和容器尺寸性能优化开关比如大数据量时切换 canvas 渲染输出格式偏好HTML 单文件、JavaScript 模块还是 Python 脚本。配置项的优先级高于模板默认值低于用户当前指令。也就是说如果对话中明确要求某个特殊处理以对话指令为准这样既保留了默认的规范化又给了灵活度。3.4 新增自检机制这次更新为 skill 加了一步“输出前自检”的流程。生成图表代码后AI 会按照自检清单逐项检查发现不满足要求的配置会主动修正不需要你反复打回重做。自检清单覆盖方面包括数据是否正确映射到图形属性坐标轴标签是否有重叠旋转角度是否合理数值格式是否符合配置要求图例和标题是否存在大数据量场景是否启用了降采样或 canvas 渲染深色模式下配色对比度是否满足要求空数据和异常值是否处理。这一步执行完输出质量和第一版相比提升非常明显。4. 环境准备与安装配置开始使用之前先确认你的开发环境满足要求。以下是本文示例所用的基础环境具体版本以实际项目为准操作思路是通用的。操作系统本文以 macOS / Linux 为例Windows 的路径略有不同开发工具Node.js 18GitAgent 工具Claude Code 或 Codex任选其一图表库默认使用 ECharts也可以通过配置切换到 Plotly 或 Chart.js。安装方式非常简单。假设你的 Agent 工具已经初始化了一个项目目录只需要把 skill 目录克隆到对应位置。以 Claude Code 为例进入项目根目录后执行mkdir -p .claude/skills git clone https://github.com/yourname/chart-skill.git .claude/skills/chart-skill注意yourname请替换为实际仓库地址。如果你不方便直接 clone也可以到 GitHub 仓库页面下载 ZIP 包解压后放到.claude/skills/chart-skill目录。文件目录结构如下.claude/skills/chart-skill/ ├── SKILL.md ├── chart-config.yaml ├── templates/ │ ├── echarts/ │ ├── plotly/ │ └── chartjs/ ├── schemas/ │ └── chart-config.schema.json └── assets/ ├── sample-data.csv └── reference/项目中的SKILL.md是技能入口文件chart-config.yaml是核心配置文件templates/目录里是不同图表库的模板schemas/目录提供了配置文件的格式验证。安装完成后可以在项目目录下直接启动 Claude Code输入“加载图表 skill”如果能看到技能解析成功的提示说明安装无误。Codex 用户请查阅你使用的 Codex 版本对 skill 目录的要求将项目放到对应位置即可。5. 完整使用示例与代码实现下面用一个实际场景演示从安装到生成一张专业图表全流程操作。5.1 场景设定假设你是一个数据分析工程师刚拿到一份某电商平台 2024 年各品类的月度销售额数据格式是 CSV。你需要让 AI 生成一张适合汇报使用的季度趋势堆叠面积图要求配色协调、数字有千分位分隔符、图表能自适应页面宽度。数据文件sales.csv内容如下月份,数码,家电,服饰,美妆 2024-01,120,86,45,30 2024-02,132,92,52,35 2024-03,145,90,68,42 2024-04,158,102,73,48 2024-05,170,115,79,55 2024-06,183,126,88,615.2 编写配置文件在项目目录下创建或修改chart-config.yaml指定这次的图表需求chart: type: stacked-area library: echarts title: 2024 年各品类季度销售趋势 theme: light color_palette: - #4E79A7 - #F28E2B - #59A14F - #E15759 data: format: csv source: ./sales.csv axis: x_label_rotation: 0 x_label_interval: auto number_format: thousand_separator: true decimal_places: 0 responsive: enable: true min_width: 320 performance: large_data_threshold: 5000配置项含义如下type声明图表类型是堆叠面积图library选择 EChartscolor_palette指定了一组色盲友好的配色thousand_separator开启千分位responsive开启自适应。剩余项使用模板默认值即可。5.3 在 Agent 对话中调用打开 Claude Code输入以下指令读取本项目的 chart-config.yaml 配置并参考 sales.csv 中的数据生成一张图表的完整 HTML 页面。要求使用配置中的配色标题居中显示图表宽高自适应页面。Skill 命中后AI 会读取配置和数据文件按规则生成代码。下面是生成结果的核心部分以 ECharts 为例!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / title2024 年各品类季度销售趋势/title !-- 建议在正式项目中使用按需引入的 ECharts 构建版本 -- script srchttps://cdn.jsdelivr.net/npm/echarts5/dist/echarts.min.js/script style html, body { margin: 0; padding: 0; background: #fff; } #chart { width: 100%; height: 520px; } media (max-width: 600px) { #chart { height: 360px; } } /style /head body div idchart/div script var chartDom document.getElementById(chart); var chart echarts.init(chartDom); var source [ [月份, 数码, 家电, 服饰, 美妆], [2024-01, 120, 86, 45, 30], [2024-02, 132, 92, 52, 35], [2024-03, 145, 90, 68, 42], [2024-04, 158, 102, 73, 48], [2024-05, 170, 115, 79, 55], [2024-06, 183, 126, 88, 61] ]; var option { backgroundColor: #fff, title: { text: 2024 年各品类季度销售趋势, left: center, textStyle: { fontSize: 16, fontWeight: bold } }, tooltip: { trigger: axis }, legend: { top: 40, type: scroll }, grid: { left: 10%, right: 5%, top: 80, bottom: 50, containLabel: false }, xAxis: { type: category, data: source.slice(1).map(function (item) { return item[0]; }), axisLabel: { interval: auto } }, yAxis: { type: value, axisLabel: { formatter: function (val) { return val.toLocaleString(zh-CN); } } }, series: [数码, 家电, 服饰, 美妆].map(function (name, index) { return { name: name, type: line, stack: total, smooth: false, symbol: circle, symbolSize: 6, areaStyle: {}, data: source.slice(1).map(function (row) { return row[index 1]; }) }; }) }; chart.setOption(option); window.addEventListener(resize, function () { chart.resize(); }); /script /body /html代码说明xAxis.axisLabel.interval: auto会自动计算标签密度避免文字重叠yAxis.axisLabel.formatter使用了toLocaleString(zh-CN)实现千分位分隔series使用循环生成方便后续新增品类时不用复制大量重复代码window.addEventListener(resize, ...)让图表在窗口变化时自适应移动端通过媒体查询降低图表高度保证在小屏上不出现内容挤压。用浏览器打开生成的 HTML 文件你会看到一张完整的堆叠面积图。如果你想用 Python 数据分析链路也可以把配置中的library改为matplotlibAI 会生成对应风格的 Python 脚本。5.4 使用六边形蜂窝图模板这次新增的六边形蜂窝图模板是更新中关注度比较高的功能它特别适合展示大量散点数据的密度分布。使用方式同样简单修改配置chart: type: hexbin library: echarts title: 用户活跃时段与时长分布 data: format: csv source: ./user-activity.csv hexbin: binSize: 12 color: #5B9BD5AI 生成时会自动把 x、y 轴数据映射到六边形网格通过颜色深浅表示不同网格的密度。这个模板对数据的分布趋势可视化效果非常直观适合处理经纬度、点击热区、用户行为密度等场景。6. 运行结果与效果验证生成图表后除了肉眼判断好不好看还应该按明确的标准验证结果。我建议按下面的顺序检查第一确认页面控制台有没有报错。打开浏览器开发者工具在 Console 面板查看是否有 JavaScript 异常。如果出现ECharts is not defined说明图表库没有正确加载需要检查 CDN 地址是否可访问。第二使用 skill 自带的输出格式。生成的 HTML 文件用浏览器打开后检查标题、图例、坐标轴标签是否完整。图例若超出可视区域需要检查legend.type是否设置成了scroll并确认 top 值是否给图例留出了空间。第三验证数据格式。将鼠标悬停在图表数据点上tooltip 显示的数值应带有千分位分隔符。如果没有检查配置项number_format.thousand_separator是否被后续代码覆盖。第四验证响应式效果。把浏览器窗口从宽屏拖到手机宽度图表应自动调整高度而不是出现横向滚动条或内容溢出。如果出现溢出优先检查grid的百分比预留是否合理。第五大数据量表现。如果你手头有超过 5000 条数据的文件建议用增量数据试一次。正常情况下 ECharts 在大数据量下依然能保持流畅如果明显卡顿检查配置中的performance.large_data_threshold是否触发以及是否启用了 canvas 渲染。7. 常见问题与排查思路在实际使用过程中用户反馈的问题主要集中在以下几个方面我整理成了一张排查表。问题现象可能原因排查方式解决方案Agent 没有识别到 skillskill 目录路径不对或文件名不匹配检查SKILL.md文件是否在正确目录名字是否准确按对应工具的规范调整目录重启 Agent 会话生成结果没有按配置文件执行配置项名称写错或 schema 校验失败用 schema 文件校验配置格式参考chart-config.schema.json修正配置字段图表无法加载CDN 图表库地址不可达打开浏览器 Network 面板确认请求是否成功切换到其他 CDN 或下载到本地引用X 轴标签重叠数据类目过多旋转角度不足检查x_label_rotation配置设置旋转角度为 30 或 45开启间隔自动计算tooltip 数值没有千分位格式化函数未生效检查 yAxis 和 tooltip 的formatter是否覆盖了默认逻辑统一通过配置文件中的数值格式规则控制中文乱码文件编码不是 UTF-8检查 CSV 和 HTML 文件的编码格式保存为 UTF-8 编码并在 HTML head 中声明 charset深色模式下文字看不清配色对比度不足检查主题配置和颜色代码设置theme: dark或调整配色中的文字颜色移动端布局溢出容器宽度设置不当检查 grid 百分比和 media query调整grid的 left/right 为百分比合理设置移动端高度如果你遇到“GitHub 克隆速度慢或失败”这通常是网络原因导致的。可以优先尝试在非高峰时段重新 clone或者到仓库页面下载 ZIP 包再手动解压到 skills 目录。不要在项目文件里保存任何需要绕过访问限制的额外工具配置保持开发环境的干净和安全。8. 最佳实践与工程建议这部分内容来自我在实际项目中的使用经验不针对某个特定场景但在大多数工程环境下都适用。8.1 按团队规范定制默认配置图表 skill 最值得投入的地方是把它和自己的团队规范结合。多数设计团队会有自己的配色、字体、间距和 Logo 规范。把规范沉淀到chart-config.yaml里以后团队所有成员通过 AI 生成图表时都会自动遵守统一规范不再需要每次口头沟通样式要求。例如你的团队主色调是品牌蓝#1677FF辅助色是橙色#FA8C16可以在配置文件中固定theme: primary_color: #1677FF secondary_color: #FA8C16 font_family: PingFang SC, Microsoft YaHei, sans-serif这样 AI 生成的每张图表在命名和配色上都会保持一致避免了反复调整的无谓沟通成本。8.2 用配置优先级管理“规范”和“例外”我见过一个常见误区为了让 AI 听自己的话把配置项写得非常细结果对话里临时要求的特例反而被配置锁死AI 怎么都不改。正确的做法是利用“配置优先、指令兜底”的机制。配置适合承接通用规则比如所有图表默认开启千分位、默认使用团队配色对话指令适合承接单次特例比如“这张图不要显示图例”“这张图用暖色调”。当指令和配置冲突时明确告诉 AI “本次以我的指令为准”它会跳过相关配置项。8.3 数据隐私和权限边界使用图表 skill 时数据文件会被当作上下文的一部分传给大模型。如果你的数据包含用户隐私、密钥、内部财务数据请一定注意脱敏。建议在传入数据之前做三件事去掉姓名、手机号、邮箱等直接标识字段用 mock 数据完成图表样式验证确认无误后再接入真实数据涉及内网数据时确认你的 Agent 工具运行在合规环境且没有把数据发送到非授权外部服务。8.4 成本控制控制上下文占用Skill 目录里的模板文件如果全部加载会占用不少 token。实际使用中多数对话只会用到一两种图表类型。为了控制成本建议按需裁剪模板目录只保留你常用的图表模板。比如你只做 ECharts 报表那就只保留templates/echarts/的内容删除其他图表库的模板。9. 总结与后续学习方向这次图表 skill 的大更新核心是把“AI 画图”这件事从不可控的碰运气变成了有标准、有配置、有自检的工程化流程。你不再需要每次反复调整 prompt而是通过一份配置文件就能让 AI 输出接近专业水准的可视化代码。无论是 Claude Code、Codex 还是 Cursor接入方式都已经统一成“放目录、改配置、发指令”三步。如果你还没有用过这个 skill下一步建议从一个最小场景开始拿一份你自己手头的数据配好chart-config.yaml让 AI 生成一张你最常用的图表类型然后对照本文的验证清单检查输出。跑通一次之后再逐步尝试六边形蜂窝图、桑基图等新图表以及按团队规范定制默认配置。图表可视化的难点从来不在于图表的 API而在于对数据和视觉规范的判断力。skill 的意义在于把这种判断力从人的脑子里复制到 AI 的执行流程里。后续我会继续往这个方向推进后面计划补充更多图表类型的模板以及针对数据大屏场景的性能优化方案。如果你在安装或使用中遇到了配置文件校验不过、图表类型模板加载不到等问题先对照上面的排查表走一遍大部分问题都能定位到具体环节。