yy-create-readme

name: yy-create-readme description: > 创建或更新项目根目录下的 README.md 文件。自动分析项目结构，生成专业、清晰的 README 文档，包含项目描述、技术栈、安装使用、特性等核心内容。不用于创建 AGENTS.md、规则文件、API 文档或子目录下的 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 或外部资源的项目
开发指南：开源项目
贡献指南：接受贡献的项目
变更日志：持续维护的项目
致谢：有依赖或参考的项目

yy-create-readme

yy-create-readme

描述

使用场景

指令

步骤 1. 分析项目结构

步骤 2. 检查现有 README.md

步骤 3. 确认方案与计划

步骤 4. 收集项目信息

步骤 5. 引导用户完善描述

步骤 6. 生成 README.md 内容

步骤 7. 写入文件

输出约定

相关资源