explain-visually
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseExplain Visually
可视化解释
The goal: the reader quickly understands what changes, how it works and why, and can decide, without reading
every line of code. Show rather than tell, concise first, details on demand. One page, ~1,000–1,500 words:
short story steps, and the detail a decision needs in the option rows and toggles.
Say exactly what the facts say, above all in the headline:
- "Migrated" is not "kept" or "working"; "honoured" is not "unchanged". Name exceptions in the same sentence: "263 rules migrate; 1 must be switched off".
- A number measured under changed conditions is not "the same": "5.3 s, after switching that rule off".
- What holds for some members doesn't hold for the group: name them ("react-x and react-jsx load as plugins").
- Write for a reader new to the tools: gloss each tool or term the first time it appears, in a few words in the same sentence ("tsgolint, Oxc's type-checking helper"), in the story and in option rows alike.
The look comes from the skill; each chapter follows its skill.
explainer-kitexplain-with-*目标:让读者无需逐行阅读代码,就能迅速理解哪些内容发生了变化、其运作方式及原因,并据此作出决定。少讲道理,多做展示;先呈现简洁内容,细节按需提供。篇幅控制在一页,约 1,000–1,500 词:通过简短的故事步骤展开,并将决策所需细节放在选项行和切换项中。
准确表述事实所说明的内容,尤其要体现在标题中:
- “已迁移”不等于“已保留”或“可正常工作”;“已遵循”不等于“未更改”。要在同一句话中指出例外:“263 条规则会迁移;其中 1 条必须关闭”。
- 在条件改变后测得的数值不能称为“相同”:“关闭该规则后为 5.3 秒”。
- 仅对部分成员成立的情况并不适用于整个群体:应明确列出这些成员(“react-x 和 react-jsx 作为插件加载”)。
- 面向初次接触这些工具的读者写作:每个工具或术语首次出现时,都要用同一句话中的几个词作简短解释(“tsgolint,Oxc 的类型检查辅助工具”),故事和选项行均应如此。
视觉效果来自 skill;每个章节都遵循对应的 skill。
explainer-kitexplain-with-*Use this skill when
何时使用此 skill
- The user asks for a visual explanation, an explainer or "explain this visually".
- Explaining a code change, a proposal, a plan or an architecture decision so the user can make informed decisions.
- 用户要求可视化解释、说明文档或“以视觉方式解释”。
- 解释代码变更、提案、计划或架构决策,使用户能够作出明智的决定。
1. Gather/research information/facts into facts.md
facts.md1. 将信息/事实收集并整理到 facts.md
facts.md- If a facts file already exists (e.g. the task gives you one), it is your source of truth: skip to step 2.
- Research the facts/topics using up to 3 concurrent subagents.
- Output each fact; one line with its source (, link, or the command you ran). Don't restate facts in your thinking; write them down once.
file:line - Get numbers from commands (,
grep -c, a timed run), not by counting by hand.jq - Measure on the real repo when it is cheap (a scratch copy or worktree, never the repo itself). Note method and versions. Never stretch one measurement into "every" or "all".
- Budget: stop when every claim you plan to make has a source.
- Output each fact; one line with its source (
- You, as an orchestrator, combines the research into .
facts.md - Note what the user must decide, the effort per option, the risks with their fixes, and what would change the recommendation.
- 如果已提供 facts 文件(例如任务中给出了该文件),它是唯一事实来源(source of truth):跳至第 2 步。
- 最多可使用 3 个并发 subagent 收集事实/主题信息。
- 每条事实单独写一行,并附上来源(、链接或你运行的命令)。不要在思考中重复陈述事实;只写一次。
file:line - 通过命令获取数字(、
grep -c、计时运行),不要手动计数。jq - 如果成本不高,在真实 repo 中进行测量(使用临时副本或 worktree,绝不要直接操作 repo 本身)。记录方法和版本。绝不可将一次测量泛化为“每个”或“全部”。
- 预算:当计划作出的每项声明都有来源时即停止。
- 每条事实单独写一行,并附上来源(
- 作为 orchestrator,你负责将研究结果整合到 。
facts.md - 记录用户必须决定的事项、每个选项的工作量、修复方案的相关风险,以及哪些变化会改变推荐结论。
2. Plan the page (no separate brief)
2. 规划页面(无需单独的 brief)
Write the plan as the first lines of (≤ 15 lines): the one-sentence answer and its main cost, the 3–5
key numbers (each gets one home on the page), the 4–8 terms to gloss, the one real snippet to show (config or
code the reader would change, ≤ 8 lines), and one line per chapter. Chapters:
notes.md| Chapter | Built with | Section | When |
|---|---|---|---|
| Overview | this skill (kit overview) | — | always |
| Story | | | always: 5–7 steps, one evolving graphic |
| Code | | | only when the change is code the reader must see |
| Decision | | | when the user has something to decide |
- At most 3 chapters after the overview. Fragility, dependencies and complexity go into the decision options'
rows (keeps / loses / fix first / risks), not into chapters of their own. A separate before/after chapter
() only replaces Code when there is no decision.
explain-with-preview - Overview: a headline that states the answer and its main cost ("lint 44 s → 5.3 s; 1 rule and 3 checks to
port"), one sentence, one hero (to scale; for
numbers use the kit's HTML , which stays legible on phones), and one key line with at most one "Decide" callout. No grid of info boxes.
ev-bars ev-bars--hero - Only add ,
explain-with-section-clipsor-slideswhen the user asks for them.-video
将计划写在 的开头几行(≤ 15 行):包括一句话答案及其主要成本、3–5 个关键数字(每个数字在页面上只出现一次)、需要解释的 4–8 个术语、一段要展示的真实代码片段(配置或读者需要修改的代码,≤ 8 行),以及每个章节一行。章节如下:
notes.md| 章节 | 构建方式 | 区块 | 使用条件 |
|---|---|---|---|
| 概览 | 此 skill(kit overview) | — | 始终 |
| 故事 | | | 始终:5–7 个步骤,一个逐步演变的图示 |
| 代码 | | | 仅当变更本身就是读者必须查看的代码 |
| 决策 | | | 当用户需要作出某种决定时 |
- 概览之后最多只能有 3 个章节。脆弱性、依赖关系和复杂度应放入决策选项的各行(保留项 / 损失项 / 优先修复 / 风险),不应单独设章。单独的“之前/之后”章节()仅在没有待决策事项时替代代码章节。
explain-with-preview - 概览: 标题应说明答案及其主要成本(“lint 44 秒 → 5.3 秒;需移植 1 条规则和 3 项检查”),包含一句话、一个可缩放的 hero 区块(对于数字,使用 kit 的 HTML ,以确保在手机上仍清晰易读),以及一行关键信息,其中最多包含一个“Decide”提示框。不要使用信息卡片网格。
ev-bars ev-bars--hero - 仅当用户明确要求时,才添加 、
explain-with-section-clips或-slides。-video
3. Build the chapters yourself
3. 自行构建各章节
- Read and the chapter skills you use, all in one turn. The contract is the whole API: never read
explainer-kit/assets/FRAGMENT-CONTRACT.md,kit.css,kit.jsorassemble.pyfor this page.SCRIPTS-AND-TABS.md - Write the chapters yourself, one file each, in order, each with the Write tool (never a shell heredoc: one stray quote fails the whole command and every file has to be written again). Don't start subagents for a page this size.
- Use kit components as they are; no new themes, fonts or components, and no layout CSS of your own.
- Show the real snippet from your plan as the recommended option's in the decision JSON (and the cautious option's, if it changes config), not as a chapter of its own.
code - References go in the details: file paths in code headers, links in the decision's Sources toggle.
- 在一轮操作中,同时读取 和所用的章节 skill。该契约就是完整的 API:绝不要读取
explainer-kit/assets/FRAGMENT-CONTRACT.md、kit.css、kit.js或assemble.py,它们不用于构建此页面。SCRIPTS-AND-TABS.md - 自行编写各个章节,按顺序每个章节写一个文件,并使用 Write tool 分别写入(绝不要使用 shell heredoc:一个多余引号就会导致整条命令失败,所有文件都必须重新写入)。对于这种规模的页面,不要启动 subagent。
- 按原样使用 kit 组件;不要引入新的主题、字体或组件,也不要编写自己的布局 CSS。
- 将计划中的真实代码片段作为决策 JSON 中推荐选项的 展示(如果它会更改配置,也作为保守选项的
code展示),不要单独为其设置章节。code - 引用资料放在详情中:文件路径放在代码标头中,链接放在决策部分的 Sources 开关中。
4. Assemble, check once, publish
4. 组装、检查一次并发布
bash
python <kit>/assets/preview.py decide.json --out frag-decide.html
python <kit>/assets/assemble.py --page --toc --title "Short name" --overview overview.html \
--section story=frag-story.html --section decide=frag-decide.html --out index.html
python <kit>/assets/check.py index.html- Run these only after every file write has returned, as one chained command.
- Fix the contract errors the assembler reports.
- Run once. Fix only the problems it lists, run it once more, then stop. Don't take or study screenshots to hunt for other issues and don't write your own browser scripts.
check.py - Read your page text once against : counts, names, no "every/all" the facts don't support.
facts.md - Publish the single page as an artifact (unless told to just write the file). Reply in at most 5 lines: the answer, the page path, and anything unchecked.
bash
python <kit>/assets/preview.py decide.json --out frag-decide.html
python <kit>/assets/assemble.py --page --toc --title "Short name" --overview overview.html \
--section story=frag-story.html --section decide=frag-decide.html --out index.html
python <kit>/assets/check.py index.html- 只有在每次文件写入都成功返回后,才使用一条串联命令运行上述命令。
- 修复组装器报告的契约错误。
- 只运行一次。修复它列出的问题后再运行一次,然后停止。不要截取或研究屏幕截图来寻找其他问题,也不要编写自己的浏览器脚本。
check.py - 对照 通读页面文本一次:检查计数和名称,确保没有使用
facts.md未支持的“每个/全部”表述。facts.md - 除非用户要求只写入文件,否则将单页发布为 artifact。回复最多 5 行:结论、页面路径以及未检查项。