Write Readme

---
name: write-readme
description: 为任意 GitHub 项目创建或改写高质量、可执行、证据驱动的双语 README；当用户说“写 README / README.md / 项目说明 / 文档首页 / GitHub 项目介绍”，或需要把 Agent Skill、库、CLI、Web 应用、服务、数据/机器学习项目整理成中文 README.md 与英文 README_EN.md 时使用。优先读取项目事实并验证命令、链接和功能，不凭空编造。
metadata:
  author: Bensz Conan
  short-description: 为任意项目生成中英文对齐的 GitHub README
  keywords:
    - write-readme
    - README
    - README.md
    - README_EN.md
    - GitHub documentation
    - project documentation
    - bilingual README
    - write-skill-readme
---

# write-readme

## 目标

为任意 GitHub 项目创建或改写高质量、可执行、证据驱动的双语 README；当用户说“写 README / README.md / 项目说明 / 文档首页 / GitHub 项目介绍”，或需要把 Agent Skill、库、CLI、Web 应用、服务、数据/机器学习项目整理成中文 README.md 与英文 README_EN.md 时使用。优先读取项目事实并验证命令、链接和功能，不凭空编造。

为项目写 README 的通用 Skill。它只负责项目说明文档，不改业务代码、配置或测试；默认写入项目根目录的 `README.md`（中文）和 `README_EN.md`（英文）。

## 流程

### 输入

#### 触发边界

适用：创建、重写、补齐或双语化项目 README；为 Agent Skill 写用户指南；根据仓库现状补 Quick Start、示例、架构、贡献或安全说明。

不适用：只改代码注释、写 API 参考手册、生成发布说明、翻译与项目无关的文章，或用户只要求审查而不允许写 README。若用户只指定一个语言，仍先确认是否应保持双语契约；本仓库默认保持两份对齐文件。

### 执行步骤

#### 核心原则

1. **先回答“这是什么、为何有用、如何开始”**：首屏给出项目名、具体价值主张和最短成功路径。
2. **事实优先**：功能、版本、命令、徽章、性能数字、兼容性和链接必须来自仓库或明确来源；无法确认就标为待确认/不写。
3. **任务优先而非文件优先**：按用户要完成的任务组织 Quick Start、示例和导航，架构细节后置。
4. **最小可运行示例**：安装、配置、运行、预期结果形成闭环；复杂用法链接到更深文档。
5. **渐进披露**：首屏短而有用；高级部署、内部设计、故障排查和贡献流程分层展开。
6. **双语等价**：英文不是逐词直译，而是自然表达同一事实；两份文件的标题树、代码块、链接目标、版本和示例保持同步。
7. **克制装饰**：只添加能帮助判断的徽章、截图、GIF 或图表；视觉材料必须有替代文本和真实路径。
8. **诚实边界**：明确支持范围、限制、风险、数据来源、许可证和未验证事项，不用营销语气掩盖缺口。

#### 工作流

##### 1. 建立事实清单

读取并交叉核对：

- 项目元数据：`pyproject.toml`、`package.json`、`Cargo.toml`、`go.mod`、`LICENSE`、版本文件。
- 入口与安装：CLI 入口、服务启动脚本、Docker/Compose、Makefile、CI workflow、示例配置。
- 能力证据：源码目录、测试、演示资源、发布包和现有文档。
- 约束：运行时版本、平台、外部服务、凭据需求、数据/模型许可和安全注意事项。

把“已证实”“用户明确提供”“推断/待确认”分开。不要为了填满章节而创造功能。

##### 2. 识别项目类型并选模板

优先选择一个主模板，必要时组合一个部署附录；不要把所有模板拼成超长手册。详细章节骨架见 `references/templates/`。

| 类型 | 识别信号 | 首要读者 | 首屏重点 |
|---|---|---|---|
| 通用库/SDK | 可导入包、API、版本发布 | 开发者 | 安装、最小 API、支持版本 |
| CLI/服务 | 命令入口、HTTP/Worker、Docker | 使用者/运维 | 一条命令运行、配置、健康检查 |
| Web/桌面应用 | 前端入口、截图、在线 Demo | 终端用户/部署者 | 视觉预览、体验路径、部署选项 |
| 数据/ML | 数据集、训练/推理、模型权重 | 研究者/工程师 | 数据与许可、复现实验、资源需求 |
| Agent Skill/插件 | `SKILL.md`、manifest、宿主安装 | Skill 使用者/维护者 | 触发方式、输入输出、宿主安装 |

通用章节规则与反例见 `references/readme-principles.md`；社区调研摘要与来源见 `references/research-notes.md`。

##### 3. 设计信息架构

按项目事实取舍以下顺序（不要生成空章节）：

1. 标题、价值主张、已验证徽章（可选）和语言切换链接。
2. 一句话概览、核心能力或视觉预览。
3. Quick Start：前置条件 → 安装 → 配置 → 运行 → 预期结果。
4. 按任务编排的 1–3 个最小示例；复杂示例链接到 `docs/`。
5. 选择性章节：功能/用例、架构、配置、部署、性能/复现、限制与安全、故障排查。
6. 帮助渠道、贡献指南、路线图（只有仓库有依据时）、许可证与致谢/引用。

标题使用 GitHub 可生成锚点的 Markdown 标题；目录仅在长文档或用户明确要求时添加（GitHub 已提供 Outline）。外部链接说明用途；相对链接和图片路径必须可解析。

##### 4. 先写中文，再生成英文

先固定中文事实和结构，再逐节生成英文。保留命令、代码、环境变量、路径、版本号、URL、表格列数和示例输出；品牌、API、许可证不翻译。中文客套话和夸大形容词不硬译。

##### 5. 校验与交付

运行：

```bash
python3 scripts/check_readme_pair.py README.md README_EN.md
```

脚本只做确定性检查：文件存在、标题树一致、代码围栏平衡、相对链接目标存在、两份文档中的命令/环境变量/版本 token 集合无明显漂移。语义准确性仍需 AI/人工复核。若目标项目无现成脚本，可从 Skill 目录运行：

```bash
python3 /path/to/write-readme/scripts/check_readme_pair.py /path/to/project/README.md /path/to/project/README_EN.md
```

交付摘要须说明：采用的模板、事实来源、实际运行过的命令、未运行或未确认的命令、生成文件和剩余风险。

#### Agent Skill 专用规则（继承 legacy 能力）

当项目包含 `SKILL.md` 时，读取其 frontmatter、`config.yaml`、`scripts/`、`references/` 和 `assets/`，把 README 写成使用者指南，而不是重复内部执行协议。至少包含：触发条件、最小 Prompt、进阶 Prompt、输入输出、推荐/备选用法、与相邻 Skill 的区别、配置/脚本入口、FAQ 和更多文档链接。只读这些文件作为事实来源，绝不修改它们。

Agent Skill README 仍遵守本 Skill 的双语约定：中文 `README.md` 与英文 `README_EN.md` 完全对齐。旧的 `write-skill-readme` 仅作为 legacy 名称保留，不应再被默认安装；安装器负责清理系统级旧目录。

#### 与其他 Skill 的协作

- `write-skill-readme`：legacy 能力已吸收；新任务统一使用 `write-readme`。
- `validate-md-ref`：可在交付前检查 Markdown 链接和锚点。
- `which-model`：若 README 需要模型选择建议，可单独生成并人工核对来源。
- `auto-test-skill`：测试本 Skill 的触发与文档契约，不替代 README 的事实校验。

### 输出

#### 输入与输出

输入：项目路径（默认当前目录）、写作目标和可选受众/定位。读取 README、许可证、包配置、入口、CI、示例、文档、测试命令等公开事实。

输出：中文 `README.md`、英文 `README_EN.md`（章节、示例、链接、命令和事实一一对应），以及可选的检查摘要（模板、已验证命令、待确认项）。

仅在用户授权的项目范围内写入上述 README 文件；不覆盖其它文档，不把密钥、令牌、个人信息或完整私有提示词写入 README。

##### Runtime Contract Pack（可选）

当宿主提供 `bensz-skill-kernel` 时，使用 `config.yaml.runtime` 声明的
State/Verifier 子集记录阶段和验证证据；没有 Kernel 时仍按本文普通流程执行，
不得声称已自动完成验证。领域阶段按以下稳定节点推进：

`input-ready` → `facts-collected` → `bilingual-draft-ready` →
`delivery-ready` → `reported`。

运行身份必须绑定 `run_id` 与 `attempt_id`。Pair Verifier
`bensz.document.readme-pair-alignment@1.0.0` 复用确定性结构检查；路径范围、文件存在、
Markdown 链接、敏感信息脱敏和证据来源优先复用 Kernel 原子 Verifier。结构错误、越界或
敏感信息命中应 fail-closed；token 漂移、网络不可观测或事实语义不足只能标为
`uncertain`/`unchecked` 并转人工复核，不能把模型自评当作通过。

事实清单和交付摘要遵循最小 Evidence Contract：项目/双语产物使用授权的相对路径，
每条关键事实保留来源、内容哈希、来源类型和 `verified`/`user-provided`/`inferred`/
`unresolved` 状态；日志不得保存凭据、完整 Prompt 或无关原始上下文。交付前 required
Verifier 结果及 Kernel Gate 必须覆盖当前运行，否则停在检查/等待阶段或失败，不写入最终
README。

### 输出管理

正式交付物、临时产物和日志继续遵循原有路径及覆盖边界；任务级中间文件使用当前会话声明的 `.bensz-api` 工作区。

### 校验

#### 质量门槛

- 首屏在 30 秒内说明项目用途和最短成功路径。
- Quick Start 不依赖未声明的前置步骤；命令来自仓库并尽量实际运行。
- 没有无法定位的徽章、图片、链接、功能数字或版本声明。
- 中文和英文标题树、代码块数量、命令、环境变量、相对链接与许可证事实一致。
- README 不包含凭据、隐私、内部 Prompt 或不必要的大段原始数据。
- 高级细节有明确的下一步链接；失败场景给出恢复建议或指向支持渠道。

### 失败与恢复

#### 安全与失败处理

路径仅限用户授权的项目范围；不读取或记录 `.env`、密钥文件、Cookie、SSH 凭据和私有提示词。遇到缺少入口、命令需要凭据、网络不可用或事实冲突时，保留可验证部分并在交付摘要列出阻塞点，不猜测、不静默跳过。

若发现是本 Skill 的设计缺陷（而非用户数据错误、第三方服务抖动、用户改源码或模型偶发波动），按 `bensz-collect-bugs` 规则先脱敏记录到 `~/.bensz-skills/bugs/`，当前任务继续；不得就地修改系统级已安装 Skill，也不得在未获明确授权时公开上报。


## 控制

运行时由 `bensz-skill-kernel` 按 `config.yaml.runtime` 管理 State、Verifier 与 Gate；事实收集、双语草稿和交付阶段必须绑定可引用 Evidence，未实现的写作判断仍由 Agent 完成。

## 约束

遵守 `.bensz-api` 任务工作区协议和 BAC 贡献记录；不记录 API Key、访问令牌、密码、Cookie、凭据、私有 Prompt 或用户隐私。文件操作限于授权范围，未经授权不执行远程写入、删除或覆盖；Skill 设计缺陷按 `bensz-collect-bugs` 先本地脱敏记录。