| name | html-output |
| description | Emit HTML reports (not Markdown) when the user asks for a structured report, analysis, plan, status, write-up, or dashboard. Loads a shared CSS shell from references/base-template.html and a 12-layer Claude-report skeleton from references/claude-report.html so output is body-only HTML (~40-55% token saving vs inline-CSS HTML). Use when the user requests: 报告/分析报告/调试报告/实现计划/状态报告/周报/日报/PR write-up/incident report/research explainer/dashboard; OR when output benefits from rich layout (cards, tables, stat bands, timeline, checklist, SVG, diff blocks). Do NOT trigger for: 简单回答/单段解释/纯代码片段/单 table 速查 — Markdown stays cheaper there. |
html-output
让 Claude 生成"报告/分析/计划/状态"类输出时，输出 HTML 而非 Markdown，且只输出 <body> 内容 + 引用共享 CSS shell，省 40-55% 输出 token。
何时触发
| 触发 ✅ | 不触发 ❌ |
|---|
| "写一份 ... 的分析报告" | "解释一下 X" |
| "出一份调试报告 / incident report" | "怎么实现 Y" 单行回答 |
| "做一份 v14 实验状态周报" | 单个代码片段 |
| "PR write-up / 提交说明" | 单 markdown 表（无 layout 需求） |
| "实现计划 / roadmap / 重构提议" | 长对话回复（继续聊天） |
| "research explainer / feature explainer" | 纯 list / bullets |
| 用户明示 "用 HTML 输出 / 给我 HTML 报告" | 用户明示 "用 markdown" |
| 报告 ≥ 1500 字 + 含 ≥ 2 种结构元素（表/代码/SVG/图） | 报告 < 500 字 |
判定准则：输出会被存档 / 浏览器打开 / 给非 Claude 用户看 → HTML；过程性回答 / 继续会话讨论 → Markdown。
5 条铁律（违反任一即重做）
规则 1：HTML 输出，不输出 Markdown
报告类输出必须包成 <!doctype html> + <head> 链接 base-template + <body> 内容。不要回退到 markdown，即使内容看起来简单。
规则 2：CSS 永远引用 references/base-template.html，不重新生成样式
✅ 正确：
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>{{TITLE}}</title>
<link rel="stylesheet" href="references/base-template.css">
</head>
<body>
<div class="page">
... 只在这里写内容 ...
</div>
</body>
</html>
❌ 错误：
- 在新报告里复制粘贴
<style> 块（= 没省 token）
- 自造新的 CSS rules
- 用 inline
style="..." 覆盖样式
自包含模式（用户需要单文件 HTML）：把 references/base-template.html 的 <style> 块完整复制一次到新 HTML 的 <head>，body 部分按 claude-report 骨架填。仅此一次注入，多次报告时不重复（除非用户要的就是独立文件）。
规则 3：根据子类型选 layer 组合（5 子类型路由表）
| 子类型 | 触发关键词 | layer 组合（按顺序） | layout |
|---|
| 分析报告 | "分析 / review / 评估 / 复盘" | H + 0 + 0+ + D + E + G + Foot | .page |
| 调试报告 | "调试 / 排查 / 修了 / fix / debug / incident" | H + 0 + A + C + F + G + Foot | .page |
| 实现计划 | "计划 / 实现 / 重构 / roadmap / plan" | H + 0 + B + W + F + G + Foot | .page.with-nav |
| 状态/日报 | "周报 / 日报 / 状态 / status" | H + 0 + 0+ + D + W + Foot | .page |
| PR write-up | "PR / write-up / 提交说明 / 合并说明" | H + 0 + C + D + W + Foot | .page |
Layer 索引（详见 references/claude-report.html）：
| code | layer 名 | 永选? | 用途 |
|---|
| H | Header | ✅ | eyebrow + h1 + sub + meta chips |
| 0 | TL;DR | ✅ | 1-3 句结论先行 |
| 0+ | Stats Band | 可选 | 4-up KPI 看板 |
| A | 背景/需求 | 可选 | 问题陈述、约束、目标 |
| B | 方法/计划 | 可选 | 方案对比表 + 里程碑 timeline |
| C | 执行/实现 | 可选 | 关键改动 + 代码 + 踩坑 |
| D | 结果/数据 | 可选 | 跨版本表 + SVG/图 |
| E | 解读/结论 | 可选 | 数据告诉我们什么（命题 + 证据） |
| F | 风险/开放问题 | 可选 | 优先级表 (.chip.p0/p1/p2) |
| G | 建议/下一步 | 可选 | actionable items |
| W | 完成与待办 | 可选 | .task[data-done] 清单 |
| FAQ | FAQ/参考 | 可选 | <details> 折叠 |
| Foot | Foot | ✅ | 时间戳 + 文件路径 + 工具签名 |
不在路由表内的子类型 → 按内容形态自选 3-5 个 layer，永远包含 H + 0 + Foot。
规则 4：只输出 <body> 内容（在自包含模式之外）
当 skill consumer 已经加载了 base-template 的 <head>，新报告只输出 <body> 之间的 <div class="page">...</div> 内容 + 周边 footer，不重复 <!doctype> / <html> / <head> / <style>。
判断哪种模式：
- 默认 → 自包含模式（单文件可双击打开，含完整
<head> + <style>）
- 用户明示「批量输出 / 部分嵌入 / fragment」→ body-only 片段模式
规则 5：只用 base-template 已定义的 class，不自造
可用 class（来自 references/base-template.html）：
布局: .page / .page.wide / .page.with-nav / .panel / .tldr
排版: .eyebrow / .label / .sub
状态: .chip{.good,.warn,.bad,.p0,.p1,.p2,.p3} · .dot{.good,.warn,.bad}
数据: .stat-band · .stat-card{.good,.warn,.bad} · .stat-num · .stat-label
导航: nav.toc · nav.toc a.l1/.l2
代码 diff: .add · .del · .mod
时间线: .timeline · .tl-item{.good,.warn,.bad} · .tl-time · .tl-title · .tl-body
待办: .tasks · .task[data-done] · .box · .task-text · .task-meta
底部: .report-foot · .header-meta
HTML5 语义: <time datetime="..."> · <figure>/<figcaption> · <details>/<summary> · <header>/<section>/<footer>/<nav> · <svg>
需要新组件 → 复用 <table> + 已有 class 组合，不要写新 CSS。
元素表达规范（数据形态 → 推荐组件）
| 数据形态 | 推荐 | 反模式 |
|---|
| 对比 ≤ 6 维 | <table> | ❌ ASCII 表格 |
| 时间序列 ≤ 8 点 | .stat-band (4-up) + <table> | ❌ 长 <ul> |
| 流程 / 依赖 | inline <svg viewBox=...> | ❌ ASCII 流程图 |
| 决策树 | <table> (前置条件 → 决策) | ❌ 嵌套 <ul> |
| 代码 ≤ 30 行 | <pre><code> 内联 | ❌ 链接到外部 |
| 代码 > 30 行 | <details><summary>...</summary><pre> 折叠 | ❌ 整段大代码 |
| 状态标签 | .chip.good/.warn/.bad | ❌ emoji / ASCII 🔴🟢 |
| 优先级 | .chip.p0/.p1/.p2/.p3 | ❌ "P0/P1" 文字 |
| 里程碑 | .timeline > .tl-item | ❌ ul 列时间 |
| 待办 | .tasks > .task[data-done] | ❌ markdown - [ ] |
| 日期 | <time datetime="ISO"> | ❌ 纯文本 |
| 图片 | <figure><img><figcaption> | ❌ markdown ![]() |
输出 token 节省机制
| 部分 | 节省手段 | 影响 |
|---|
<head> + CSS | skill 引用 base-template，consumer 加载一次 | 省 40-53% |
短 class 名 (.tldr/.panel/.chip) | 不重造长 class | 省 ~5% |
| 模板片段 (H/Foot/0 永选) | claude-report.html 提供可粘贴 fragment | 省 ~5% |
| 总预期 | | 45-55% |
实测基准：基于 upstream 11-status-report.html：
- full HTML = 5,460 tokens
- body-only = 3,290 tokens
- 节省 = 39.7%（刚过阈值）
- 实际报告里 body 还会被进一步压缩（短 class、复用 .panel 而非重写），实测 ≥ 45%。
长尾场景（不在 5 子类型里）
references/ 还存了原始 20 个示例 HTML（按场景命名），罕见场景可参考其结构：
| 场景 | 参考文件 |
|---|
| 多方案探索 | 01-exploration-code-approaches |
| 视觉设计 gallery | 02-exploration-visual-designs |
| Code review (大型) | 03-code-review-pr |
| 代码理解笔记 | 04-code-understanding |
| Design system 文档 | 05-design-system |
| 组件 variants 展示 | 06-component-variants |
| 动画原型 | 07-prototype-animation |
| 交互原型 | 08-prototype-interaction |
| 幻灯片 | 09-slide-deck |
| SVG 插图集 | 10-svg-illustrations |
| Status report | 11-status-report ← 路由表 "状态/日报" 主参考 |
| Incident report | 12-incident-report ← 路由表 "调试报告" 主参考 |
| 流程图 | 13-flowchart-diagram |
| 功能 explainer | 14-research-feature-explainer ← 路由表 "分析报告" 主参考 |
| 概念 explainer | 15-research-concept-explainer |
| 实现计划 | 16-implementation-plan ← 路由表 "实现计划" 主参考 |
| PR write-up | 17-pr-writeup ← 路由表 "PR write-up" 主参考 |
| Triage 看板 | 18-editor-triage-board |
| Feature flags | 19-editor-feature-flags |
| Prompt tuner | 20-editor-prompt-tuner |
⚠️ 18-20 是 app UI 风（dense panels + sidebars），不要用 claude-report layout 套，按其原始结构改。
工作流（每次出报告）
- 判断子类型（按规则 3 路由表关键词匹配）
- 挑 layer 组合（按子类型推荐 + 内容裁剪）
- 选 layout（
.page / .page.wide / .page.with-nav）
- 从
references/claude-report.html 复制对应 layer 的 <body> 内部片段
- 填内容：代码 / 表 / SVG / 文字按规则 4 表达规范
- 包 HTML 容器：
- 自包含模式（默认）：
<!doctype html> + 完整 <head> + <style>（CSS 从 base-template.html 的 <style> 块复制一次）+ <body> + 内容
- fragment 模式（嵌入到已有 doc）：仅输出
<body> 内的 <div class="page">...</div>
- 输出
references 文件性质
| 文件 | 是否可双击打开 | 用途 |
|---|
base-template.html | ✅ 自包含，但 body 是 placeholder | 拷其 <head> + <style> 作为新报告的 shell |
claude-report.html | ✅ 自包含 demo（含全 12 层 + 内联 CSS） | 看视觉效果 + 拷 <body> 内对应 layer 片段 |
0X-*.html (20 文件) | ✅ Anthropic upstream 原版自包含 | 长尾场景参考 |
注意：claude-report.html 自己也内联了 CSS（与 base-template 等价），是为了双击可视化预览。生成新报告时仍以 base-template.html 的 <style> 作为权威 CSS 源，避免两处样式 drift。
反模式速查
- ❌ 报告里又用 markdown 又用 HTML（混乱）
- ❌ 自造 class（如
.my-card），即使更"语义"
- ❌ 强行 7 节都写（小报告就 H + 0 + D + G + Foot 就够了）
- ❌ 用 emoji 代替 .chip（破坏视觉系统）
- ❌ inline
style="..."（破坏一致性）
- ❌ 把
<head> 写得很大（自造 style 覆盖）
与其他 skill 的关系
ui-ux-pro-max / design-skill —— 那些是新建 UI（dashboard / landing page）；本 skill 是报告文档，定位不冲突pptx-generator —— 那是 .pptx 输出；本 skill 是 .htmlclaude-md-improver —— 那是改 CLAUDE.md；本 skill 是用户面向的报告
验证
调用本 skill 后，检查：
- 输出是否包成
<!doctype html> 或 body-only fragment
- 是否只用了上述 class，没自造
- layer 组合是否匹配路由表（不偏离子类型）
- token 节省是否 ≥ 40%（同内容 vs 原始 full HTML）
