Immutable. This exact content is served forever at /api/v1/blob/939e1c77da1f0ca5.
---
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` 先本地脱敏记录。