readme

/readme — 黄金标准 README 生成

**目的：**生成一份能将浏览者转化为用户、满足深入阅读者需求的 README，然后通过评审团验证。

你必须执行此工作流。不要只是描述它。

快速开始

/readme                    # Interview + generate + validate (new README)
/readme --rewrite          # Rewrite existing README with same patterns
/readme --validate         # Council-validate an existing README without rewriting

---

模式

这些要求不可妥协。此技能生成的每份 README 都遵循这些模式。

1. 开篇讲问题，而不是框架

反例：“为 Agent 工作流实现三步法的 DevOps 层。” 正例：“编码 Agent 会忘记不同会话之间的一切。这个工具可以解决这个问题。”

读者应该能用一句话理解你解决了什么痛点。不要用术语、框架名称或理论。问题就是吸引读者的关键。（注意：像三步法和 Meadows 这样的框架，应作为设计依据放在正文中，而不是放在开篇。）

2. 承认已有实践

如果你的方法与成熟实践（敏捷、SCRUM、规范驱动开发、CI/CD）相似，请明确说明：

“如果你做过 X，就已经知道解决办法。新颖之处在于 Y。”

这样能打消资深从业者的疑虑，避免他们认为你只是在重复造轮子。只声称真正新颖的部分。

3. 展示，而不是声称

反例：“这就是 X 与众不同的地方。系统会不断积累。” 正例：展示系统正常工作的终端记录。

没有证据的断言会引起反感。具体示例胜过形容词。如果无法在代码块中展示，就说明还没准备好写进 README。

4. 只说明一次差异化优势

清楚解释一次。演示一次。仅此而已。在每个章节重复核心价值主张，就会从强化信息变成营销文案。相信读者第一次就能理解。

5. 在安装说明附近展示信任信息

在用户安装任何会运行代码、挂载钩子或修改配置的内容之前，他们需要了解：

关注点	需要说明的内容
会改动什么？	创建或修改的文件、注册的钩子
会泄露数据吗？	遥测、网络调用、离开本机的数据
权限范围	Shell 命令、配置变更、Git 行为修改
能否恢复？	如何立即停用、如何彻底卸载

这部分应放在安装命令附近，而不是埋在常见问题解答中。

6. 收起细节，不要删除

详细的工作流步骤、架构深入解析、理论和参考资料应放在 <details> 块中。浏览者可以快速了解重点，深入阅读者可以点击展开。不要为了简洁而删除细节——把它们收起来。

7. 去掉说教口吻

不要写“过去 N 个月教会了我什么”。不要写“我来自 X，所以我应用了 Y”。不要写“这就是我们与众不同的地方”。让工具自己说话。谦逊能消除戒心，居高临下则会让人反感。

8. 章节顺序应有助于用户采用

Problem → Install → See It Work → Getting Started Path → How It Works (collapsed) → Reference

理论和架构应放在用户看过示例、知道如何开始之后。绝不要在“如何尝试”之前讲“为什么这很重要”。

---

执行步骤

对于 /readme [--rewrite] [--validate]：

步骤 1：准备检查

ls README.md 2>/dev/null

模式判断：

• 使用 --validate 且 README 已存在 → 跳到步骤 5（仅进行评审团验证）
• 使用 --rewrite 且 README 已存在 → 读取现有 README，并将其作为重写的上下文
• README 已存在且未指定标记 → 询问：
  • “重写 — 按黄金标准模式重新生成”
  • “验证 — 由评审团检查现有 README”
  • “取消”
• README 不存在 → 继续步骤 2（从头生成）

步骤 2：收集上下文

静默读取可用的项目文件（不向用户输出）：

ls README.md PRODUCT.md package.json pyproject.toml go.mod Cargo.toml Makefile 2>/dev/null
ls -d src/ lib/ cmd/ app/ 2>/dev/null
ls -d docs/ 2>/dev/null
ls LICENSE CHANGELOG.md 2>/dev/null

提取：

• 项目名称：从清单文件中获取
• 语言／运行时：从构建文件中获取
• 现有描述：从 README 或 PRODUCT.md 中获取
• 许可证：从 LICENSE 文件中获取
• 安装方式：从清单中获取（npm、pip、brew、go install、cargo 等）

步骤 3：访谈

针对每个章节使用 AskUserQuestion。在可能的情况下，使用步骤 2 中的信息预先填入建议。问题要简短。

3a：问题

询问：“这解决了什么问题？用一句话说明——用户遇到什么痛点？”

选项（如有现成的 README/PRODUCT.md，则根据其内容生成）：

• 建议的问题陈述
• 更有冲击力的版本
• “让我自己输入”

3b：解决方案

询问：“它如何解决这个问题？用一句话说明——你的工具实际会做什么？”

3c：适用对象

询问：“这是为谁打造的？说出运行时、框架或角色。”

示例：“使用 FastAPI 的 Python 开发者”或“任何运行 Claude Code 或 Cursor 的人”

3d：安装

询问：“安装命令是什么？（我们会把它放在最显眼的位置）”

选项：

• 从清单中检测（例如，npm install <pkg>、pip install <pkg>）
• “让我自己输入”

3e：快速演示

询问：“安装后，用户可以做什么最简单的操作来确认它能正常运行？（命令、代码片段或终端会话）”

3f：信任考量

询问：“你的工具会做以下哪些事情？请勾选所有适用项。”

• 运行 shell 命令或钩子
• 修改项目之外的配置文件
• 发出网络请求
• 在用户的代码仓库中创建文件
• 以上皆非

3g：先例（可选）

询问：“有类似的工具吗？如果有，你的工具有何不同？（请如实回答——熟悉这一领域的读者会进行核实）”

选项：

• “有，让我来描述” → 追问
• “没有特别类似的／跳过此项”

第 4 步：生成 README

根据访谈回复和上述 8 种模式，按以下结构生成 README：

<div align="center">

# {Project Name}

### {Problem statement — one line}

{Badges}

{Nav links}

</div>

---

> [!IMPORTANT]
> {Trust block — local-only, what it touches, how to disable, how to uninstall}
> (Skip if no trust concerns from 3f)

{Install command}

---

## The Problem

{2-3 sentences expanding the problem. Acknowledge prior art if applicable.
State what's genuinely new about your approach — once.}

---

## See It Work

{Terminal transcript or code example from 3e. Show, don't describe.}

---

## Install

{Full install details, alternative methods in <details> blocks.
"What it touches" table if trust concerns exist.}

---

## Getting Started

{Adoption path — Day 1, Week 1, etc. Or just "Run X, then Y."}

---

## How It Works

{One paragraph summary + diagram if applicable.}

<details>
<summary><b>Details</b> — {phases, architecture, etc.}</summary>

{Deep content here}

</details>

---

## {Reference sections as needed}

{Skills, API, CLI, etc. — collapsed where appropriate}

---

## FAQ

{Top 3 questions inline, link to full FAQ if it exists}

---

## Contributing

## License

生成规则：

• 每个 <details> 块中的 <summary> 后都必须留一个空行（以启用 Markdown 渲染）
• 在 details 块中使用 Markdown，而不是内联 HTML（<code>、<a href>、<br>）
• 在 </details> 前留一个空行
• 除非用户现有内容使用表情符号，否则不要使用表情符号
• 飞轮／差异化概念：在“问题”中只陈述一次，在“看它运行”中只展示一次
• 绝不要使用以下措辞：“N 个月教会了我什么”“这就是 X 与众不同之处”“我来自 X，所以我应用了 Y”

将生成的 README 写入 README.md。

第 5 步：Council 验证

运行 council 来验证 README：

Skill(skill="council", args="--quick validate README.md — is it clear, non-repetitive, and does it serve both skimmers and deep readers?")

使用 --rewrite 或从头开始生成时： 使用 --quick（内联、快速）。

使用 --validate 验证现有 README 时： 使用默认 council（2 位评审者）进行全面审查。

向用户展示 council 的发现。如果发现重大问题，请提供以下选项：

• “修复——自动应用 council 的建议”
• “展示给我——显示发现，由我决定”
• “发布——这样就够好了”

第 6 步：应用修复（如有要求）

应用 council 建议的修复。使用 --quick 重新验证以确认。

第 7 步：报告

## README Complete

**File:** README.md
**Sections:** {count}
**Patterns applied:** {list which of the 8 patterns were relevant}
**Council verdict:** {PASS/WARN/FAIL}

{If WARN/FAIL: list the top findings and whether they were fixed}

---

要识别的反模式

重写或验证时，请标记以下问题：

反模式	检测方式	修复方法
飞轮回声	核心价值主张陈述了 3 次以上	陈述一次，展示一次
框架优先	开篇先讲方法论名称，而非问题	将开篇改写为问题陈述
大师腔调	“我学到了什么”“这就是 X 与众不同之处”	删除这些内容，让工具自己说话
术语先于定义	尚未解释就使用领域术语	首次使用时先定义，或改用通俗说法
信任信息埋得太深	安全性／权限信息位于首屏以下	将其移至安装说明附近
没有醒目的卸载说明	10 秒内找不到卸载方法	将其添加到安装说明附近
安装命令散落各处	同一安装命令出现在 3 个以上位置	保留一处主展示和一处规范引用
先讲理论再试用	在示例之前先讲架构／理念	调整顺序：先放示例，再把理论放在 details 中
主张缺少证据	没有演示却声称“最佳”“不同”“独特”	换成具体示例，或删除

---

示例

从头为新项目生成 README

用户说： /readme

执行过程：

1. 预检发现不存在现有的 README.md，于是从头开始生成。
2. 该技能会读取项目上下文（清单文件、源代码目录、许可证），并进行简短访谈，询问项目要解决的问题、解决方案、目标受众、安装命令、快速演示和信任方面的顾虑。
3. README 会按照全部 8 项黄金标准模式（问题优先的开篇、安装部分附近的信任说明、可折叠的详细内容等）生成，并通过快速评审委员会审核。

结果： 一份写入磁盘的完整 README.md，既能将浏览者转化为用户，也能满足深入阅读者的需求，并附有确认质量的评审委员会结论。

验证现有 README，不做修改

用户说： /readme --validate

执行过程：

1. 预检确认 README.md 存在，并进入仅验证模式，跳过访谈和生成步骤。
2. 由评审委员会（2 位评审者）根据 8 项模式和反模式检测表（飞轮回声、专家说教口吻、信任信息埋得太深等）全面评审 README。
3. 呈现评审结果，并提供自动修复、手动审查或直接发布等选项。

结果： 一份详细的评审委员会报告，指出现有 README 中的具体反模式和结构问题，并提供可执行的修复建议。

故障排除

问题	原因	解决方案
评审委员会验证步骤失败或卡住	未安装 /council 技能依赖，或该依赖已损坏	运行 /update 重新安装所有技能，然后重试。确认 /council 可以独立正常工作
生成的 README 没有信任说明	访谈期间未选择任何信任方面的顾虑（第 3f 步回答了“以上都不是”）	如果你的工具会运行钩子、修改配置或进行网络调用，请重新运行 /readme --rewrite，并选择适用的信任方面顾虑
GitHub 将 <details> 块显示为原始 HTML	<summary> 标签后或 </details> 前缺少空行	该技能会强制执行此格式规则，但手动编辑可能会破坏格式。请确保每个 <summary>...</summary> 行后以及每个 </details> 前都有一个空行
访谈不断询问项目清单中已有答案的问题	上下文收集步骤无法识别清单文件格式	确保仓库根目录下有标准清单文件（package.json、go.mod、pyproject.toml、Cargo.toml）
重写时反模式检测误报	即使某些内容模式是有意采用的，也可能触发启发式检测	在评审委员会步骤中逐项检查结果，对有意采用的做法选择“直接发布”。该检测基于启发式规则，并非绝对判断

另请参阅

• skills/product/SKILL.md — PRODUCT.md 生成（为 README 上下文提供信息）
• skills/doc/SKILL.md — 代码文档（范围不同：面向 API，而非 README）
• skills/council/SKILL.md — 第 5 步使用的验证引擎