readme-generator by bug-ops/claude-plugins
npx skills add https://github.com/bug-ops/claude-plugins --skill readme-generator生成专业的 README 文件或改进现有的 README 文件。应用来自 90 多个精选示例的生态系统特定最佳实践。
[!IMPORTANT] 在生成之前,务必先检测项目类型。错误的模板 = 错误的惯例。
| 项目类型 | 检测方式 | 关键要求 |
|---|---|---|
| Rust 库 | Cargo.toml + src/lib.rs | crates.io 徽章、docs.rs、MSRV、功能标志 |
| Rust CLI | Cargo.toml + src/main.rs | 多平台安装(cargo、brew、apt 等) |
| TypeScript | package.json + |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
tsconfig.json| npm/yarn/pnpm/bun 标签页、打包大小徽章 |
| Python | pyproject.toml 或 setup.py | pip/poetry/conda、Python 版本徽章 |
[!IMPORTANT] 在生成的 README 中使用 GitHub 标注框来突出显示关键信息。它们在 GitHub 上渲染效果很好。注意:标注框是 GitHub 特有的功能 —— 关于每个平台的限制,请参阅生态系统参考文件。
在生成的 README 文件中使用这些标注框:
> [!NOTE]
> 用户应该了解的有用信息,即使在浏览内容时也是如此。
> [!TIP]
> 关于如何更好或更轻松地做事的建议。
> [!IMPORTANT]
> 用户为实现目标需要了解的关键信息。
> [!WARNING]
> 需要用户立即关注以避免问题的紧急信息。
> [!CAUTION]
> 关于某些操作的风险或负面结果的建议。
| 标注框 | 用途 | 示例 |
|---|---|---|
[!NOTE] | 额外背景信息、仅供参考 | "此 crate 重新导出来自 X 的类型" |
[!TIP] | 最佳实践、建议 | "生产构建请使用 --release" |
[!IMPORTANT] | 破坏性变更、要求 | "需要 Rust 1.70+" |
[!WARNING] | 潜在问题、弃用通知 | "此 API 将在 v2.0 中更改" |
[!CAUTION] | 危险操作、数据丢失 | "此命令会删除所有数据" |
策略性地放置标注框:
带有 MSRV 的 Rust 库:
## 安装
```toml
[dependencies]
my-crate = "1.0"
```
> [!IMPORTANT]
> 需要 Rust 1.70 或更高版本。请参阅 [MSRV 策略](#msrv-policy)。
带有破坏性命令的 CLI 工具:
## 用法
```bash
my-tool clean --all
```
> [!CAUTION]
> `--all` 标志会删除所有缓存数据,包括用户首选项。此操作不可撤销。
带有异步功能的库:
## 功能
> [!TIP]
> 启用 `async` 功能以进行非阻塞 I/O。推荐用于高吞吐量应用程序。
```toml
my-crate = { version = "1.0", features = ["async"] }
```
带有版本要求的 Python 包:
## 安装
```bash
pip install my-package
```
> [!WARNING]
> Python 3.8 将于 2024 年 10 月停止支持。请考虑升级到 Python 3.10+。
# 检查项目标记
ls -la Cargo.toml package.json pyproject.toml setup.py tsconfig.json 2>/dev/null
决策树:
Cargo.toml → Rust 项目
[[bin]] 或 src/main.rs → CLI 工具(使用 references/rust-cli.md)references/rust-library.md)package.json → JavaScript/TypeScript
tsconfig.json → TypeScript(使用 references/typescript.md)references/typescript.md)pyproject.toml 或 setup.py → Python(使用 references/python.md)[!TIP] 从项目文件中提取元数据 —— 不要向用户询问已经存在于 Cargo.toml/package.json 中的信息。
从项目文件中提取:
Rust:
# 获取包信息
grep -E "^name|^version|^description|^license|^rust-version" Cargo.toml
# 获取功能
grep -A 50 "^\[features\]" Cargo.toml | head -50
# 检查是否有二进制文件
grep -E "^\[\[bin\]\]" Cargo.toml || ls src/main.rs 2>/dev/null
TypeScript/JavaScript:
# 获取包信息
cat package.json | jq '{name, version, description, license, keywords}'
# 检查是否有类型文件
ls src/*.ts tsconfig.json 2>/dev/null
Python:
# 从 pyproject.toml 中提取
grep -E "^name|^version|^description|^license" pyproject.toml
# 或从 setup.py 中提取
grep -E "name=|version=|description=" setup.py
检测到项目类型后,读取相应的参考文件:
references/rust-library.mdreferences/rust-cli.mdreferences/typescript.mdreferences/python.md[!WARNING] 切勿在最终输出中使用占位符文本,如
[TODO]或<description>。提取真实值或询问用户。
应用模板结构。按顺序排列的基本部分:
assets/、docs/ 或 images/ 中存在 GIF/截图演示
* CLI 工具的终端录制[!NOTE] 改进时,保留现有的自定义部分和贡献致谢。不要覆盖用户的内容。
改进现有 README 时:
审核当前状态:
cat README.md
对照要求检查: * 缺少基本部分? * 徽章过时? * 没有代码示例? * 大段文字没有结构?
常见改进: * 添加缺失的徽章 * 如果缺失,添加安装部分 * 如果缺失,添加使用示例 * 拆分长段落 * 如果超过 500 字,添加目录 * 更新过时的版本号
保留现有内容: * 保留自定义部分 * 维护现有链接 * 保留贡献历史致谢
关于完整的按生态系统分类的徽章语法,请参阅 references/badges.md。
快速参考:
<!-- Rust -->
[](https://crates.io/crates/CRATE)
[](https://docs.rs/CRATE)
<!-- TypeScript/npm -->
[](https://www.npmjs.com/package/PACKAGE)
[](https://bundlephobia.com/package/PACKAGE)
<!-- Python -->
[](https://pypi.org/project/PACKAGE)
[](https://pypi.org/project/PACKAGE)
完成前,请验证:
[!CAUTION] 这些错误会使 README 文件明显变差。在完成前对照此列表检查。
每周安装次数
1
仓库
GitHub 星标数
6
首次出现
1 天前
安全审计
安装于
amp1
cline1
opencode1
cursor1
kimi-cli1
codex1
Generate professional README files or improve existing ones. Applies ecosystem-specific best practices from 90+ curated examples.
[!IMPORTANT] Always detect project type FIRST before generating. Wrong template = wrong conventions.
| Project Type | Detection | Key Requirements |
|---|---|---|
| Rust library | Cargo.toml + src/lib.rs | crates.io badge, docs.rs, MSRV, feature flags |
| Rust CLI | Cargo.toml + src/main.rs | Multi-platform install (cargo, brew, apt, etc.) |
| TypeScript | package.json + tsconfig.json | npm/yarn/pnpm/bun tabs, bundle size badge |
| Python | pyproject.toml or setup.py | pip/poetry/conda, Python versions badge |
[!IMPORTANT] Use GitHub callouts in generated READMEs to highlight critical information. They render beautifully on GitHub. Note: callouts are GitHub-specific — see ecosystem reference files for per-platform restrictions.
Use these callout blocks in generated README files:
> [!NOTE]
> Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
| Callout | Use For | Example |
|---|---|---|
[!NOTE] | Additional context, FYI | "This crate re-exports types from X" |
[!TIP] | Best practices, recommendations | "Use --release for production builds" |
[!IMPORTANT] | Breaking changes, requirements | "Requires Rust 1.70+" |
[!WARNING] | Potential issues, deprecations | "This API will change in v2.0" |
[!CAUTION] |
Place callouts strategically:
Rust library with MSRV:
## Installation
\`\`\`toml
[dependencies]
my-crate = "1.0"
\`\`\`
> [!IMPORTANT]
> Requires Rust 1.70 or later. See [MSRV policy](#msrv-policy).
CLI tool with destructive command:
## Usage
\`\`\`bash
my-tool clean --all
\`\`\`
> [!CAUTION]
> The `--all` flag removes ALL cached data including user preferences. This cannot be undone.
Library with async feature:
## Features
> [!TIP]
> Enable the `async` feature for non-blocking I/O. Recommended for high-throughput applications.
\`\`\`toml
my-crate = { version = "1.0", features = ["async"] }
\`\`\`
Python package with version requirement:
## Installation
\`\`\`bash
pip install my-package
\`\`\`
> [!WARNING]
> Python 3.8 reaches end-of-life in October 2024. Consider upgrading to Python 3.10+.
# Check for project markers
ls -la Cargo.toml package.json pyproject.toml setup.py tsconfig.json 2>/dev/null
Decision tree:
Cargo.toml exists → Rust project
[[bin]] or src/main.rs → CLI tool (use references/rust-cli.md)references/rust-library.md)package.json exists → JavaScript/TypeScript
tsconfig.json exists → TypeScript (use references/typescript.md)references/typescript.md)[!TIP] Extract metadata from project files — don't ask the user for info that's already in Cargo.toml/package.json.
Extract from project files:
Rust:
# Get package info
grep -E "^name|^version|^description|^license|^rust-version" Cargo.toml
# Get features
grep -A 50 "^\[features\]" Cargo.toml | head -50
# Check for binary
grep -E "^\[\[bin\]\]" Cargo.toml || ls src/main.rs 2>/dev/null
TypeScript/JavaScript:
# Get package info
cat package.json | jq '{name, version, description, license, keywords}'
# Check for types
ls src/*.ts tsconfig.json 2>/dev/null
Python:
# From pyproject.toml
grep -E "^name|^version|^description|^license" pyproject.toml
# Or from setup.py
grep -E "name=|version=|description=" setup.py
After detecting project type, read the appropriate reference file:
references/rust-library.mdreferences/rust-cli.mdreferences/typescript.mdreferences/python.md[!WARNING] Never use placeholder text like
[TODO]or<description>in final output. Extract real values or ask user.
Apply the template structure. Essential sections in order:
Hero section (required)
Visual hook (highly recommended)
assets/, docs/, or images/Installation (required)
Usage/Examples (required)
Features (recommended)
API/Configuration (if applicable)
[!NOTE] When improving, preserve existing custom sections and contribution acknowledgments. Don't overwrite user's content.
When improving an existing README:
Audit current state:
cat README.md
Check against requirements:
Common improvements:
Preserve existing content:
See references/badges.md for complete badge syntax by ecosystem.
Quick reference:
<!-- Rust -->
[](https://crates.io/crates/CRATE)
[](https://docs.rs/CRATE)
<!-- TypeScript/npm -->
[](https://www.npmjs.com/package/PACKAGE)
[](https://bundlephobia.com/package/PACKAGE)
<!-- Python -->
[](https://pypi.org/project/PACKAGE)
[](https://pypi.org/project/PACKAGE)
Before completing, verify:
[!CAUTION] These mistakes make READMEs significantly worse. Check against this list before completing.
Weekly Installs
1
Repository
GitHub Stars
6
First Seen
1 day ago
Security Audits
Gen Agent Trust HubPassSocketFailSnykPass
Installed on
amp1
cline1
opencode1
cursor1
kimi-cli1
codex1
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
109,600 周安装
| Dangerous operations, data loss |
| "This command deletes all data" |
pyproject.toml or setup.py → Python (use references/python.md)Contributing (recommended)
License (required)