# Yy Create Readme

> 创建或更新项目根目录下的 README.md 文件。自动分析项目结构， 生成专业、清晰的 README 文档，包含项目描述、技术栈、安装使用、特性等核心内容。 不用于创建 AGENTS.md、规则文件、API 文档或子目录下的 README。

- Skill: `bulls-cows/yy-create-readme` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add bulls-cows/yy-create-readme`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-create-readme/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: bulls-cows (https://skillmd.com/u/bulls-cows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bulls-cows/yy-create-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. 引导用户完善描述

如果项目描述不明确，使用以下核心问题引导：

1. **项目是什么？** — 一句话描述核心功能
2. **为什么开发？** — 开发动机、解决什么问题
3. **有什么特点？** — 与同类项目的差异点

如果用户在请求中说"直接写"、"无需确认"等，跳过此步骤。

### 步骤 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`：常见问题与注意事项