让你的AI Agent自动画文本图表:mdxcn SKILL.md安装与使用教程
让你的AI Agent自动画文本图表:mdxcn SKILL.md安装与使用教程
mdxcn 是一个免费开源的文本图表组件库,专为 MDX 打造的 callouts、steps、terminal、charts 和 timelines。只需把它的 SKILL.md 放进你的 AI Agent 技能目录,Cursor、Claude Code、Codex 等 Agent 就能在写文档时自动画出带边框的 ASCII 文本图表——时间线、流程图、甘特图、进度条,全部是纯文字,README 和 GitHub 里直接可读。本教程带你在 3 分钟内完成安装并上手使用。
SKILL.md 是什么:让 Agent "会画图"的说明书
普通 AI Agent 写文档时,要么堆砌冗长列表,要么随手画一个歪歪扭扭的 SVG。mdxcn 的 SKILL.md 解决的就是这个问题:
- 何时画图:Agent 会先判断"这句话是否值得一张图"。一句话能说清就不画;有路径、有时间线、有对比、有数据,才动手。
- 画哪种图:内置一张"选择器"对照表(chooser),什么场景配哪个组件一目了然。
- 用什么格式:在 MDX 里写 Markdown 子内容,在 Comark 应用里写
::graph-*块,在 Knap 模板里用graph_*过滤器,在 README/GitHub/Linear 里粘贴官方围栏 ASCII。
完整技能文件只有两个,都位于 skills/mdxcn/ 目录:
| 文件 | 作用 |
|---|---|
| SKILL.md | 核心规则:何时画图、选哪个组件、输出什么格式、禁止事项 |
| recipes.md | 带真实数据的完整示例(Refactor、Incident、PR 复盘等),Agent 照着抄 |
Agent 加载 SKILL.md 的方式是"描述匹配":当任务里提到"写一份 README、解释一次重构、复盘一次事故",或涉及 ASCII diagrams、GraphTimeline、Comark、Knap 等关键词时,技能自动生效。
一键安装步骤:把 SKILL.md 放进 Agent 的技能目录
仓库是只读的,安装只是"复制两个文件",不会修改仓库内容。
第 1 步:克隆仓库
git clone https://gitcode.com/gh_mirrors/md/mdxcn
第 2 步:复制到你的 Agent 技能目录
不同 Agent 读取的目录不同,项目内置的安装逻辑(见 lib/docs/skill.ts 与 skill-install.tsx)支持这 4 种:
| Agent | 项目级目录(随仓库提交,团队共享) | 个人级目录(只在你机器上) |
|---|---|---|
| Cursor | .cursor/skills/mdxcn |
~/.cursor/skills/mdxcn |
| Claude Code | .claude/skills/mdxcn |
~/.claude/skills/mdxcn |
| Codex | .agents/skills/mdxcn |
~/.agents/skills/mdxcn |
| OpenCode | .opencode/skills/mdxcn |
~/.config/opencode/skills/mdxcn |
以 Cursor 项目级安装为例:
mkdir -p .cursor/skills
cp -R mdxcn/skills/mdxcn .cursor/skills/mdxcn
💡 团队项目推荐项目级安装:提交进仓库后,每位成员的 Agent 都会自动带上这套画图技能。
第 3 步(可选):让图表在你的 React 站点里渲染
SKILL.md 本身不含图表组件。如果你的站点运行 React/MDX,还需要用 shadcn CLI 把组件源码拷进项目(组件落地在 @/registry/default):
pnpm dlx shadcn@latest add https://mdxcn.dev/r/all.json
只装单个组件时,把 all 换成 slug(如 graph-table)。纯 README / 纯 Markdown 场景不需要这一步——Agent 直接输出官方围栏 ASCII。
使用教程:一句话 Prompt 让 Agent 自动配图
安装完成后,正常给 Agent 派活即可,记得点一句"用 mdxcn"。以下是官方示例(来源 lib/docs/skill.ts)中最好用的几条:
场景 1:写重构方案(Flow + Timeline 组合)
We're moving session checks out of route handlers into middleware.
Write a short plan for the team.
Use mdxcn for the before/after request path and the week-by-week
rollout. Prose between the two figures. Don't draw SVG.
场景 2:事故复盘(Timeline + Uptime 组合)
Draft a tight postmortem: p95 crossed 800ms at 14:02, we rolled back
the cache flag at 14:11.
Use mdxcn: a timeline of the night, then the days users felt it.
No SVG.
场景 3:给 README 加发布章节(纯 ASCII,无需 React)
Add a launch section to the README. It's a .md file, no React.
Use mdxcn: a punch list plus a grouped table. Paste the official
fenced ASCII. Don't paste JSX.
Agent 的输出长这样——先 1-3 句结论,再一张图,中间是文字:
+---------------- [ NIGHT ] ----------------+
| |
| ● 14:02 p95 crossed 800ms |
| │ |
| ● 14:11 rolled back the cache flag |
| │ |
| ○ 14:40 write the postmortem |
| |
+-------------------------------------------+
这就是 mdxcn 最妙的地方:图还是文件里的纯文本。Agent 下次改文档时,可以直接读出标签和数值来编辑,而不是对着截图猜。
图表选择速查:Agent 内置的 Chooser 对照表
SKILL.md 里最值钱的就是这张"什么内容配什么图"的对照表(节选自 SKILL.md 的 Chooser 部分):
| 你要写的内容 | Agent 会选的图表 |
|---|---|
| 请求路径 / 重构前后 | GraphFlow + GraphTimeline |
| 事故复盘 / 事后报告 | GraphTimeline + GraphUptime |
| A vs B 选型对比 | GraphCompare(+ 体积相关时加 GraphRank) |
| PR 改了什么 | GraphDiff + GraphSlope |
| 本周并行任务 | GraphGantt + GraphStat |
| 迁移进度 | GraphMeter + GraphKpi |
| 决策记录 / ADR | Decision + GraphScore |
| 嵌套文件 / 组织结构 | GraphTree |
| 操作步骤 | Steps |
| 注意事项 / 警告 | Callout |
数据型场景也有对照:少量数字用 GraphSpark,需要 y 轴用 GraphPlot,0 到 1 的进度用 GraphMeter,实际值 vs 目标值用 GraphBullet,占比用 GraphStack(注意:规则里明确禁止饼图)。
⚠️ GitHub / README / Linear 这类不能跑 React 的地方,Agent 只会粘贴有围栏 ASCII 版本的图表;Flow、Plot、Heatmap、Timer 等没有纯文本版的会被自动跳过。
使用规则:4 条铁律保证输出质量
SKILL.md 的"Rules / Do not"部分(SKILL.md)把质量控制写进了技能本身:
- 每节最多 2 张图,图与图之间必须有文字,绝不堆"图墙"。
- 禁止自造图表:不画 SVG、Mermaid、Recharts、canvas,也不手写 ASCII——只能复制官方围栏图再改标签。
- 标题 1-2 个词、大写(渲染为
[ TITLE ]),标签用小写朴素名词(auth middleware而非AuthMiddleware Layer)。 - 不改边框样式:边框风格通过
frame="corners" | "rule" | "none"属性切换,不额外加边框或圆角卡片。
相关文件导读:深入 mdxcn 的技能体系
| 路径 | 说明 |
|---|---|
| skills/mdxcn/SKILL.md | Agent 加载的核心技能文件(选择器 + 规则 + 示例 Prompt) |
| skills/mdxcn/recipes.md | 带真实数据的完整写作配方(JSX 版) |
| lib/docs/skill.ts | 支持的 Agent 列表、选择器数据、官方 Prompt 文案 |
| app/skill.md/route.ts | 站点路由:把 SKILL.md 原文作为 Markdown 响应输出 |
| app/llms.txt/route.ts | 站点路由:输出选择器 + 所有格式的图表指南 |
| app/agents/page.tsx | "for agents" 页面:Agent 写图、读图的完整故事 |
总结
mdxcn SKILL.md 的安装成本只有两条命令:clone + cp。换来的是 AI Agent 写作能力的显著升级——重构方案自带前后路径图,事故复盘自带时间线和可用性面板,README 里直接嵌入官方围栏 ASCII。图是纯文本,Agent 下次还能读出来改标签。
如果你常用 Cursor 或 Claude Code 写项目文档,这套"免费、开源、Agent 原生"的文本图表技能,值得今天就装进技能目录。

