readme

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/readme — Gold-Standard README Generation

/readme — 黄金标准README生成

Purpose: Generate a README that converts skimmers into users and satisfies deep readers — then validate it with a council.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

用途： 生成能让浏览者转化为用户、同时满足深度阅读需求的README文件，随后通过council进行验证。

你必须执行此工作流，而非仅进行描述。

Quick Start

快速开始

bash

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

bash

/readme                    # 访谈 + 生成 + 验证（全新README）
/readme --rewrite          # 遵循相同模式重写现有README
/readme --validate         # 仅通过council验证现有README，不进行重写

The Patterns

核心模式

These are non-negotiable. Every README this skill produces follows them.

这些模式是不可妥协的，本技能生成的每一份README都将严格遵循。

1. Lead with the problem, not the framework

1. 以问题为开篇，而非框架

Bad: "A DevOps layer implementing the Three Ways for agent workflows." Good: "Coding agents forget everything between sessions. This fixes that."

The reader should understand what pain you solve in one sentence. No jargon, no framework names, no theory. The problem is the hook.

反面示例："一款为Agent工作流实现三大原则的DevOps层工具。" 正面示例："编码Agent会在会话之间遗忘所有信息，本工具可解决此问题。"

读者应能通过一句话理解你解决的痛点。避免行话、框架名称和理论。问题是吸引读者的钩子。

2. Acknowledge prior art

2. 提及已有方案

If your approach resembles established practices (agile, SCRUM, spec-driven development, CI/CD), say so explicitly:

"If you've done X, you already know the fix. What's new is Y."

This disarms experienced practitioners who would otherwise dismiss you as reinventing the wheel. Claim only what's genuinely novel.

如果你的方案与已确立的实践（敏捷、SCRUM、规范驱动开发、CI/CD）类似，请明确说明：

"如果你了解X，那你已经知道解决方案的核心。本工具的创新点在于Y。"

这能打消资深从业者认为你在重复造轮子的疑虑。仅声明真正创新的内容。

3. Show, don't claim

3. 展示而非宣称

Bad: "This is what makes X different. The system compounds." Good: A terminal transcript showing the system working.

Assertions without evidence trigger hostility. Concrete examples > adjectives. If you can't show it in a code block, it's not ready for the README.

反面示例："这正是X的与众不同之处，系统具备复利效应。" 正面示例：展示系统运行过程的终端记录。

无证据的断言会引发抵触。具体示例胜于形容词。如果无法用代码块展示，说明内容还未准备好写入README。

4. State your differentiator once

4. 仅声明一次差异化优势

One clear explanation. One demonstration. That's the max. Repeating your core value proposition in every section crosses from reinforcement into marketing copy. Trust the reader to absorb it the first time.

给出清晰的解释和一次演示即可，点到为止。在每个章节重复核心价值主张，会从强化变成营销话术。请相信读者能一次性理解。

5. Trust block near install

5. 在安装区域附近添加信任区块

Before a user installs anything that runs code, hooks, or modifies config, they need to see:

Concern	Answer it
What does it touch?	Files created/modified, hooks registered
Does it exfiltrate?	Telemetry, network calls, data leaving the machine
Permission surface	Shell commands, config changes, git behavior modifications
Reversibility	How to disable instantly, how to uninstall completely

This goes near the install command, not buried in an FAQ.

在用户安装任何会运行代码、挂载钩子或修改配置的工具前，他们需要看到以下信息：

关注点	对应说明
工具会访问哪些内容？	创建/修改的文件、注册的钩子
是否会向外传输数据？	遥测、网络请求、离开本地机器的数据
权限范围	Shell命令、配置修改、Git行为变更
可逆性	如何立即禁用、如何完全卸载

该区块应放在安装命令附近，而非隐藏在FAQ中。

6. Collapse depth, don't delete it

6. 折叠深度内容，而非删除

Detailed workflow steps, architecture deep-dives, theory, and reference material belong in

<details>

blocks. Skimmers get the fast path. Deep readers click to expand. Never delete depth to achieve brevity — collapse it.

详细的工作流步骤、架构深入解析、理论和参考资料应放在

<details>

区块中。浏览者可快速获取核心信息，深度读者可点击展开查看。切勿为了简洁而删除深度内容，应选择折叠。

7. Strip guru tone

7. 摒弃专家口吻

No "What N months taught me." No "I come from X, so I applied Y." No "This is what makes us different." Let the tool speak for itself. Humility disarms. Condescension repels.

避免使用“N个月的经验教会我”、“我来自X领域，因此应用了Y方法”、“这就是我们的与众不同之处”这类表述。让工具本身说话。谦逊能打消疑虑，傲慢会让人反感。

8. Section order serves adoption

8. 章节顺序以促进采用为目标

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

Theory and architecture come AFTER the user has seen examples and knows how to start. Never put "why this is important" before "how to try it."

问题 → 安装 → 效果展示 → 快速上手路径 → 工作原理（折叠） → 参考资料

理论和架构应放在用户看到示例、了解如何上手之后。切勿在说明“如何试用”之前，先讲“为什么这很重要”。

Execution Steps

执行步骤

Given

/readme [--rewrite] [--validate]

当收到指令

/readme [--rewrite] [--validate]

时：

Step 1: Pre-flight

步骤1：前置检查

bash

ls README.md 2>/dev/null

Mode detection:

```
--validate
```
+ README exists → skip to Step 5 (council validation only)
```
--rewrite
```
+ README exists → read existing, use as context for rewrite
README exists, no flags → ask:
- "Rewrite — regenerate with gold-standard patterns"
- "Validate — council-check the existing README"
- "Cancel"
No README exists → proceed to Step 2 (generate from scratch)

bash

ls README.md 2>/dev/null

模式检测：

```
--validate
```
+ 存在README.md → 直接跳至步骤5（仅进行council验证）
```
--rewrite
```
+ 存在README.md → 读取现有文件，作为重写的上下文
存在README.md但无参数 → 询问用户：
- "重写 — 遵循黄金标准模式重新生成"
- "验证 — 通过council检查现有README"
- "取消"
不存在README.md → 进入步骤2（从零开始生成）

Step 2: Gather Context

步骤2：收集上下文

Read available project files silently (no output to user):

bash

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

Extract:

Project name from manifest files
Language/runtime from build files
Existing description from README or PRODUCT.md
License from LICENSE file
Install method from manifest (npm, pip, brew, go install, cargo, etc.)

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

bash

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.md或PRODUCT.md
许可证：来自LICENSE文件
安装方式：来自清单文件（npm、pip、brew、go install、cargo等）

Step 3: Interview

步骤3：用户访谈

Use AskUserQuestion for each section. Pre-populate suggestions from Step 2 where possible. Keep questions short.

针对每个章节使用AskUserQuestion提问。尽可能用步骤2中提取的信息预填充选项。问题应简洁。

3a: The Problem

3a：项目解决的问题

Ask: "What problem does this solve? One sentence — what pain does your user have?"

Options (derived from existing README/PRODUCT.md if available):

Suggested problem statement
A punchier variant
"Let me type my own"

提问："该项目解决了什么问题？请用一句话描述用户的痛点。"

选项（若现有README/PRODUCT.md中有相关内容则基于此生成）：

建议的问题描述
更精炼的版本
"我自己输入"

3b: The Fix

3b：解决方案

Ask: "How does it fix that problem? One sentence — what does your tool actually do?"

提问："它如何解决该问题？请用一句话描述工具的实际功能。"

3c: Who Is It For

3c：目标用户

Ask: "Who is this for? Name the runtime, framework, or role."

Example: "Python developers using FastAPI" or "Anyone running Claude Code or Cursor"

提问："该工具面向谁？请说明运行时、框架或用户角色。"

示例："使用FastAPI的Python开发者" 或 "所有使用Claude Code或Cursor的用户"

3d: Install

3d：安装命令

Ask: "What's the install command? (We'll put this front and center)"

Options:

Detected from manifest (e.g.,
```
npm install <pkg>
```
,
```
pip install <pkg>
```
)
"Let me type my own"

提问："安装命令是什么？（我们会将其放在最显眼的位置）"

选项：

从清单文件中检测到的命令（如
```
npm install <pkg>
```
、
```
pip install <pkg>
```
）
"我自己输入"

3e: Quick Demo

3e：快速演示

Ask: "What's the simplest thing a user can do after installing to see it work? (A command, a code snippet, or a terminal session)"

提问："用户安装后能执行的最简单演示是什么？（命令、代码片段或终端会话）"

3f: Trust Concerns

3f：信任相关问题

Ask: "Does your tool do any of these? Check all that apply."

Runs shell commands or hooks
Modifies config files outside the project
Makes network calls
Creates files in the user's repo
None of the above

提问："你的工具会执行以下哪些操作？请勾选所有适用项。"

运行Shell命令或挂载钩子
修改项目外的配置文件
发起网络请求
在用户仓库中创建文件
以上都不会

3g: Prior Art (optional)

3g：已有方案（可选）

Ask: "Are there similar tools? If so, how is yours different? (Be honest — readers who know the space will check)"

Options:

"Yes, let me describe" → follow up
"Not really / I'll skip this"

提问："是否有类似工具？如果有，你的工具有何不同？（请如实回答 — 了解该领域的读者会核实）"

选项：

"有，我来描述" → 后续跟进提问
"没有/我跳过此部分"

Step 4: Generate README

步骤4：生成README

Using the interview responses and the 8 patterns above, generate the README with this structure:

markdown

<div align="center">

结合用户访谈的回复和上述8项模式，按照以下结构生成README：

markdown

<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}

{徽章}

{导航链接}

</div>

[!IMPORTANT] {信任区块 — 仅本地运行、访问内容、禁用方式、卸载方式} （若3f中无信任相关问题则跳过）

{安装命令}

The Problem

项目背景

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

{2-3句话扩展问题描述。若适用则提及已有方案。仅声明一次工具的真正创新点。}

See It Work

效果展示

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

{来自3e的终端记录或代码示例。展示而非描述。}

Install

安装指南

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

{完整安装细节，替代安装方式放在<details>区块中。若有信任相关问题则添加「工具访问内容」表格。}

Getting Started

快速上手

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

{采用路径 — 第1天、第1周等。或仅说明「运行X，然后执行Y」。}

How It Works

工作原理

{One paragraph summary + diagram if applicable.}

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

{Deep content here}

</details>

{一段摘要 + 若适用则添加示意图。}

{深度内容}

</details>

{Reference sections as needed}

{按需添加的参考章节}

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

{技能、API、CLI等 — 按需折叠}

FAQ

常见问题

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

{前3个问题直接展示，若有完整FAQ则添加链接}

Contributing

贡献指南

License

许可证


**Generation rules:**
- Every `<details>` block must have a blank line after `<summary>` (enables markdown rendering)
- Use markdown inside details blocks, not inline HTML (`<code>`, `<a href>`, `<br>`)
- Trailing blank line before `</details>`
- No emoji unless the user's existing content uses them
- Flywheel/differentiator concept: state ONCE in "The Problem", demonstrate ONCE in "See It Work"
- Never use phrases: "What N months taught me", "This is what makes X different", "I come from X so I applied Y"

Write the generated README to `README.md`.


**生成规则：**
- 每个`<details>`区块的`<summary>`后必须有一个空行（确保Markdown渲染正常）
- 在details区块中使用Markdown，而非内联HTML（`<code>`、`<a href>`、`<br>`除外）
- `</details>`前需添加空行
- 除非用户现有内容中使用表情，否则不添加表情
- 飞轮/差异化概念：仅在「项目背景」中声明一次，在「效果展示」中演示一次
- 禁止使用以下表述："N个月的经验教会我"、"这正是X的与众不同之处"、"我来自X领域因此应用了Y方法"

将生成的README写入`README.md`文件。

Step 5: Council Validation

步骤5：Council验证

Run a council to validate the README:

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

If
--rewrite
or generating from scratch: Use

--quick

(inline, fast).

If
--validate
on existing README: Use default council (2 judges) for thorough review.

Present the council findings to the user. If significant issues found, offer:

"Fix — apply council recommendations automatically"
"Show me — display findings, I'll decide"
"Ship it — good enough"

调用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

模式（内联快速验证）。

若为对现有README执行
--validate
：使用默认council（2位评审）进行全面审查。

向用户展示council的验证结果。若发现重大问题，提供以下选项：

"修复 — 自动应用council的建议"
"查看详情 — 展示问题，我自行决定"
"直接发布 — 目前已足够"

Step 6: Apply Fixes (if requested)

步骤6：应用修复（若用户要求）

Apply council-recommended fixes. Re-validate with

--quick

to confirm.

应用council推荐的修复。使用

--quick

模式重新验证以确认修复效果。

Step 7: Report

步骤7：生成报告

undefined

undefined

README Complete

README生成完成

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}

---

文件： README.md 章节数量： {统计数} 已应用模式： {列出相关的8项模式} Council验证结果： {通过/警告/失败}

{若为警告/失败：列出主要问题及是否已修复}

---

Anti-Patterns to Detect

需检测的反模式

When rewriting or validating, flag these:

Anti-Pattern	Detection	Fix
Flywheel echo	Core value prop stated 3+ times	State once, demonstrate once
Framework-first	Opens with methodology name, not problem	Rewrite lead as problem statement
Guru tone	"What I learned", "This is what makes X different"	Strip, let the tool speak
Jargon before definition	Domain terms used before they're explained	Define on first use or use plain language
Buried trust info	Security/permissions info below the fold	Move near install
No visible uninstall	Uninstall not findable within 10 seconds	Add near install block
Install scatter	Same install command in 3+ locations	One hero install, one canonical reference
Theory before try	Architecture/philosophy before examples	Reorder: examples first, theory in details
Claim without evidence	"Best", "different", "unique" without demo	Replace with concrete example or remove

在重写或验证时，需标记以下反模式：

反模式	检测方式	修复方案
核心主张重复	核心价值主张被提及3次以上	仅声明一次，演示一次
框架优先	开篇提及方法论名称而非问题	重写开篇为问题描述
专家口吻	出现「我学到了」、「这正是X的与众不同之处」等表述	删除此类内容，让工具本身说话
行话前置	在解释之前使用领域术语	首次使用时定义术语，或使用通俗语言
信任信息隐藏	安全/权限信息放在页面底部	移至安装区域附近
无可见卸载方式	10秒内无法找到卸载说明	在安装区块附近添加卸载方式
安装命令分散	相同安装命令出现在3个以上位置	保留一个主安装命令和一个标准参考位置
理论前置	架构/理念放在示例之前	调整顺序：先展示示例，理论放在折叠区块中
无证据宣称	出现「最佳」、「与众不同」、「独特」等无演示支撑的表述	替换为具体示例或删除