专业 README 生成器 | 支持 Rust/TypeScript/Python 项目，自动应用最佳实践

readme-generator by bug-ops/claude-plugins

1 周安装量

6 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/bug-ops/claude-plugins --skill readme-generator

开发文档生成开源项目

🇨🇳中文介绍

README 生成器

生成专业的 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 开发者，精准高效

联系我们

何时使用每种标注框

标注框	用途	示例
`[!NOTE]`	额外背景信息、仅供参考	"此 crate 重新导出来自 X 的类型"
`[!TIP]`	最佳实践、建议	"生产构建请使用 `--release`"
`[!IMPORTANT]`	破坏性变更、要求	"需要 Rust 1.70+"
`[!WARNING]`	潜在问题、弃用通知	"此 API 将在 v2.0 中更改"
`[!CAUTION]`	危险操作、数据丢失	"此命令会删除所有数据"

README 中标注框的放置位置

策略性地放置标注框：

安装之后 —— 兼容性警告、系统要求
使用说明部分 —— 常见模式的提示、重要的注意事项
破坏性变更之前 —— 迁移说明、弃用警告
配置部分 —— 危险选项、安全考虑

生成 README 中的示例

带有 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+。

1. 检测项目类型

# 检查项目标记
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）
- 否则 → JavaScript（使用 references/typescript.md）
存在 pyproject.toml 或 setup.py → Python（使用 references/python.md）

2. 收集项目上下文

[!TIP] 从项目文件中提取元数据 —— 不要向用户询问已经存在于 Cargo.toml/package.json 中的信息。

从项目文件中提取：

# 获取包信息
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

# 从 pyproject.toml 中提取
grep -E "^name|^version|^description|^license" pyproject.toml
# 或从 setup.py 中提取
grep -E "name=|version=|description=" setup.py

检测到项目类型后，读取相应的参考文件：

Rust 库 → 读取 references/rust-library.md
Rust CLI → 读取 references/rust-cli.md
TypeScript/JavaScript → 读取 references/typescript.md
Python → 读取 references/python.md

[!WARNING] 切勿在最终输出中使用占位符文本，如 [TODO] 或 <description>。提取真实值或询问用户。

应用模板结构。按顺序排列的基本部分：

标题部分（必需） * 项目名称作为 H1 标题 * 单行描述（来自包元数据） * 徽章行（生态系统特定）
视觉钩子（强烈推荐） * 如果 assets/、docs/ 或 images/ 中存在 GIF/截图演示 * CLI 工具的终端录制
安装（必需） * 适合生态系统的命令 * CLI 工具的多个包管理器
用法/示例（必需） * 可运行的代码片段 * 常见用例
功能（推荐） * 关键功能的项目符号列表
API/配置（如果适用） * 对于库：关键类型和函数 * 对于 CLI：命令行参数 * 对于服务：环境变量
贡献（推荐） * 如果存在，链接到 CONTRIBUTING.md * 否则提供基本指南
许可证（必需） * 许可证名称，并链接到 LICENSE 文件

5. 改进现有 README

[!NOTE] 改进时，保留现有的自定义部分和贡献致谢。不要覆盖用户的内容。

改进现有 README 时：

审核当前状态：

cat README.md
对照要求检查： * 缺少基本部分？ * 徽章过时？ * 没有代码示例？ * 大段文字没有结构？
常见改进： * 添加缺失的徽章 * 如果缺失，添加安装部分 * 如果缺失，添加使用示例 * 拆分长段落 * 如果超过 500 字，添加目录 * 更新过时的版本号
保留现有内容： * 保留自定义部分 * 维护现有链接 * 保留贡献历史致谢

关于完整的按生态系统分类的徽章语法，请参阅 references/badges.md。

<!-- Rust -->
[![Crates.io](https://img.shields.io/crates/v/CRATE)](https://crates.io/crates/CRATE)
[![docs.rs](https://img.shields.io/docsrs/CRATE)](https://docs.rs/CRATE)

<!-- TypeScript/npm -->
[![npm](https://img.shields.io/npm/v/PACKAGE)](https://www.npmjs.com/package/PACKAGE)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/PACKAGE)](https://bundlephobia.com/package/PACKAGE)

<!-- Python -->
[![PyPI](https://img.shields.io/pypi/v/PACKAGE)](https://pypi.org/project/PACKAGE)
[![Python](https://img.shields.io/pypi/pyversions/PACKAGE)](https://pypi.org/project/PACKAGE)

完成前，请验证：

单行描述清晰且具体
徽章有效且适合生态系统
安装命令可复制粘贴
至少有一个可运行的代码示例
指定了许可证
没有损坏的链接
没有剩余的占位符文本
使用标注框处理警告、提示和重要说明（仅限 GitHub/crates.io —— 避免用于 PyPI 和 npm）

要避免的反模式

[!CAUTION] 这些错误会使 README 文件明显变差。在完成前对照此列表检查。

大段文字没有标题
通用描述（"一个用于做事的工具"）
缺少安装部分
没有代码示例
过时的徽章/版本号
过多的徽章（>6 个通常就太多了）
为简短的 README 添加目录（<300 字）

🇺🇸English

README Generator

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.

Quick Reference

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

GitHub Callouts

[!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.

Callout Types

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.

When to Use Each Callout

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]`

Callout Placement in README

Place callouts strategically:

After Installation — compatibility warnings, system requirements
In Usage section — tips for common patterns, important gotchas
Before Breaking Changes — migration notes, deprecation warnings
In Configuration — dangerous options, security considerations

Examples in Generated READMEs

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+.

Workflow

1. Detect Project Type

# 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
- Has [[bin]] or src/main.rs → CLI tool (use references/rust-cli.md)
- Otherwise → Library (use references/rust-library.md)
package.json exists → JavaScript/TypeScript
- tsconfig.json exists → TypeScript (use references/typescript.md)
- Otherwise → JavaScript (use references/typescript.md)

2. Gather Project Context

[!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

3. Load Template

After detecting project type, read the appropriate reference file:

Rust library → Read references/rust-library.md
Rust CLI → Read references/rust-cli.md
TypeScript/JavaScript → Read references/typescript.md
Python → Read references/python.md

4. Generate README

[!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)
- Project name as H1
- One-line description (from package metadata)
- Badge row (ecosystem-specific)
Visual hook (highly recommended)
- GIF/screenshot demo if exists in assets/, docs/, or images/
- Terminal recording for CLI tools
Installation (required)
- Ecosystem-appropriate commands
- Multiple package managers for CLI tools
Usage/Examples (required)
- Runnable code snippets
- Common use cases
Features (recommended)
- Bullet list of key capabilities
API/Configuration (if applicable)
- For libraries: key types and functions

5. Improve Existing README

[!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:
- Missing essential sections?
- Outdated badges?
- No code examples?
- Wall of text without structure?
Common improvements:
- Add missing badges
- Add installation section if missing
- Add usage examples if missing
- Break up long paragraphs
- Add table of contents if >500 words
- Update outdated version numbers
Preserve existing content:
- Keep custom sections
- Maintain existing links
- Preserve contribution history acknowledgments

Badge Reference

See references/badges.md for complete badge syntax by ecosystem.

Quick reference:

<!-- Rust -->
[![Crates.io](https://img.shields.io/crates/v/CRATE)](https://crates.io/crates/CRATE)
[![docs.rs](https://img.shields.io/docsrs/CRATE)](https://docs.rs/CRATE)

<!-- TypeScript/npm -->
[![npm](https://img.shields.io/npm/v/PACKAGE)](https://www.npmjs.com/package/PACKAGE)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/PACKAGE)](https://bundlephobia.com/package/PACKAGE)

<!-- Python -->
[![PyPI](https://img.shields.io/pypi/v/PACKAGE)](https://pypi.org/project/PACKAGE)
[![Python](https://img.shields.io/pypi/pyversions/PACKAGE)](https://pypi.org/project/PACKAGE)

Quality Checklist

Before completing, verify:

One-line description is clear and specific
Badges are valid and ecosystem-appropriate
Installation commands are copy-pasteable
At least one runnable code example
License is specified
No broken links
No placeholder text remaining
Callouts used for warnings, tips, and important notes (GitHub/crates.io only — avoid for PyPI and npm)

Anti-patterns to Avoid

[!CAUTION] These mistakes make READMEs significantly worse. Check against this list before completing.

Wall of text without headers
Generic descriptions ("A tool for doing things")
Missing installation section
No code examples
Outdated badges/version numbers
Excessive badges (>6 is usually too many)
TOC for short READMEs (<300 words)

Weekly Installs

Repository

bug-ops/claude-plugins

GitHub Stars

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPass SocketFail SnykPass

Installed on

amp1

cline1

opencode1

cursor1

kimi-cli1

codex1

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

109,600 周安装

pyproject.toml or setup.py → Python (use references/python.md)

For CLI: command-line arguments

For services: environment variables

Contributing (recommended)

Link to CONTRIBUTING.md if exists
Basic guidelines otherwise

License (required)

License name with link to LICENSE file