Readable Output

输出工程：让 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）三方交叉验证。

---

元原则（贴在最顶层，每次开始前默念）

1. 如果你自己读完没有获得新认知，读者也不会有。 写作是 thinking on paper，不是模板填空。
2. 终点是"读者下次能用"，不是"读者这次能懂"。 Backward design：先想读者读完手里多了什么"可复用的工具"（一张对照表 / 一个判断框架 / 一条决策路径 / 一个口诀），再倒推写什么。
3. 不列菜单——给推荐 + 一句话理由。 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 / 单篇文章）且原文 ⚠️ 提示一下：你选的是教学版（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 问

写完前必过：

1. 不懂这事的人能看懂吗？
2. 读完一周后能复述核心吗？
3. 最长那段砍一半还说得通吗？
4. 每段是否都在一屏内？（Linear One-Screen Test）
5. 是按"详略档完成度"产的，不是为了凑字数硬加的吗？（如果为了卡字数加了背景延伸/虚构案例/重复同类场景，砍掉）

---

反模式总清单

| 反模式 | 哪个阶段 | 后果 | |---|---|---| | 跳过阶段 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 区下方、正文上方，必须加这样一段双行条：

  
    📋 本次配置 · 受众：[问题 1 答案] · 终点：[问题 2 答案]
    · 详略：[问题 3 答案]（约 [阅读时间]） · 风格：[问题 4 答案]
  
  
    💬 觉得短？告诉我「展开 [章节名]」/「加 [背景/案例/可复用框架]」
       觉得长？「砍到要点」/「合并 X 章和 Y 章」
  

为什么加追加提示：长度是后验感受，事前再准也会有"差一点"。把"差一点"显式化成可点的指令，用户不用重跑就能迭代。这是这份 skill 故意不卡死字数的配套机制。

为什么配置条只写阅读时间不写字数：阅读时间是用户能感知的承诺、字数是 AI 内部目标。素材撑不到字数时硬卡会注水，撑过头时硬砍会丢内容。把字数从用户视图删掉，避免"标 5K-8K 给 3K"这种期望错位（这种错位等价于旧版"卡不住"）。

文件路径

默认写入项目 docs/ 下：

docs/[内容主题]-[YYYYMMDD].html

如果项目没有 docs/，写入用户指定路径或当前目录。

写完自动打开

写完 HTML 文件后，运行 open 在浏览器打开供 review。

---

维护规则

这份清单综合三方视角（写作 / 认知科学 / 大厂实践）交叉验证而来。如果有新来源（某本经典写作书、某家公司最佳实践）值得加入，按"是不是 3 方都认可"为标准筛选。

反原则：不要往清单里加"可能有用但不是必须"的检查项。AI 走清单本身有成本，每加一项都要确认能阻止某种具体反模式。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yunshu0909
• Source: yunshu0909/yunshu_skillshub
• License: MIT

Install and usage instructions live in the source repository linked above.