readme-maker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

@rules/project-discovery.md @rules/section-design.md @rules/validation.md @references/readme-templates.md

README Maker

README生成器（README Maker）

Read the project carefully, then write the README the project actually deserves.

Generate a project
```
README.md
```
grounded in the real codebase, not boilerplate.
Refactor stale or generic READMEs so install, usage, structure, and examples match current code.
Adapt section choice and depth to project shape (CLI, library, web app, monorepo, plugin, framework, docs site, service).
Preserve evidence: every install command, script, badge, and example traces back to a file in the repo.

</purpose>

<routing_rule>

Use

readme-maker

when the primary deliverable is a

README.md

(root or sub-package) for a project, library, CLI, plugin, workspace, framework, docs site, or service.

Route neighboring work elsewhere:

Use
```
docs-maker
```
when the output is a general doc, runbook, instruction base, or harness rule pack.
Use
```
prd-maker
```
when the output is a product planning package (PRD, diagram, feature spec, user flow, wireframe).
Use
```
seo-maker
```
when the output is an SEO/AEO/GEO audit or marketing-page optimization.
Use
```
research
```
when the job is pure fact-finding with no README artifact.
Use
```
version-update
```
when the main job is bumping a version or producing release notes.
Use
```
git-commit
```
or
```
git-maker
```
when the main job is committing a README change after the README is finalized.

Do not use

readme-maker

when:

the user wants only a
```
CHANGELOG.md
```
,
```
CONTRIBUTING.md
```
,
```
LICENSE
```
, or other non-README file
the user wants source-code edits, refactors, or feature implementation and only mentions README in passing
the user wants live external research with no README artifact
the user wants AI-readable instruction docs or harness rule packs (use
```
docs-maker
```
)

</routing_rule>

<instruction_contract>

Field	Contract
Intent	Produce or improve a `README.md` that reflects the real shape, install, usage, and constraints of the target project.
Scope	Own the target `README.md` (root or package) and a short summary; do not edit source code, configuration, license, or unrelated docs unless the user asks.
Authority	User instructions and project-local docs ( `AGENTS.md` , `CLAUDE.md` , root README, package manifests) outrank generic README conventions and external templates.
Evidence	Ground every install command, script invocation, file path, badge, and feature claim in a real file under the project. Do not invent commands or APIs.
Tools	Use read/edit/write and shell search ( `find` , `grep` , `ls` ) only inside the project. Do not run install, build, deploy, or release commands as part of authoring.
Output	A single written or updated `README.md` , plus a short summary noting which files were inspected and which sections changed.
Verification	Run project-discovery, shape, language, and evidence checks from `rules/validation.md` before completion.
Stop condition	Finish when checks pass and any uncertain claims are flagged with `<!-- TODO -->` ; escalate when project shape is ambiguous, license is unclear, or commands cannot be verified from the repo.

</instruction_contract>

<activation_examples>

Positive requests:

"Read this project carefully and create a README.md."
"Refactor the README so it matches the current CLI commands."
"Generate a README for the
```
packages/color
```
workspace in this monorepo."
"Update the install and usage sections of README to reflect the new entry point."
"프로젝트 README.md 만들어줘." (Korean positive create request; should trigger.)
"이 저장소를 꼼꼼히 읽고 README를 다시 써줘." (Korean refactor request; should trigger.)

Negative requests:

"Create a CHANGELOG from the commit log." Use
```
git-commit
```
/
```
version-update
```
paths instead.
"Write API documentation for this library." Use
```
docs-maker
```
.
"Plan the next release of this project." Use
```
prd-maker
```
or
```
plan
```
.
"이 코드베이스에 새 기능을 추가해줘." (Korean feature request; not a README task.)

Boundary requests:

"Document this project." Use
```
readme-maker
```
only when the output is a
```
README.md
```
. Use
```
docs-maker
```
when the output is a guide, runbook, or instruction base.
"Refactor this README and commit the change." Use
```
readme-maker
```
for the README itself; route the commit to
```
git-commit
```
or
```
git-maker
```
after the README is finalized.
"이 README 리팩터하고 커밋도 같이 해줘." (Korean boundary; README first via
```
readme-maker
```
, then commit via
```
git-commit
```
/
```
git-maker
```
.)

</activation_examples>

<trigger_conditions>

Situation	Mode
Project has no `README.md`	create
`README.md` exists but is stale, generic, or contradicts current code	refactor
Specific sections need updating after a feature, rename, or move	update
A sub-package or workspace inside a monorepo needs its own README	create
README needs to align with the project's primary documentation language	refactor

</trigger_conditions>

<supported_targets>

Root
```
README.md
```
of an app, library, CLI, plugin, framework, docs site, or service.
Package-level
```
README.md
```
inside a monorepo workspace.
README refactors that re-derive sections from current code.
README updates that touch install, usage, configuration, scripts, examples, or project structure.
Language alignment when project docs are predominantly Korean, English, or another language.

</supported_targets>


README.md
rules/project-discovery.md
AGENTS.md
rules/section-design.md
README.md
rules/validation.md

Phase	Task	Output
0	Confirm the deliverable is a `README.md` ; pick `create` / `refactor` / `update`	Mode decision
1	Scan project structure and detect shape ( `rules/project-discovery.md` )	Project profile
2	Read existing README, `AGENTS.md` , `CLAUDE.md` , license, manifests, and entry points	Evidence base
3	Pick sections, order, depth, and language ( `rules/section-design.md` )	Section plan
4	Draft or refactor `README.md` using grounded examples and templates from `references/readme-templates.md`	Updated README
5	Run validation checks ( `rules/validation.md` ) and write the completion summary	Final README + summary

仔细研读项目，为其生成真正适配的README。

<用途>

基于真实代码库生成项目
```
README.md
```
，而非通用模板内容。
重构过时或通用化的README，使安装、使用、结构及示例与当前代码保持一致。
根据项目类型（CLI、library、web app、monorepo、plugin、framework、docs site、service）调整章节选择及深度。
保留溯源依据：每条安装命令、脚本、徽章及示例均可追溯至仓库中的对应文件。

</用途>

<路由规则>

当主要交付物是项目、library、CLI、plugin、工作区、framework、docs site或service的

README.md

（根目录或子包）时，使用

readme-maker

。

其他相关任务请路由至对应工具：

若输出为通用文档、运行手册、指令库或规则包，请使用
```
docs-maker
```
。
若输出为产品规划包（PRD、流程图、功能规格、用户流程、线框图），请使用
```
prd-maker
```
。
若输出为SEO/AEO/GEO审计或营销页面优化内容，请使用
```
seo-maker
```
。
若仅需纯事实调研且无需生成README，请使用
```
research
```
。
若主要任务是版本升级或生成发布说明，请使用
```
version-update
```
。
若主要任务是在README定稿后提交变更，请使用
```
git-commit
```
或
```
git-maker
```
。

以下场景请勿使用

readme-maker

：

用户仅需要
```
CHANGELOG.md
```
、
```
CONTRIBUTING.md
```
、
```
LICENSE
```
或其他非README文件
用户需要对源代码进行编辑、重构或功能实现，仅顺带提及README
用户需要实时外部调研且无需生成README
用户需要AI可读的指令文档或规则包（请使用
```
docs-maker
```
）

</路由规则>

<指令约定>

字段	约定
意图	生成或优化能反映目标项目真实类型、安装方式、使用方法及约束条件的 `README.md` 。
范围	负责目标 `README.md` （根目录或子包）及简短总结；除非用户要求，否则不得编辑源代码、配置、许可证或无关文档。
优先级	用户指令及项目本地文档（ `AGENTS.md` 、 `CLAUDE.md` 、根目录README、包清单）优先于通用README规范及外部模板。
溯源依据	每条安装命令、脚本调用、文件路径、徽章及功能声明均需基于项目中的真实文件。不得虚构命令或API。
工具使用	仅在项目内部使用读取/编辑/写入及Shell搜索（ `find` 、 `grep` 、 `ls` ）功能。创作过程中不得运行安装、构建、部署或发布命令。
输出	一份已撰写或更新的 `README.md` ，以及一份简短总结，说明已检查的文件及变更的章节。
验证	完成前需执行 `rules/validation.md` 中的项目探测、类型、语言及依据检查。
终止条件	检查通过且所有不确定声明已用 `<!-- TODO -->` 标记后即可完成；若项目类型模糊、许可证不明确或无法从仓库验证命令，则需升级处理。

</指令约定>

<激活示例>

正向请求：

"仔细阅读这个项目并创建一份README.md。"
"重构README使其与当前CLI命令保持一致。"
"为这个单仓库中的
```
packages/color
```
工作区生成一份README。"
"更新README的安装和使用章节以反映新的入口点。"
"프로젝트 README.md 만들어줘."（韩语创建请求；应触发）
"이 저장소를 꼼꼼히 읽고 README를 다시 써줘."（韩语重构请求；应触发）

反向请求：

"从提交日志创建CHANGELOG。" 应改用
```
git-commit
```
/
```
version-update
```
流程。
"为这个库编写API文档。" 应使用
```
docs-maker
```
。
"规划这个项目的下一个版本。" 应使用
```
prd-maker
```
或
```
plan
```
。
"이 코드베이스에 새 기능을 추가해줘."（韩语功能请求；不属于README任务）

边界请求：

"为这个项目编写文档。" 仅当输出为
```
README.md
```
时使用
```
readme-maker
```
；若输出为指南、运行手册或指令库，则使用
```
docs-maker
```
。
"重构这份README并提交变更。" 使用
```
readme-maker
```
处理README本身；README定稿后，将提交任务路由至
```
git-commit
```
或
```
git-maker
```
。
"이 README 리팩터하고 커밋도 같이 해줘."（韩语边界请求；先通过
```
readme-maker
```
处理README，再通过
```
git-commit
```
/
```
git-maker
```
提交）

</激活示例>

<触发条件>

场景	模式
项目无 `README.md`	创建
`README.md` 已存在但过时、通用化或与当前代码矛盾	重构
功能更新、重命名或迁移后需更新特定章节	更新
单仓库工作区中的子包或工作区需要独立README	创建
README需与项目主要文档语言保持一致	重构

</触发条件>

<支持目标>

应用、library、CLI、plugin、framework、docs site或service的根目录
```
README.md
```
。
单仓库工作区内的包级
```
README.md
```
。
从当前代码重新推导章节的README重构。
涉及安装、使用、配置、脚本、示例或项目结构的README更新。
项目文档以韩语、英语或其他语言为主时的语言对齐。

</支持目标>

<工作流程>


README.md
rules/project-discovery.md
AGENTS.md
rules/section-design.md
references/readme-templates.md
rules/validation.md

阶段	任务	输出
0	确认交付物为 `README.md` ；选择「创建/重构/更新」模式	模式决策
1	扫描项目结构并检测类型（ `rules/project-discovery.md` ）	项目概况
2	读取现有README、 `AGENTS.md` 、 `CLAUDE.md` 、许可证、清单及入口点	依据库
3	选择章节、顺序、深度及语言（ `rules/section-design.md` ）	章节规划
4	使用 `references/readme-templates.md` 中的可信示例及模板撰写或重构 `README.md`	更新后的README
5	执行验证检查（ `rules/validation.md` ）并撰写完成总结	最终README + 总结

Phase 4 authoring rules

第4阶段创作规则

Read first, write second. Never invent install commands, scripts, environment variables, or APIs.
Match the project's primary documentation language. If
```
AGENTS.md
```
,
```
CLAUDE.md
```
, or the existing README is Korean, write the README in Korean.
Prefer one accurate example over three speculative ones.
Keep the README scannable: title, description, install, and quickstart belong above the fold.
Move long deep-dive content out of the README and link to it; the README should orient, not exhaust.
Do not add badges that cannot be verified (CI status, coverage, npm version) unless the project already publishes them.

</workflow> <modes>

先读再写。不得虚构安装命令、脚本、环境变量或API。
匹配项目主要文档语言。若
```
AGENTS.md
```
、
```
CLAUDE.md
```
或现有README为韩语，则README使用韩语撰写。
优先选择一个准确示例，而非三个推测性示例。
保持README易读：标题、描述、安装及快速入门应位于首屏可见区域。
将长篇深入内容移出README并添加链接；README应起到引导作用，而非详尽罗列。
不得添加无法验证的徽章（CI状态、覆盖率、npm版本），除非项目已发布此类徽章。

</工作流程>

<模式说明>

create mode

创建模式

Start from the project profile and pick the matching template in
```
references/readme-templates.md
```
.
Include only sections supported by real evidence in the repo.
Mark unknowns explicitly with
```

```
instead of fabricating.

从项目概况出发，选择
```
references/readme-templates.md
```
中的匹配模板。
仅包含仓库中真实依据支持的章节。
明确标记未知内容，使用
```

```
而非虚构信息。

refactor mode

重构模式

Preserve correct existing content; rewrite only sections that drift from the code.
Re-derive install, usage, scripts, and structure sections from current files.
Keep links, badges, and prose that still hold; remove dead links and stale commands.

保留正确的现有内容；仅重写与代码不符的章节。
从当前文件重新推导安装、使用、脚本及结构章节。
保留仍有效的链接、徽章及文案；移除无效链接及过时命令。

update mode

更新模式

Touch only the sections the user named or the diff implies.
Append a dated entry to a change-history section only if the project README already tracks one.

</modes> <forbidden>

Category	Avoid
Fabrication	Install commands, scripts, environment variables, or APIs not present in the repo
Drift	Stale screenshots, broken links, deprecated commands left in place
Overload	Embedding full API references, long tutorials, or design docs inside the README
Tone	Marketing fluff, vague superlatives, hype the code does not support
Side effects	Editing source code, configs, or licenses while authoring the README
Extra files	Creating `CHANGELOG.md` , `CONTRIBUTING.md` , or other docs unless the user asks

</forbidden> <required>

Category	Required
Evidence	Every install/usage line maps to a manifest, script, source file, or existing doc in the repo
Shape match	Section selection matches the detected project type
Language match	README language matches the project's primary documentation language
Discoverability	Title, one-line description, install, and quickstart are above the fold
Verification	Validation checklist completed before claiming done

</required>

<structure_blueprint>

Default README outline (adapt by project type per

references/readme-templates.md

Title + one-line description
Optional badges (only when verifiable)
Features or highlights (3-7 bullets max)
Install
Quickstart / Usage
Configuration / Environment
Commands or API surface (CLI, library, plugin)
Examples
Development (build, test, dev server, scripts)
Project structure (only when non-trivial)
Contributing (only if the project documents a process)
License

</structure_blueprint>

Check	Rule
Evidence	Each command and path in the README exists in the repo
Shape	The selected template matches the actual project type
Language	README language matches existing project docs
Above the fold	Title, description, install, and quickstart appear within the first screen
No fabrication	No invented APIs, scripts, env vars, or external badges
Lean body	Long content is linked, not inlined
Translation pair	If the skill itself or other markdown was edited, English/Korean files stay aligned

Must-pass thresholds:

Project shape detected and recorded in the completion summary
At least one verified install command and one verified usage example
Existing README sections that remain accurate are preserved (refactor/update mode)
Unknowns are marked with
```

```
, not fabricated
No dead links or removed scripts left in the new draft

</validation>

仅修改用户指定或代码差异暗示的章节。
仅当项目README已跟踪变更历史时，才在变更历史章节添加带日期的条目。

</模式说明>

<禁止操作>

类别	禁止内容
虚构	仓库中不存在的安装命令、脚本、环境变量或API
脱节	保留过时截图、无效链接、废弃命令
过载	在README中嵌入完整API参考、长篇教程或设计文档
语气	营销话术、模糊的最高级表述、代码无法支撑的夸大宣传
副作用	创作README时编辑源代码、配置或许可证
额外文件	创建 `CHANGELOG.md` 、 `CONTRIBUTING.md` 或其他文档，除非用户要求

</禁止操作>

<必填要求>

类别	必填内容
依据	每条安装/使用内容均对应仓库中的清单、脚本、源代码或现有文档
类型匹配	章节选择与检测到的项目类型一致
语言匹配	README语言与项目主要文档语言一致
可发现性	标题、单行描述、安装及快速入门位于首屏可见区域
验证	完成前需执行验证检查清单

</必填要求>

<结构蓝图>

默认README大纲（根据

references/readme-templates.md

按项目类型调整）：

标题 + 单行描述
可选徽章（仅可验证时添加）
特性或亮点（最多3-7个项目符号）
安装
快速入门 / 使用方法
配置 / 环境变量
命令或API接口（CLI、library、plugin）
示例
开发（构建、测试、开发服务器、脚本）
项目结构（仅非通用结构时添加）
贡献指南（仅当项目有明确流程文档时添加）
许可证

</结构蓝图>

<验证规则>

检查项	规则
依据验证	README中的每条命令及路径均存在于仓库中
类型匹配	所选模板与实际项目类型一致
语言匹配	README语言与现有项目文档一致
首屏内容	标题、描述、安装及快速入门位于首屏可见区域
无虚构内容	无虚构的API、脚本、环境变量或外部徽章
内容精简	长篇内容通过链接引用，而非嵌入
翻译对齐	若技能本身或其他markdown文件被编辑，英文/韩文文件需保持一致

必须通过的阈值：

已检测项目类型并记录在完成总结中
至少包含一条已验证的安装命令和一条已验证的使用示例
保留现有README中仍准确的章节（重构/更新模式）
未知内容已用
```

```
标记，未虚构信息
新草稿中无无效链接或已移除的脚本

</验证规则>