write-readme

Files (24)

• CHANGELOG.md
• README.md
• README_EN.md
• SKILL.md
• config.yaml
• github-hero-patterns.md · references/
• readme-principles.md · references/
• research-notes.md · references/
• STATE.md · references/states/bilingual-draft-ready/
• STATE.md · references/states/delivery-ready/
• STATE.md · references/states/facts-collected/
• index.json · references/states/
• STATE.md · references/states/input-ready/
• STATE.md · references/states/reported/
• agent-skill.md · references/templates/
• cli-service.md · references/templates/
• data-ml.md · references/templates/
• general.md · references/templates/
• library.md · references/templates/
• web-app.md · references/templates/
• index.json · references/verifiers/
• VERIFIER.md · references/verifiers/readme-pair-alignment/
• verify.py · references/verifiers/readme-pair-alignment/scripts/
• check_readme_pair.py · scripts/

SKILL.md (first lines)

# 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. **完整 GitHub Hero**：除非项目确实是极短的索引或用户明确要求极简排版，首屏默认采用“居中标题/标识 → 事实徽章 → 导航 → 价值主张 → 解释段 → 证据或 Quick Start”的完整 Hero；视觉不可用时保留信息顺序并退化为纯 Markdown。
8. **克制装饰**：只添加能帮助判断的徽章、截图、GIF 或图表；视觉材料必须有替代文本和真实路径。
9. **诚实边界**：明确支持范围、限制、风险、数据来源、许可证和未验证事项，不用营销语气掩盖缺口。

#### 工作流

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

读取并交叉核对：

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

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

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

优先选择一个主模板，必要时组合一个部署附录；不要把所有模板拼成超长手册。详细章节骨架见 `references/templates/`；首屏 Hero 的组成、项目类型变体、可访问性门槛和反模式见 `references/github-hero-patterns.md`。

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

通用章节规则与反例见 `references/readme-principles.md`；Hero 模式和社区调研摘要见 `references/github-hero-patterns.md` 与 `references/research-notes.md`。

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

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

1. 完整 GitHub Hero：居中标题/真实标识、已验证徽章、语言/文档/演示导航、价值主张、2–4 句解释和真实证据或最短行动入口。
2. 一句话概览、核心能力或视觉预览（如果已在 Hero 中表达则不要重复堆砌）。
3. Quick Start：前置条件 → 安装 → 配置 → 运行 → 预期结果；Hero 中的命令必须与此处一致。
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。

### 输出管理

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

From huangwb8/skills, MIT.

More from huangwb8/skills