| name | html-effectiveness |
| description | 让 agent 用单文件 HTML 替代 markdown 输出空间性、并行性、可比较或可交互的内容。当用户请求"对比/计划/评审/报告/解释器/幻灯片/编辑器/可视化"或当输出含并排选项、流程图、时间线、代码 diff、可交互元素、需要"指着某处说就是它"的场景时使用。本 skill 是路由器：先用决策框架判断是否走 HTML，再按 9 大类调度对应的子 skill（01-explore / 02-review / 03-design / 04-proto / 05-diagram / 06-slides / 07-research / 08-report / 09-editor），并复用 ../templates/*.html 与 shared/base.css 输出真实可运行的产物。 |
html-effectiveness — 主路由
Markdown 把所有信息压成线性文字流。diff 是空间的、对比是并排的、流程是图状的、交互是可感受的——这些维度被 markdown 抹平后，人需要在脑中重建它们。HTML 是 agent 真正的画布。
灵感来自 Thariq Shihipar 的 The unreasonable effectiveness of HTML。本 skill 把 9 大类 20 个范式系统化为可复用的决策框架 + 模板。
第 1 步：形状测试（决定要不要走 HTML）
读完用户请求后，对答案做"形状测试"：
| 答案的形状 | 用什么 |
|---|
| 一段陈述、一个数字、一句结论 | 直接说 |
| 几个步骤、要点列表、单一代码片段 | markdown |
| 2+ 选项要并排比较（方案、设计、文案） | HTML |
| 空间关系（架构图、流程图、依赖、调用栈） | HTML（含 SVG） |
| 结构化文档（PR 写作、状态报告、事故报告、计划） | HTML |
| 可交互（滑块调参、拖拽分组、键盘翻页、live preview） | HTML |
| 需要导出回 agent（用户在 UI 改完结果要复制回来） | HTML（必带"复制"按钮） |
| 代码 diff + 注释 + 风险标记同时存在 | HTML |
| 概念需要"看到"才能懂（哈希环、token bucket、状态机） | HTML（含 SVG/canvas） |
判断更具体的边界案例见同目录下没有但需要时可读的../examples（已并入下方各子 skill 的"何时用"章节）。
第 2 步：路由到子 skill
命中 HTML 路径后，从下面 9 大类中选最匹配的一个，读取对应子 skill 的 SKILL.md 文件继续执行。每个子 skill 包含：详细使用场景、空间形状分析、HTML 骨架、关键代码片段、对应的 ../templates/*.html。
第 3 步：执行（每个子 skill 的标准流程）
子 skill 内部统一遵循这个流程：
- 读 对应的
../templates/{name}.html（如有）作为骨架
- 嵌 真实内容（不要
Lorem ipsum、不要 User A，要具体场景 + 真实姓名 + 真实数字）
- 检 6 项产出约束（见下）
- 写 到工作区（永远在工作区内，不写
~/Downloads/ / 不写 user home / 不写 /tmp/）—— 见下面"输出位置"小节
- 告 用户相对工作区的路径与打开方式（
xdg-open / wslview / open / 双击）
输出位置（强制约定）
唯一规则：所有 HTML 输出都写到当前工作区里。 不污染用户的 Downloads、不写 /tmp/、不写 home 目录。
工作区根目录 = 用户当前 IDE / shell 打开的项目根（含 .git/ 的目录，或 agent 启动时的 cwd）。下文中 <ws> 代表它。
默认目录：<ws>/.agent-html/
所有"一次性消费"的产出——临时对比、视觉风格探索、组件变体、动画沙盒、可点击流、PR 评审视图、模块图、概念解释器、所有编辑器小工具——都默认写到：
<ws>/.agent-html/{slug}-{YYYYMMDD-HHmm}.html
slug 是简短英文标识符：debounce-compare、auth-flow、task-card-anim、cycle-14-triage 等- 时间戳避免覆盖同名前作
- 把
.agent-html/ 加进 .gitignore（仓库自带的 .gitignore 已包含此项），avoid 误提交
每个子 skill 的默认位置：
| 子 skill | 默认位置 |
|---|
| 01-explore: compare / 视觉方向 | <ws>/.agent-html/compare-{slug}-{ts}.html |
| 02-review: diff (reviewer) / 模块图 | <ws>/.agent-html/review-{slug}-{ts}.html |
| 03-design: 组件变体 | <ws>/.agent-html/variants-{component}-{ts}.html |
| 04-proto: 动画沙盒 / 可点击流 | <ws>/.agent-html/proto-{slug}-{ts}.html |
| 05-diagram: 流程图 / SVG 插图 | <ws>/.agent-html/diagram-{slug}-{ts}.html |
| 07-research: 概念解释器 | <ws>/.agent-html/concept-{topic}-{ts}.html |
| 09-editor: 拖拽板 / flag / prompt-tuner | <ws>/.agent-html/editor-{slug}-{ts}.html |
例外：有"长期价值"的产出，提议升级到工作区文档目录
下面这几类产出会被人反复回看或进 PR/Wiki——agent 应该提议把它们写到工作区的标准文档目录，而不是 .agent-html/。提议时给出两个明确选项让用户选：
| 子 skill / 模板 | 提议位置（首选 → 备选） | 文件名 |
|---|
| 01-explore: plan (实现计划 / RFC) | <ws>/rfcs/ → <ws>/docs/rfcs/ → <ws>/.agent-html/ | {NNNN}-{slug}.html |
| 02-review: PR writeup (作者侧) | <ws>/docs/prs/ → <ws>/.agent-html/（更常见做法是直接粘贴到 GitHub PR description） | pr-{NNN}-{slug}.html |
| 03-design: design tokens | <ws>/docs/design/ → <ws>/.agent-html/ | tokens.html |
| 05-diagram: 架构 flowchart / 配图 | <ws>/docs/architecture/ → <ws>/docs/figures/ → <ws>/.agent-html/ | {slug}.html |
| 06-slides: deck | <ws>/docs/slides/ → <ws>/.agent-html/ | {date}-{topic}.html |
| 07-research: feature explainer | <ws>/docs/explainers/ → <ws>/.agent-html/ | {feature}.html |
| 08-report: status | <ws>/reports/status/ → <ws>/docs/status/ → <ws>/.agent-html/ | {YYYY-WW}.html |
| 08-report: postmortem | <ws>/postmortems/ → <ws>/docs/postmortems/ → <ws>/.agent-html/ | INC-{id}-{slug}.html |
路径选择决策树
用户请求 → 选目录的判断顺序：
1. 用户在 prompt 里指定了路径？ → 用用户指定的，结束
2. 工作区里已经有同类目录？ → 用现有的（保持仓库结构一致）
例：已有 docs/rfcs/ → plan 写这里
3. 上表里这类产出有"首选 → 备选"？ → 提议首选（如果不存在就 mkdir -p）
4. 否则 → .agent-html/{slug}-{ts}.html
第 2 步的"已有目录"检测：在执行前用 ls/Glob 检查 <ws>/{docs,rfcs,reports,postmortems}/ 是否存在，如已存在就直接用，不要在工作区里创建第二个并列名字的目录（比如已有 rfcs/ 就别再开 docs/rfcs/）。
报告给用户
写完后总是给一个简短的两行确认：
✓ Saved to .agent-html/compare-debounce-20260514-1103.html (relative to /home/you/proj)
Open: xdg-open .agent-html/compare-debounce-20260514-1103.html
或在 WSL 上：
Open: wslview .agent-html/compare-debounce-20260514-1103.html
路径优先用工作区相对形式——便于用户复制到 IDE 里直接 Cmd+Click 打开。完整绝对路径只在第一行尾部用括号附注。
6 项产出约束（每个 HTML 输出都必须满足）
- 单文件自包含 — HTML/CSS/JS/SVG 全内联，不依赖 CDN（可以从
shared/base.css 复制 token，但要内联进 <style>）
file:// 可运行 — 不需要 server，不需要 build，不调外部 API- 现代但克制 — system font 栈、暖色调（来自
shared/base.css）、克制动画
- 真实内容 — 禁占位符；用具体场景：
comments.create p99 1.4s → 180ms，不写 latency improved
- 编辑器必带导出 — 任何让用户操作的 HTML 必须有"复制为 markdown / Copy diff / Copy prompt"按钮，让 UI 状态能回到 agent
- 桌面响应式 — 1280px 笔记本和 1920px 外接显示器都看得舒服；不强求手机端
共享资源
shared/base.css — 通用 CSS baseline（CSS 变量 / 字体 / 配色 / 间距 / 组件）。生成新模板时把这份内联到 <style> 里shared/components.html — 常用 HTML 片段库：badges、cards、buttons、SVG arrow markers、diff lines、KPI tiles、carryover items 等
反模式（不要做）
| 错误做法 | 正确做法 |
|---|
| 用 markdown 表格放 4 列方案对比 | 走 01-explore，用 compare.html |
| 用 ASCII art 画流程图 | 走 05-diagram，用内联 SVG |
| 引用 Tailwind / shadcn / Chart.js CDN | 内联 CSS，从 shared/base.css 复制需要的部分 |
用 Lorem ipsum / User A, User B | 用具体场景 + 真实姓名 + 真实数字 |
| 编辑器没有"复制结果"按钮 | 永远带导出按钮，把 UI 状态变成可粘贴文本 |
| 输出 HTML 后用户找不到文件 | 总是给"工作区相对路径 + 打开命令"两行 |
写到 ~/Downloads/ / /tmp/ / user home / 任何工作区外 | 永远写工作区——默认 <ws>/.agent-html/，长期价值的提议升级到 docs/ rfcs/ reports/ postmortems/ |
在工作区已有 rfcs/ 时还另建 docs/rfcs/ | 先 ls 检测已有目录，复用，不并列 |
| 不读子 skill 直接拍脑袋写 | 命中类别后先读 01-09/*/SKILL.md 再动手 |
元信息
