readme-creator

README 创作

编写的 README 应该像商店橱窗，而不是维基百科。

• **是：**为决定是否使用项目的人编写或重写 README.md。根据项目类型决定哪些功能板块值得保留；根据文件的展示位置（仅 GitHub，或还包括注册表页面）决定图片和徽章的选择。
• **不是：**润色已经涵盖项目内容的 README 文案，也不是创建多页文档站点（使用 docs-writing）；不是编写 AGENTS.md 或 CLAUDE.md Agent 指令文件（使用 agents-md）；不是修复 README 所描述的安装或首次运行体验（使用 dx-audit）；也不是为落地页撰写营销文案（使用 copywriting）。

读者

读者来自搜索结果、注册表列表或个人资料页面。他们只有大约 15 秒，只想知道一件事：这个项目值得我花时间吗？每一行要么回答这个问题，要么删掉。

他们不是贡献者。构建流水线、工作区布局、发布流程或编码规范都无助于他们做出决定，因此这些内容不该出现在这里。

这有意区别于 standard-readme 和 Make a README：后者要求添加 ## Contributing，超过 100 行时添加目录，还认为过长胜过过短。不要回到这些默认做法：贡献者相关内容应移至 CONTRIBUTING.md 或 AGENTS.md，篇幅则应以读者的需要为准。

参考文件

文件	阅读时机
references/section-templates.md	阶段 3：每个核心板块的标记、功能板块菜单及各类型项目的说明
references/badges-and-shields.md	阶段 4：仅当阶段 1 确认项目有注册表列表（npm、crates.io、PyPI、VS Code Marketplace、skills.sh）时阅读
references/quality-checklist.md	阶段 5：完成前评分

语气

起草前，检查外部 ghostwriter 技能中是否有配置文件：${GHOSTWRITER_HOME:-~/.config/ghostwriter}/readme.md。如果存在，以其中规定的语体、拼写规范和任何特定风格标记（页眉区块、徽章颜色、页脚署名）为准；若与本技能有冲突，一律以该配置文件为准。遵循配置文件，不要在此重复说明。

如果没有配置文件，默认使用简洁的第二人称祈使句，不用表情符号和感叹号，多用具体数字，少用形容词。

工作流

复制此清单以跟踪进度：

README progress:
- [ ] Phase 1: Detect project type and where the README renders
- [ ] Phase 2: Fix the spine, then choose capability sections
- [ ] Phase 3: Write each section from the template
- [ ] Phase 4: Add badges (registry-listed projects only)
- [ ] Phase 5: Score against the checklist; report the pass count and render-check output

阶段 1：检测项目类型和呈现目标

读取清单（package.json、Cargo.toml、pyproject.toml、go.mod）中的名称、描述、许可证、脚本、bin、"private" 和 repository。如果要重写 README，请读取现有 README。扫描顶层目录结构。

将项目归为且仅归为一种类型。按顺序检查，下表中第一个匹配项优先：

类型	决定性信号
Skill 集合	包含 SKILL.md 文件的 skills/ 目录
Monorepo	工作区配置（turbo.json、pnpm-workspace.yaml、workspaces）
CLI 工具	存在 bin 字段、src/cli.*，或 commander/yargs/clap 依赖
框架	插件/中间件架构、配置 API、文档化的扩展点
库 / 包	设置了 main/exports，没有 bin，且存在 src/index.* 入口
Web 应用	框架配置（next.config.*、vite.config.*）；不发布

**对于 README 而言，Monorepo 不是项目类型。**它是一种交付方式。想想陌生用户会安装或访问什么，然后围绕它编写 README：如果仓库中的 apps/cli 会发布到 npm，那么根目录应该放 CLI README，而不是工作区表格。工作区目录结构应写在 AGENTS.md 中。

如果仍有两种类型都符合（例如同时导出 API 的 CLI，或作为库发布的框架），请选择大多数用户实际使用的方式，并用一个额外章节说明次要角色。

然后记录该文件会在哪里呈现。"private": true 的清单或没有注册表条目，表示只在 GitHub 上呈现。已发布的包也会在 npmjs.com、PyPI 或 crates.io 上呈现，因此图片 URL 会有所不同，也需要添加徽章（参见阶段 4 和注意事项）。

只向用户询问代码无法揭示的信息：

• 这个项目解决什么问题（标语背后的“原因”）？
• 是否有必须包含或排除的章节？

如果无法联系到用户，就从清单和代码中推断“原因”，在总结中说明这一假设，然后继续，不要因此停滞。

阶段 2：先确定主干，再选择功能章节

在适用时采用以下标准主干。托管应用可以用其在线 URL 代替安装命令；对于通过浏览器使用的产品，不要凭空编造安装步骤：

1. 页首区块（标题、标语、纯文本第二行、已上架注册表时添加徽章）
2. ## Demo（仅在存在在线 URL 时）
3. ## Install
4. ## Quickstart
5. ## License

功能章节放在 Quickstart 和 License 之间：从 references/section-templates.md 中的选项里挑选两到四个。四个是上限，因为第五个章节几乎总是把面向贡献者的内容伪装成面向读者的标题；如果确实有利于读者，则在总结中说明原因，不要默默添加。

使用规范的标题名称，以便保持仓库间的一致性：Install、Quickstart、Demo、License。不要使用 Installation、Getting Started、Quick start、Quick Start、Licence。全文使用句首字母大写格式，因此应写作 ## Browser support，而不是 ## Browser Support。

**受众筛选。**撰写任何章节之前，先问问它能否帮助某人决定是否使用该项目，还是只对修改项目的人有帮助。面向贡献者的内容应放入 CONTRIBUTING.md 或 AGENTS.md（目标文件对照表见 references/section-templates.md），README 中最多保留一行指引。如果目标文件不存在，就创建它：删掉承载关键信息的设置说明，后果比 README 稍长更糟。

阶段 3：撰写各个章节

从 references/section-templates.md 复制各章节的骨架，填写内容，然后按照该文件末尾针对不同类型的说明进行调整。以下规则适用于所有类型：

• 标题使用带空格和大写字母的显示名称（如「React Vello」，而不是 react-vello）；如果有官方网站，则链接到该网站。
• 标语紧接标题下方，不加标题，长度约为 8 到 16 个词，说明项目能做什么，而不是项目是什么。以项目名称开头，会浪费读者刚在 H1 中看到的前三个词。
• 第二行用一个普通句子说明你实际会用它做什么。
• 安装使用最快的单条命令，并从清单的 name 字段复制（绝不要从可能早于重命名的旧 README 中复制）。只写一条命令，不要列出四个标签页式的 npm/pnpm/yarn/bun 命令矩阵；偏好其他包管理器的用户可以自行转换 npm install。
• 快速入门使用能产生可见输出的最短完整示例。即使因此成为文件中最长的代码块，也要保持完整；截断的示例只会在读者粘贴后才出错。
• 每个代码块复制粘贴后都能直接运行：不使用伪代码、占位导入、foo、bar、my-app 或 your-name-here。使用真实端口、真实分支名称和真实十六进制颜色。
• 长度按需决定。大多数内容在 40 到 90 行之间；包含实际标志表的 CLI 文档可达 120 行。超过约 130 行时，应改用文档网站或 docs/ 文件夹，并从 README 链接过去。
• 章节使用 ##；只有在某个章节内确实需要区分并列变体时才使用 ###，例如 CLI 的安装方式。

阶段 4：添加徽章

除非阶段 1 找到了软件包注册表条目，否则跳过。未发布的应用和内部单体仓库的标题区块不带徽章行。软件包注册表条目还包括技能包的 skills.sh，它提供安装次数徽章端点；仓库自己的 README 也使用了该端点。

需要徽章时，加载 references/badges-and-shields.md。默认使用两个：版本和许可证（技能包则使用安装次数和许可证），并采用统一的样式和配色方案，让一组仓库看起来风格一致。指向永不触发的工作流的 CI 徽章会永久显示失败；星标徽章则重复展示了页面上已有的数字。

阶段 5：验证

使用 references/quality-checklist.md 检查用户使用路径和内部规范。报告可运行示例和链接／渲染检查结果；自评分数不能作为渲染证据。

将以下渲染检查与通过项数量一并附上。每项都必须无输出：

grep -nE "TODO|\{\{" README.md                                      # review candidates, not automatic failures
perl -CSD -ne 'print "$.: $_" if /\x{2014}/' README.md                  # em dashes
grep -nE "^## (Installation|Getting Started|Quick Start|Licence|Development|Tech Stack|Contributing)" README.md
grep -nE '(src|\]\()=?"?\.?/?\.github/assets' README.md                  # relative image paths: fine on GitHub, broken on npm and PyPI, so must be empty for a published package

清单中的自动判定失败项是硬性门槛：缺少描述、缺少安装说明、残留模板内容、无法运行的代码示例，或只服务于贡献者的章节。任何一项存在都意味着尚未完成，无论得分多少。

重写已发布软件包的 README 时，应在摘要中说明 npmjs.com 和 PyPI 显示的是上一次发布时的 README，因此页面要等到下次发布后才会更新。

注意事项

• <div align="center"> 内的空行至关重要。CommonMark 会将 <div> 视为一个持续到下一个空行的 HTML 块，因此紧跟在标签后面的 # Title 会被渲染为字面文本 # Title。<p align="center"> 徽章行和结束标签 </div> 也是如此。
• 相对图片路径（.github/assets/demo.png）在 GitHub 上可以正常显示，但在 npmjs.com 和 PyPI 上会返回 404，因为它们提供的是仓库外的 README。对于已发布的包，请将 src 指向 https://raw.githubusercontent.com/{owner}/{repo}/main/.github/assets/demo.png；文件仍保留在仓库中。
• 仓库外的图片托管服务可能会失效。GitHub 会通过 camo 代理所有外部图片，因此 http:// URL 今天还能加载，但托管服务消失时，截图也会随之失效。请将图片提交到 .github/assets/ 下。
• 深色／浅色徽标使用 <picture>，包含两行 <source media="(prefers-color-scheme: ...)"> 和一个 <img> 回退项。#gh-dark-mode-only URL 片段已弃用。PyPI 会移除 <source>，只显示回退项，因此请将浅色版本设为回退项。
• > [!NOTE] 提示（以及 TIP、IMPORTANT、WARNING、CAUTION）可在 GitHub、npmjs.com 和 crates.io 上渲染。PyPI 会在灰色引用块中显示字面文本 [!NOTE]。每个 README 最多使用一条，仅用于说明会导致安装失败的事项；满篇提示会让 README 看起来像更新日志。
• https://img.shields.io/github/license/{owner}/{repo} 会读取仓库检测到的许可证。如果没有 LICENSE 文件，徽章会显示 license: not identified，这比不放徽章更糟。添加徽章前，请确认文件存在。
• 最常见的重写失败，是已发布包的 README 面向维护者而非使用者。表现为：第一个标题是 ## Workspaces，或安装步骤是 git clone。解决办法不是删减内容，而是为不同的读者撰写。
• 如果库的 README 将 git clone 作为入门步骤，或应用的 README 带有软件包注册表徽章，就说明 Phase 1 中的类型判断有误，会把读者引向死路。修改正文前请先重新分类。
• 请确认软件包已使用你准备写进安装命令的名称发布：npm view {{name}} version（或 cargo search、pip index versions）。README 如果指向未发布或已更名的软件包，读者从第一行起就会碰壁。
• 一次重写多个仓库时，很容易凭猜测写出安装命令。请注明每条命令依据的清单 bin 条目或脚本，并选取一个示例进行粘贴测试。
• 切勿直接发布默认脚手架 README（create-next-app、create-vite）：应彻底替换；读者会认为它已无人维护。
• 功能列表项应使用带冒号的 - **Name:** what it does.。在名称和说明之间使用带空格的连字符（- **Name** - what it does.），看起来像是用来代替破折号，不符合本项目的风格规范。
• ## Features 如果只是重复标语，就会显得多余。请根据读者能获得的内容命名（## Modes、## What you can do、## Keyboard shortcuts），这样每个列表项都必须说明一项能力。

相关技能

何时使用	运行
README 已存在，需要审查文案；或需要完整文档站点	docs-writing
项目需要 Agent 指令（AGENTS.md、CLAUDE.md），包括受众筛选移出的内容	agents-md
README 中说明的安装或首次运行流程本身有问题	dx-audit
标语以外的落地页或营销文案	copywriting
按照用户自己的语气起草内容	在已安装的情况下使用外部 ghostwriter 技能；平台 readme

仅用于维护：evals/evals.json 包含针对本技能变更的回归场景；执行用户任务时不会加载。