Imported from yunshu0909/yunshu_skillshub (
readable-output/SKILL.md). Install upstream withnpx skills add yunshu0909/yunshu_skillshub --skill readable-output. Copyright stays with the author.
输出工程：让 AI 输出长内容时按清单想一遍
综合写作理论（Zinsser《On Writing Well》/ Heath《Made to Stick》/ Rosenfeld《Information Architecture》）+ 学习科学（Sweller CLT / Brown《Make It Stick》/ Wiggins backward design）+ 大厂文档实践（Stripe / GitLab / Linear / Anthropic / Google SRE）三方交叉验证。
元原则（贴在最顶层，每次开始前默念）
- 如果你自己读完没有获得新认知，读者也不会有。 写作是 thinking on paper，不是模板填空。
- 终点是"读者下次能用"，不是"读者这次能懂"。 Backward design：先想读者读完手里多了什么"可复用的工具"（一张对照表 / 一个判断框架 / 一条决策路径 / 一个口诀），再倒推写什么。
- 不列菜单——给推荐 + 一句话理由。 AI 喜欢"列出 5 个选项让你选"，但好文档敢于 opinionated。
触发条件
触发（需要给人读的中长 HTML 内容）：
- "做个复盘 / 总结 / 汇总 / 整理"
- "做个教程 / 学习指南 / 上手文档"
- "把 X 讲清楚 / 整理成可读的 HTML"
- "做份报告 / 说明文档"
- 任何要求产出 > 500 字的结构化阅读内容
不触发（短输出 / 操作型 / 非 HTML 需求）：
- 写代码 / 修 bug / 改文件
- 一两句话回答
- 代码 diff / 短列表
- 用户明确说"用 markdown 答" / "聊天里直接说"
- PRD（用 prd-doc-writer）/ 文章写作（用 writing-assistant）/ 起名（用 product-naming）
重要：本 skill 产出只有 HTML 一种格式。如果用户要 markdown，不用本 skill。
运作模式
触发
↓
阶段 1：强制用 AskUserQuestion 一次性问 4 个关键问题
↓
用户选完
↓
阶段 2-6 在 AI 心里走（不对用户念稿）
↓
产出 HTML，顶部加「本次配置」确认条，浏览器自动打开
例外（跳过阶段 1 的提问）：
- 用户在 prompt 里已经明确所有 4 个参数（如"给 PM 看的 5K 字复盘，故事化风格"）
- 用户明确说 "快速做" / "随便给我一份" / "别问"
阶段 1（强制）：用 AskUserQuestion 一次性问 4 个
必须用 AskUserQuestion 工具发起一次询问，包含下面 4 个问题。问题文案和选项可微调但维度不能换。
问题 1：给谁看？（受众）
| 选项 | 说明 |
|---|---|
| PM / 产品经理 | 偏故事、对标、决策、可复用框架 |
| 工程师 / 技术新人 | 含代码片段、技术决策、动手指南 |
| 高管 / 决策者 | TL;DR + 数据 + 投/不投建议 |
| 自己 / 备忘 | 时间线 + 笔记式、备查 |
| 外部用户 / 客户 | 教程式、概念建梯 |
问题 2：读完拿什么？（终点）
| 选项 | 说明 |
|---|---|
| 决策依据 | 看完能 go/no/hold |
| 操作步骤 | 看完能动手 |
| 概念理解 | 看完知道是什么 |
| 故事共鸣 | 看完有感触 |
| 备忘归档 | 看完之后能查 |
问题 3：要详到什么程度？
设计原因：字数是后验感受、且常常承诺不到（素材撑不到时硬卡字数会注水）。所以字数不进用户视图，只承诺用户能感知的两件事——「包含什么」和「阅读时间」。
| 选项 | 包含什么 | 阅读时间 |
|---|---|---|
| 速读卡 | TL;DR + 1 个核心框架 / 1 张主图，能转发 | 3 分钟 |
| 标准版（默认推荐） | 核心点 + 故事 + 反例 + 出口 | 5-8 分钟 |
| 教学版 | + 背景延伸 + 多视角对照 + 可复用框架 + 边界声明 | 20-30 分钟 |
| AI 自选 | 按"受众耐受时间 × 素材独立信息点数"反推 | — |
字数怎么定（AI 内部参考，不告诉用户、不在配置条里写字数承诺）：
- 阅读速度按 PM/产品类内容 300 中文字/分钟 反推。
- 速读卡 → 内部目标 ~800 字 | 标准版 → ~1.5K-2.5K 字 | 教学版 → ~5K-8K 字
- 真正决定停笔的是"包含什么"清单是否每项都讲到位（standard 的"核心点 / 故事 / 反例 / 出口"四件事都齐全；teaching 多 4 项延展），而不是"字数到了"。
阶段 1.5（强制）：素材体量自检 + 主动反劝
问题 4 答完后、进入阶段 2 之前，AI 必须做一次自检。触发反劝的场景只有一个：
- 单文档型素材（单个 README / 单个 PRD / 单篇文章）且原文 < 3K 字 + 用户选了「教学版」
触发后，AI 必须中断流程，向用户主动反劝：
⚠️ 提示一下：你选的是教学版（20-30 分钟阅读），但素材是单 [README/PRD/文章] 仅 X 字。强行扩到教学版深度，约 60% 内容会是 AI 推演（背景延伸 / 对照 / 框架），不是素材原文。建议二选一： ① 改成「标准版」（5-8 分钟），刚好覆盖素材现有深度 ② 补充 2-3 份同类素材（多 PRD / 同领域多篇文章 / 项目全部文档），让教学版有真正的舞台
要继续教学版吗？（继续 / 改标准版 / 我去补素材）
- 用户改档：按新档位走阶段 2-6
- 用户去补素材：等用户补完再继续
- 用户坚持继续教学版：才产出，且必须加「素材体量警告」横幅 + 每段推演加「推演」标签（详见输出规则）
多源素材 / 非教学版 → 不触发反劝，直接进阶段 2。
问题 4：风格 + 侧重（合并）
每个选项是「视觉调性 + 内容侧重」绑定的：
| 选项 | 视觉 | 内容侧重 |
|---|---|---|
| 工程严肃 | 清新蓝（Stripe/Linear 风） | 教训方法论为主 |
| 故事化阅读 | 暖色书卷（米白 + 深棕） | 故事完整性为主 |
| 决策简洁 | 极简黑白（Apple 文档风） | 数据冲击为主 |
| 技术深度 | 暗色科技（GitHub Dark） | 含代码细节 |
| AI 自选 | — | 按受众默认推荐 |
用户选完后，把 4 个参数写入 HTML 顶部「本次配置」段（见下方"输出文件规则"）。
阶段 2-6（AI 自己心里走，不对用户念）
阶段 2 · 定终点（backward design）
基于阶段 1 用户选的"读完拿什么"，进一步具体化：读完手里多了什么"可复用的东西"？
- 一张对照表（A vs B 怎么选）
- 一个判断框架（什么情况该做 X）
- 一条决策路径（遇到 Y → 先 a → 再 b）
- 一个口诀（短句易记）
- 一份 checklist
反模式：终点只定到"读者理解"。
阶段 3 · 抓核心点（≤ 3 个）
工作记忆铁律（Sweller 认知负荷理论）：新读者一次只能处理 3-4 个新组块。默认 3 个，最多 5 个，超过必须合并或降级到附录。
核心点之间关系必须显式想清楚：
- 【并列】3 个独立要点，可任意顺序读
- 【依赖链 Why → What → How】必须按顺序
砍半测试：列出所有候选点后问"只能保留一半留哪几个"——剩下的就是真骨干。
阶段 4 · 选主结构（一个，不要叠）
警告：这一阶段最容易"自己在示范认知超载"——给推荐 + 一句话理由，不列菜单。
主结构 1 个（按内容性质选）：
| 内容性质 | 推荐结构 |
|---|---|
| 一段过程 / 多步骤决策 | 时间线 |
| 多个主题平行 | 分类章节 |
| 解决某个具体问题 | 问题导向 Q&A |
| 教学 / 概念建梯 | 由浅入深教学梯度 |
| 多版本对比 | before/after |
| 故事性强 | 危机-转折-启示 |
主视觉 1 套（不要叠）：表 / 对比卡 / ASCII 图 / Callout，选一种主导。
视觉细节（颜色、字体）按阶段 1 用户选的"风格"决定。
阶段 5 · 写：TL;DR + 论点句 + 反例 + 出口
5.1 开篇 TL;DR / 钩子（前置，不能埋）：Stripe / Google SRE 实践——前 2-3 句 = 全文摘要。钩子三选一：反常识 / 痛点 / 数字冲击。
5.2 每段一个论点句开头：先说结论再展开。
5.3 每个正面论点配一个反例 / What not to do：Anthropic Docs 实践，反例对照比正面示例更有效。
5.4 结尾给"出口"：可复用产物 + 下一步行动 + 边界声明（什么时候不适用）。
5.5 数据带出处，不复制已有内容：链接引用（GitLab single source of truth）。
5.6 复盘类内容：blameless 原则：对事不对人。
5.7 检索提示：开头一句总结 + 每节末尾回顾 + 可复用口诀。
阶段 6 · 自检 5 问
写完前必过：
- 不懂这事的人能看懂吗？
- 读完一周后能复述核心吗？
- 最长那段砍一半还说得通吗？
- 每段是否都在一屏内？（Linear One-Screen Test）
- 是按"详略档完成度"产的，不是为了凑字数硬加的吗？（如果为了卡字数加了背景延伸/虚构案例/重复同类场景，砍掉）
反模式总清单
| 反模式 | 哪个阶段 | 后果 |
|---|---|---|
| 跳过阶段 1 直接开写 | 1 | 自我感动 / 走偏 |
| 一次问超过 4 个问题 | 1 | 用户认知负担过重 |
| 用户已给的参数还重复问 | 1 | 啰嗦 / 显得不智能 |
| 终点定在"读者理解" | 2 | 信息汇总而非可迁移工具 |
| 5 个核心点并列 | 3 | 工作记忆超载 |
| 不分并列 vs 依赖链 | 3 | 结构混乱 |
| 列菜单不给推荐 | 4 | AI 让用户选 5 种结构 |
| 主视觉叠加（表+卡+图全用） | 4 | 视觉超载 |
| HTML 顶部没加「本次配置 + 追加提示」条 | 4 | 用户不知道按什么基准产的、也不知道可以追加 |
| 为了卡字数硬加方法论延展 / 虚构案例 / 重复场景 | 3-5 | 注水，自检第 5 问就是为这条而设 |
| 单文档素材选「教学版」未触发主动反劝 | 1.5 | 必然注水 + 用户预期错位（实测 README 类素材撑过 5K 就开始虚构） |
| 配置条 / 表格里写"参考字数"暴露给用户 | 3 / 文件规则 | 用户预期被字数锚定，撑不到时体感是"骗我" |
| TL;DR 埋在中间 | 5 | 读者前 30 秒走人 |
| 没有反例对照 | 5 | 正面示例容易被误用 |
| 数据无出处 | 5 | 容易编造 |
| 文档里抄已有内容 | 5 | 信息漂移 |
| 复盘里指责具体人 | 5 | 违反 blameless |
| 写完不自检直接交付 | 6 | 长 / 啰嗦 / 难读 |
快速决策树
触发
↓
[阶段 1] AskUserQuestion 4 问（除非已明确）
↓
[阶段 1.5] 素材体量自检 → 单文档 + 教学版 → 主动反劝改档
↓
[阶段 2] 定终点 = 可复用的什么？
↓
[阶段 3] 3 个核心点 + 砍半测试
↓
[阶段 4] 主结构 + 主视觉（不叠）
↓
[阶段 5] TL;DR + 论点句 + 反例 + 出口
↓
[阶段 6] 自检 4 问 → 砍 / 拆 / 调
↓
HTML 输出（顶部加确认条）+ 浏览器打开
输出文件规则
HTML 顶部必加「本次配置 + 追加提示」条
每份产出的 HTML 在 Hero 区下方、正文上方，必须加这样一段双行条：
<div class="config-bar">
<div class="config-line">
📋 本次配置 · 受众：[问题 1 答案] · 终点：[问题 2 答案]
· 详略：[问题 3 答案]（约 [阅读时间]） · 风格：[问题 4 答案]
</div>
<div class="hint-line">
💬 觉得短？告诉我「展开 [章节名]」/「加 [背景/案例/可复用框架]」
觉得长？「砍到要点」/「合并 X 章和 Y 章」
</div>
</div>为什么加追加提示：长度是后验感受，事前再准也会有"差一点"。把"差一点"显式化成可点的指令，用户不用重跑就能迭代。这是这份 skill 故意不卡死字数的配套机制。
为什么配置条只写阅读时间不写字数：阅读时间是用户能感知的承诺、字数是 AI 内部目标。素材撑不到字数时硬卡会注水，撑过头时硬砍会丢内容。把字数从用户视图删掉，避免"标 5K-8K 给 3K"这种期望错位（这种错位等价于旧版"卡不住"）。
文件路径
默认写入项目 docs/ 下：
docs/[内容主题]-[YYYYMMDD].html
如果项目没有 docs/，写入用户指定路径或当前目录。
写完自动打开
写完 HTML 文件后，运行 open <path> 在浏览器打开供 review。
维护规则
这份清单综合三方视角（写作 / 认知科学 / 大厂实践）交叉验证而来。如果有新来源（某本经典写作书、某家公司最佳实践）值得加入，按"是不是 3 方都认可"为标准筛选。
反原则：不要往清单里加"可能有用但不是必须"的检查项。AI 走清单本身有成本，每加一项都要确认能阻止某种具体反模式。
