write-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. **完整 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/`；首屏 ...