| name | yy-create-readme |
| description | 创建或更新项目根目录下的 README.md 文件。自动分析项目结构， 生成专业、清晰的 README 文档，包含项目描述、技术栈、安装使用、特性等核心内容。 不用于创建 AGENTS.md、规则文件、API 文档或子目录下的 README。
|
yy-create-readme
描述
自动分析项目结构，创建或更新根目录下的 README.md，帮助用户展示项目核心价值，回答"是什么、为什么、怎么用"三个核心问题。
使用场景
- 用户要求创建 README.md 文件
- 用户要求更新或完善 README.md
- 项目缺少文档说明时
- 用户说"帮我写个 README"
不应触发：
- 用户要求创建其他文档（如 CHANGELOG、CONTRIBUTING 等）
- 简单的文件读取操作
- 用户要求修改代码
- 用户只是想查看 README 内容
指令
步骤 1. 分析项目结构
扫描项目根目录，识别关键文件和目录：
- 包管理文件：
package.json、pom.xml、build.gradle、requirements.txt、Cargo.toml、go.mod 等
- 配置文件：
tsconfig.json、.eslintrc、pyproject.toml 等
- 源码目录：
src/、lib/、app/、main/ 等
- 文档目录：
docs/、examples/ 等
- 测试目录：
test/、tests/、__tests__/ 等
- 协议文件：
LICENSE、LICENSE.txt 等
- 截图/资源目录：
screenshots/、assets/、images/ 等
根据识别的文件判断项目类型：Node.js/前端、Python、Java、Go、Rust 或其他。
步骤 2. 检查现有 README.md
情况 A：README.md 不存在 — 记录为新建 README。
情况 B：README.md 已存在 — 读取现有内容，分析现有结构。默认采用"补充+优化"策略：保留现有内容，补充缺失部分，优化表达和结构，更正错误内容。若用户明确要求"完全重写"，则覆盖生成。
步骤 3. 确认方案与计划
完成 README 状态判断后，必须先确认方案与计划，收到用户确认后才可继续收集信息、生成内容或写入文件。
- 若当前环境可用
yy-mode-plan：优先直接使用该技能创建方案方向和计划，并等待用户确认
- 若当前环境不可用
yy-mode-plan：使用以下本地最小确认流程
- 方向不明确时：先展示方案方向，等用户确认方向正确后，再展示计划
- 方向明确时：直接展示计划
- 展示计划后，必须等用户确认才可继续后续步骤
- 展示方案方向时，至少包含以下内容：
- 目标：一句话说明将要完成的内容
- 方法：高层策略（1-3 句）
- 涉及范围：将要修改的文件、目录或文档章节
- 待确认点：仍需用户决策的关键选择（如有）
- 方案方向结尾必须明确提示用户确认方向是否正确，或提出调整意见
- 计划中至少说明 README 状态、目标文件路径、内容生成策略、信息来源和影响范围
步骤 4. 收集项目信息
根据项目类型从配置文件自动收集：
- 基本信息：项目名称、描述、版本号
- 技术信息：主要技术栈和框架、运行环境要求、主要依赖项
- 使用信息：安装方式、启动命令、配置说明
- 环境与资源：
.env.example、.env.sample 等环境变量示例文件；assets/、screenshots/、public/ 等资源占位目录
- 其他信息：开源协议、作者/维护者信息、是否有截图/GIF 演示
无法从文件确定的信息再主动询问用户。
步骤 5. 引导用户完善描述
如果项目描述不明确，使用以下核心问题引导：
- 项目是什么？ — 一句话描述核心功能
- 为什么开发？ — 开发动机、解决什么问题
- 有什么特点？ — 与同类项目的差异点
如果用户在请求中说"直接写"、"无需确认"等，跳过此步骤。
步骤 6. 生成 README.md 内容
参考 templates/readme-template.md 的结构生成文档，遵循以下原则：
- 回答三个核心问题：What、Why、How
- 结构清晰：使用合理的标题层级（最多 3 级），重要信息放在前面
- 示例完整：代码示例可直接复制运行，标注代码块语言类型
- 视觉友好：有 UI 的项目添加截图或 GIF，并提供描述性 alt 文本；列表项使用适当的 emoji 表情增强视觉效果
- 语言规范：中文项目使用中文，专有名词保留英文（如 Vue、TypeScript）
Emoji 使用规范：
- 特性列表：使用 ⭐、🚀、💡、🎯、⚡ 等表情
- 技术栈分类：使用 🖥️（前端）、⚙️（后端）、🗄️（数据库）、🧰（工具）等表情
- 环境要求：使用 📦 表情
- 协议部分：使用 📄 表情
- 保持一致性：同类项目使用相同的 emoji 表情
- 适度使用：避免过度使用 emoji，保持文档专业性
常见编写问题参考 resources/readme-writing-guide.md。
步骤 7. 写入文件
根据已确认的计划生成并写入 README.md，告知用户文件路径。如需调整，可继续提出修改意见。
输出约定
生成的 README.md 文件应包含：
必要内容（必须有）：
- 项目名称：清晰的标题
- 项目描述：回答"是什么、为什么"
- 安装方式：可执行的安装命令
- 使用方法：基本的启动/运行命令
推荐内容（强烈建议）：
- 环境要求：运行所需的版本要求
- 特性列表：3-5 个核心特性
- 技术栈：主要技术和框架
- 开源协议：许可证信息
可选内容（按需添加）：
- 界面展示：有 UI 的项目
- 配置说明：需要配置的项目
- 环境变量示例和资源占位说明：依赖
.env 或外部资源的项目
- 开发指南：开源项目
- 贡献指南：接受贡献的项目
- 变更日志：持续维护的项目
- 致谢：有依赖或参考的项目
相关资源
templates/readme-template.md：README 结构模板resources/readme-writing-guide.md：常见问题与注意事项
