# Readable Output

产出给人读的 HTML 长文, , 把已有的素材、经历、资料想清楚再写出来。每次触发先用 AskUserQuestion 一次性问清「给谁看 / 读完拿什么 / 多长 / 风格...

- Repository: https://github.com/yunshu0909/yunshu_skillshub (788 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-11
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add yunshu0909/yunshu_skillshub --skill readable-output -g -a claude-code -y`
Codex: `npx skills add yunshu0909/yunshu_skillshub --skill readable-output -g -a codex -y`
Cursor: `npx skills add yunshu0909/yunshu_skillshub --skill readable-output -g -a cursor -y`
Gemini CLI: `npx skills add yunshu0909/yunshu_skillshub --skill readable-output -g -a gemini-cli -y`

## Description

产出给人读的 HTML 长文, , 把已有的素材、经历、资料想清楚再写出来。每次触发先用 AskUserQuestion 一次性问清「给谁看 / 读完拿什么 / 多长 / 风格 + 侧重」4 个关键参数，再按 6 阶段框架输出。**产出只有 HTML 一种格式**, , 用户要 markdown 或要在聊天里直接说，就不该用本 skill。当用户说"做个复盘""汇总一下""总结这堆""整理成 HTML""做个教程/学习指南""把 X 讲清楚"等需要超过 500 字的结构化阅读内容时触发。不适用于：项目的计划报告/框架计划/版本路线（用 issue-pool，它自带 md2html）、PRD/需求文档/测试用例（用 prd-test-writer）、整页界面方案（用 page-solution-design）、起名（用 product-naming）、写代码/修 bug/改文件、一两句话就能答完的问题。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 输出工程：让 AI 输出长内容时按清单想一遍

## 工具适配

文中的 `AskUserQuestion` 使用当前平台的结构化询问工具；没有该工具时，用一条消息问清同样的四个维度。用户已明确的参数直接继承；工具名不同不阻断写作。


> 综合写作理论（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-test-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：要详到什么程度？

> **设计原因**：字数是后验感受、且常常承诺不到（素材撑不到时硬卡字数会注水）。所以**字数不进用户视图**，只承诺用户能感知的两件事, , 「**包含什么**」和「**阅读时间**」。

The rest: https://github.com/yunshu0909/yunshu_skillshub/blob/HEAD/visualization/readable-output/SKILL.md