readme-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

README Creator

README 生成器

Write or rewrite a README.md tailored to the project type and audience.

根据项目类型和目标受众编写或重写README.md文件。

Reference Files

参考文件

File	Read When
`references/section-templates.md`	Phase 3: choosing structure and writing sections for a specific project type
`references/quality-checklist.md`	Phase 5: validating the finished README against quality standards
`references/badges-and-shields.md`	Phase 4: adding badges after the main content is written

文件	读取时机
`references/section-templates.md`	阶段3：为特定项目类型选择结构并编写章节时
`references/quality-checklist.md`	阶段5：根据质量标准验证完成后的README时
`references/badges-and-shields.md`	阶段4：主内容编写完成后添加徽章时

README Workflow

README 工作流

Copy this checklist to track progress:

text

README progress:
- [ ] Phase 1: Discover project context
- [ ] Phase 2: Choose README structure
- [ ] Phase 3: Write sections
- [ ] Phase 4: Add badges and extras
- [ ] Phase 5: Validate quality

复制以下检查清单以跟踪进度：

text

README progress:
- [ ] Phase 1: Discover project context
- [ ] Phase 2: Choose README structure
- [ ] Phase 3: Write sections
- [ ] Phase 4: Add badges and extras
- [ ] Phase 5: Validate quality

Phase 1: Discover project context

阶段1：识别项目上下文

Read the project before asking questions. Explore files to detect the project type:

Read
```
package.json
```
,
```
Cargo.toml
```
,
```
pyproject.toml
```
,
```
go.mod
```
, or equivalent for name, description, license, dependencies, scripts, and bin field.
Read existing README.md (if rewriting).
Scan directory structure to understand architecture.

Classify into one of six project types:

Type	Signals
CLI tool	`bin` field in package.json, `src/cli.ts` , commander/yargs dependency
Library / package	`main` / `exports` in package.json, no bin field, `src/index.ts`
Web app	`next.config.ts` , `vite.config.ts` , framework dependency, no npm publish
Framework	Plugin/middleware architecture, configuration API, extensibility points
Monorepo	`turbo.json` , `pnpm-workspace.yaml` , `apps/` + `packages/` directories
Skill bundle	`skills/` directory with SKILL.md files

Ask the user only for what cannot be discovered from the code:

What problem does the project solve? (the "why")
Who is the target audience?
Any sections to include or exclude?

提问前先了解项目内容。浏览文件以识别项目类型：

读取
```
package.json
```
、
```
Cargo.toml
```
、
```
pyproject.toml
```
、
```
go.mod
```
或等效文件，获取项目名称、描述、许可证、依赖项、脚本和bin字段信息。
读取已有的README.md（如果是重写场景）。
扫描目录结构以理解项目架构。

将项目归类为以下六种类型之一：

类型	识别特征
CLI工具	`package.json` 中的bin字段、 `src/cli.ts` 文件、commander/yargs依赖项
库/包	`package.json` 中的main/exports字段、无bin字段、 `src/index.ts` 文件
Web应用	`next.config.ts` 、 `vite.config.ts` 文件、框架依赖项、无需发布至npm
框架	插件/中间件架构、配置API、可扩展点
单仓项目	`turbo.json` 、 `pnpm-workspace.yaml` 文件、包含 `apps/` + `packages/` 目录
技能包	包含 `skills/` 目录及SKILL.md文件

仅询问无法从代码中获取的信息：

该项目解决什么问题？（即“价值定位”）
目标受众是谁？
需要包含或排除哪些章节？

Phase 2: Choose README structure

阶段2：选择README结构

Load

references/section-templates.md

Select sections based on the project type:

Section	CLI	Library	App	Framework	Monorepo	Skills
Title + one-liner	yes	yes	yes	yes	yes	yes
Badges	yes	yes	--	yes	yes	--
Features / highlights	yes	yes	yes	yes	--	yes
Install	yes	yes	--	yes	yes	--
Quick start / usage	yes	yes	yes	yes	yes	yes
Options / API reference	yes	yes	--	yes	--	--
Configuration	opt	opt	yes	yes	opt	--
Environment variables	--	--	yes	--	--	--
Packages table	--	--	--	--	yes	--
Skills table	--	--	--	--	--	yes
Requirements	yes	yes	opt	yes	opt	--
Contributing	opt	opt	opt	opt	opt	opt
License	yes	yes	yes	yes	yes	opt

加载

references/section-templates.md

文件。

根据项目类型选择对应章节：

章节	CLI	库	应用	框架	单仓项目	技能包
标题 + 一句话描述	是	是	是	是	是	是
徽章	是	是	--	是	是	--
特性/亮点	是	是	是	是	--	是
安装步骤	是	是	--	是	是	--
快速开始/使用示例	是	是	是	是	是	是
选项/API参考	是	是	--	是	--	--
配置说明	可选	可选	是	是	可选	--
环境变量	--	--	是	--	--	--
包列表	--	--	--	--	是	--
技能列表	--	--	--	--	--	是
系统要求	是	是	可选	是	可选	--
贡献指南	可选	可选	可选	可选	可选	可选
许可证	是	是	是	是	是	可选

Phase 3: Write sections

阶段3：编写章节内容

Load

references/section-templates.md

. Write each section following the template for the detected project type.

Key principles:

Title is the project name. One-liner directly below, no heading.
Feature list above the fold (before Install) so readers see value before effort.
Install: single fastest path first.
```
npm install -g
```
for CLIs,
```
npm install
```
for libraries.
Usage: 3-5 runnable examples, simplest first. Real values, not
```
foo
```
or
```
example
```
.
Every code block must be copy-pasteable and runnable without modification.
A reader should be able to install and run something within 60 seconds.
Progressive disclosure: basic first, advanced later or in linked docs.

加载

references/section-templates.md

文件。根据识别的项目类型，遵循模板编写每个章节。

核心原则：

标题为项目名称，下方直接放置一句话描述，无需额外标题。
特性列表放在“安装”章节之前（首屏可见区域），让读者先看到价值再了解操作成本。
安装步骤：优先展示最快捷的路径。CLI工具用
```
npm install -g
```
，库用
```
npm install
```
。
使用示例：提供3-5个可运行的示例，从最简单的开始。使用真实值，而非
```
foo
```
或
```
example
```
。
所有代码块必须可直接复制粘贴并运行，无需修改。
读者应能在60秒内完成安装并运行某个功能。
渐进式披露：先展示基础内容，高级内容放在后面或链接至其他文档。

Phase 4: Add badges and extras

阶段4：添加徽章及额外内容

Load

references/badges-and-shields.md

. Add badges only if the project is published to a registry. Place directly below the title and one-liner. Maximum 4 badges.

Skip badges entirely for private apps, unpublished projects, and skill bundles.

加载

references/badges-and-shields.md

文件。仅当项目已发布至注册表时才添加徽章。徽章放置在标题和一句话描述下方，最多4个。

私有应用、未发布项目和技能包完全跳过徽章。

Phase 5: Validate quality

阶段5：验证质量

Load

references/quality-checklist.md

. Run through every applicable check. Fix issues before finalizing.

After fixes, reread the README top to bottom to confirm it flows naturally.

加载

references/quality-checklist.md

文件。逐一运行所有适用的检查项。在定稿前修复所有问题。

修复完成后，从头到尾重读README，确认内容逻辑流畅自然。

Anti-patterns

反模式（需避免）

Do not write a README longer than the codebase warrants
Do not include a table of contents for READMEs under 100 lines
Do not use "About" or "Introduction" as the first heading
Do not ship the default create-next-app or create-vite README
Do not include badges for unpublished projects
Do not include a "Features" section that restates the one-liner
Do not write "This project is..." or "This is a..." — describe what it does directly
Do not include empty Contributing or Acknowledgements sections
Do not use
```
foo
```
,
```
bar
```
, or
```
test
```
as example values

不要编写超出代码库规模所需的冗长README
不要为少于100行的README添加目录
不要将“关于”或“简介”作为第一个标题
不要保留create-next-app或create-vite生成的默认README
不要为未发布项目添加徽章
不要添加仅重复一句话描述的“特性”章节
不要使用“这个项目是...”或“这是一个...”的表述——直接描述其功能
不要包含空的“贡献指南”或“致谢”章节
不要使用
```
foo
```
、
```
bar
```
或
```
test
```
作为示例值

Skill Handoffs

技能交接

When	Run
After README is written, audit prose quality	`docs-writing`
If project needs AGENTS.md / CLAUDE.md	`agents-md`

场景	调用对应工具
README编写完成后，审核文案质量	`docs-writing`
如果项目需要AGENTS.md / CLAUDE.md文件	`agents-md`