---
name: readme-gen
description: "为 Python 和 Rust 项目生成中文 README.md 文档。包含项目概述、安装指南、使用方法、配置说明和示例代码等标准章节。当用户要求生成 README、编写项目文档、创建项目说明，或提到 README.md 时使用此 skill。"
---

# README 文档生成

为 Python / Rust 项目生成结构清晰、内容完整的中文 README.md。

## 工作流程

```
Task Progress:
- [ ] Step 1: 分析项目结构和代码
- [ ] Step 2: 确定文档章节
- [ ] Step 3: 生成 README 内容
- [ ] Step 4: 检查和完善
```

### Step 1: 分析项目

在生成文档前，先收集项目信息：

1. 读取项目根目录结构（`ls` / `tree`）
2. 读取已有的配置文件：
   - Python: `pyproject.toml` > `setup.py` > `setup.cfg` > `requirements.txt`
   - Rust: `Cargo.toml`
3. 浏览核心源码入口（`main.py`、`lib.rs`、`main.rs` 等）
4. 检查是否有已有的 README（有则作为参考进行改写）

### Step 2: 确定章节

根据项目规模选择章节：

**小型项目**（单文件/脚本）→ 精简版：
- 项目简介、安装、使用方法

**标准项目** → 完整版（默认）：
- 项目简介、安装指南、快速开始、配置说明、示例代码

**大型项目**（多模块/库）→ 扩展版：
- 项目简介、目录、功能特性、安装指南、快速开始、配置说明、示例代码、项目结构、API 参考

> 当文档超过 150 行时，在项目简介后添加「目录」章节。

### Step 3: 生成 README

使用下方模板，参考 [templates.md](templates.md) 获取完整模板。

#### 核心规则

1. **语言**：全部使用中文，技术术语保留英文（如 API、CLI、Docker）
2. **代码块**：标注语言（`python`、`rust`、`bash`、`toml` 等）
3. **命令示例**：同时给出注释说明
4. **表格**：用于对比信息、参数列表、环境变量等结构化数据
5. **不加徽章**：除非用户明确要求

#### 行文风格

- 简洁直接，不要废话
- 用「你」称呼读者
- 步骤编号用阿拉伯数字
- 重要提示用 `>` 引用块或 `**粗体**`

### Step 4: 检查

生成后逐项检查：

- [ ] 所有代码块都能正确运行
- [ ] 安装命令与实际依赖文件一致
- [ ] 没有占位符文本（`<your-xxx>` 等需提醒用户修改）
- [ ] 目录链接正确（如有）
- [ ] Markdown 语法正确，无渲染问题

## 语言特定指南

### Python 项目

安装章节优先使用以下方式（按优先级排序）：

```bash
# 1. uv（推荐）
uv pip install <package>

# 2. pip
pip install <package>

# 3. 从源码安装
git clone <repo>
cd <project>
pip install -e .
```

虚拟环境建议：
```bash
# uv
uv venv && source .venv/bin/activate

# 标准方式
python -m venv .venv && source .venv/bin/activate
```

### Rust 项目

安装章节标准格式：

```bash
# 作为依赖添加
cargo add <crate-name>

# 从源码构建
git clone <repo>
cd <project>
cargo build --release
```

运行示例：
```bash
cargo run --example <example-name>
```

## 额外资源

- 完整模板和章节示例，参见 [templates.md](templates.md)