readme-author

name	readme_author
description	编写或修订面向公开分享的项目 README，特别是"主要自己用、顺便公开"的个人项目。 当用户说"写 README"、"改 README"、"公开版的 README"、"整理一下 README"、 "做个 public release 的 readme"、"README 太弱了"、"awesome-readme"、"README 怎么写"时触发。 也适用于用户提到 awesome-readme 仓库、要把私有项目 README 改成公开版、需要校准 README 语气时。 覆盖从零起草和增量修订两种模式，含公开项目特有陷阱（过度承诺、部署门槛伪装、竞品对比翻车）。
task_type	adhoc.readme_author
trust	native

readme_author — 公开项目 README 编写指南

何时调用此 skill

显式触发：

• "帮我写个 README" / "改一下 README" / "README 公开版"
• "这个项目要开源，README 怎么写"
• " awesome-readme " / "参考 awesome-readme 改改"
• "README 太啰嗦了" / "README 没说清这东西是干啥的"
• "公开前过一遍 README"

Agent 主动触发：

• 用户准备公开/分发项目（走 public-release skill 时联动）
• 用户做竞品调研后转变项目定位，README 还停留在旧的自我定位
• README 与实际能力严重不符（过度承诺或过度自贬）

何时不调用

• 私有项目的内部文档 — 走 neat-freak 同步 AGENTS.md / _index.md
• 技能文件 SKILL.md — 走 skill-creator
• 架构文档 / API 文档 — 走 neat-freak 或专门写 docs/
• CHANGELOG / 发版说明 — 走 system.release 工作流

核心哲学

README 不是产品说明书，是作者和读者的一次诚实对话。读者花 30 秒决定要不要继续看，这 30 秒里 README 必须回答三件事：

1. 这是什么（一句话能讲清，否则你自己也没想清）
2. 谁会用 / 谁不会用（明确的边界比"all welcome"更可信）
3. 凭什么用你的（不和竞品比就等于没说）

反模式：把 README 当作 feature list 列表 — 那是 CHANGELOG 的工作。

公开项目 README 的 7 段结构

参考 awesome-readme 社区精选范例归纳，面向公开分享的个人项目典型结构如下，按需裁剪：

段	作用	长度	写作要点
1. 一句话定位	30 秒决策	1-2 行	不堆形容词；如果是"主要自己用"的项目，明说
2. 这是什么 / 不是什么	边界澄清	1 段	"不是什么"往往比"是什么"更有信息量
3. 为什么写这个 / 定位	作者动机	1-2 段	公开个人项目必填：诚实交代"为什么公开"
4. 能力一览	让读者评估价值	表格/列表	不要 feature dump；按读者画像分组
5. 快速开始	让想试的人能试	代码块	诚实标注门槛；"努力一下能跑起来"是底线
6. 架构 / 核心概念	给好奇者深读	可选	链接到详细文档而不是全塞进 README
7. 局限性 + License + 致谢	收尾 + 信任建立	各 1 段	局限性放显眼位置，反而比隐藏更能建立信任

反顺序的合理情形：CLI 工具 / 演示项目可以把"快速开始"提到第 2 位（先让人跑起来再说）。但个人项目不建议 — 读者先理解你的动机，才能正确评估"值不值得我花时间部署"。

第 0 步：写之前先收集上下文

任何写作前必须明确以下 5 项；任何一项不清楚就 AskUserQuestion 问用户：

1. 项目自我定位：是工具？框架？参考实现？作品集？多身份并存？
2. 作者态度：主动维护 / 顺手公开 / 已弃坑 / 展示能力 / 找合作者？
3. 目标读者：会用类似工具的开发者？潜在雇主？朋友？随机路人？
4. 部署故事：能 clone 就跑？需要环境配置？需要密钥？基本跑不起来？
5. 差异化：相比竞品/同类，唯一值得讲的 1-2 个点是什么？（不是 feature 列表，是"如果只能保留一句话描述这个项目，是哪句"）

关键原则：如果第 5 项答不上来，先做竞品调研再写 README。一个不知道自己为什么存在的项目，README 写得再漂亮也是包装纸。

第 1 步：选定 tone（语气校准）

公开个人项目的语气谱系（按"作者姿态"由高到低）：

Tone	特征	适用	风险
官方产品型	"Powerful, Easy, Modern"	商业开源 / 想拉 star	个人项目用这种最违和，容易被一眼看穿
工程师作品集型	"I built this to solve X. Here's how it works."	求职 / 技术展示	偏自夸，但可接受
诚实自用型	"主要自己用，公开是因为 X。你愿意折腾就试试。"	大多数个人项目	推荐；反而最容易建立信任
自嘲型	"又一个轮子，慎用"	小工具	容易低估自己 / 显得没价值
过度防御型	"别用，没用，真的"	—	反模式；读者会觉得作者在求夸

校准方法：把第 0 步的"作者态度"和"目标读者"投影到谱系上，取交集。默认推荐"诚实自用型" — 适合 90% 的个人公开项目。

第 2 步：处理"竞品对比"这个雷区

竞品对比是公开 README 最容易翻车的段落。规则：

✅ 该做

• 承认竞品存在且更强："每个独立功能都有更强的对应产品（X / Y / Z）" — 这是诚实
• 说清差异化维度："但它们要么不开源，要么只解决单点；本项目的价值在 A+B+C 的聚合"
• 给出明确推荐："如果你只需要 X，直接用 [竞品]；如果你需要 X+Y+Z 且能接受折腾，可以试这个"
• 承认不适合的场景："期待 W 的用户会失望"

❌ 不要做

• 拉踩竞品：贬低别人不会让你变强
• 假装唯一：每个功能都说"the only / first / best"
• 回避对比：读者会自己 Google，与其让他们发现你藏着掖着
• 过度谦虚到反推销："这个项目很烂但反正也没人用" — 那为什么要公开？

第 3 步：写"快速开始"的诚实原则

公开个人项目的"快速开始"必须回答：

问题	推荐写法
跑起来需要什么环境？	明确列出 OS / 依赖 / 权限（如"需管理员权限"）
大概要花多久？	笼统但诚实："5 分钟" / "半小时" / "需要折腾一阵"
需要什么密钥？	哪些是必需，哪些是可选；指向模板而非明文
跑不起来怎么办？	给一个 troubleshooting 入口（docs 链接 / Issue 模板）

反模式：

• 写"<5 分钟搞定"但实际要装 CUDA、配 3 个 API key、跑数据库迁移
• 写"easy to install"然后 200 行 bash 脚本
• 完全不写部署文档，让读者自己 grep 代码

底线："努力一下能跑起来"是公开个人项目的最低承诺。如果连这个都做不到，README 里要明说"目前主要自己用，部署文档不全，欢迎 Issue 但不保证回复"。

第 4 步：增量修订 vs 从零起草

从零起草

按 7 段结构顺序写。每段写完问自己："如果读者只看这一段，他会做什么决定？" 答不上来就重写。

增量修订（更常见）

1. 先读完整 README，不要边读边改
2. 画一张"当前结构 vs 目标结构"映射表：哪些段保留 / 哪些段调整 tone / 哪些段新增 / 哪些段删
3. 按"动 tone 最少 → 动结构最多"顺序改：先调语气（最少改动），再补/删段（最大改动）
4. 改完后整篇通读一遍：检查段间衔接是否还通顺，新增段是否和保留段语气一致

常见修订场景

场景	修订要点
项目定位转变（如从"工具"变"兜底层"）	改一句话定位 + 新增"为什么公开/定位"段 + 调整"和别的项目不同的地方"段
准备公开但原 README 是私有自用 tone	全篇 tone 校准；补 Limitations 和 License 段；删内部链接
新增竞品调研后想重新定位	新增"竞品对比"段（按第 2 步规则）；调整"凭什么用你的"段
部署门槛变化	重写"快速开始"；诚实标注门槛

第 5 步：反模式清单（写完必查）

内容反模式

• 一句话定位里超过 2 个形容词 — 形容词越多越没信息量
• Feature dump — 把每个 feature 都列出来，读者无法判断哪些是核心
• "Powerful / Easy / Modern / Production-ready" — 公开个人项目用这些词几乎都是过度承诺
• 隐藏部署门槛 — "easy to install" 但需要 5 个密钥 + GPU + 管理员权限
• 不提竞品 — 读者会自己搜，不如主动 frame
• 过度自贬 — "这个项目很烂" — 那为什么要公开？
• 把 README 当 CHANGELOG — 完整变更历史应进 CHANGELOG.md，README 只讲"现在是什么"

结构反模式

• 目录过长（>3 级） — README 不是文档站，过长说明该拆到 docs/
• 架构图塞在前面 — 读者还没看懂这是什么，看架构图没用
• 每段都引用别的文档 — 读者点进去出不来，README 失去意义
• License / 致谢 / 贡献指南散落各处 — 集中收尾

Tone 反模式

• 官方产品型语气用于个人项目 — "We are excited to announce..." → "I built this because..."
• 过度防御 — "Don't use this in production" 重复 3 次 → 1 次就够
• 乞求 star / 求 PR — 个人项目 NC license 下尤其违和
• 感谢段写得太煽情 — 简洁列出引用来源即可

第 6 步：交付前 checklist

写完 / 改完后逐项检查：

内容自检

• 30 秒测试：找一个没看过这个项目的人（或模拟），让他读 30 秒后回答"这是什么 / 谁会用 / 凭什么用你的" — 三个都答得出才算过关
• 诚实度测试：每个形容词和承诺后面，能不能补一句"具体指什么" — 答不上来就是空话
• 竞品测试：读者 Google 类似项目时，README 是否提前 frame 了对比？
• 部署诚实度：快速开始里的步骤，是否真的能让"努力一下的人"跑起来？

结构自检

• 一句话定位 ≤ 2 行
• 段间衔接通顺（无突兀跳跃）
• 表格 / 代码块格式正确（GitHub 渲染检查）
• 内部链接都指向存在的文件
• 外部链接（竞品 / 参考）指向正确仓库

项目规则自检（本仓库特有）

• 改完后 README_public.md 没有泄露私有路径（F:\ / 个人邮箱 / 内部 IP）
• 没有引用 gitignored 文件作为关键文档（如 temp/ private_vault/ chrome_debug/）
• 链接的 docs/ 文件实际存在
• 版本号 badge 与 server/core/version.py（或对应版本常量）一致

与其他 skill 的关系

• public-release：源码分发审计与打包；README 修订常作为公开前的最后一步，由 public-release 编排调用本 skill
• neat-freak：会话后文档同步；本 skill 聚焦 README 起草/修订，neat-freak 聚焦文档一致性
• skill-creator：写 SKILL.md（skill 定义文件）；本 skill 写 README.md（项目门面文件）— 两者面向不同读者
• deep_research：写 README 前如果对竞品不熟，先用 deep_research 做竞品调研，再回来按第 2 步规则写对比段

参考资源

• awesome-readme — 社区精选 README 范例集（注意：是范例集合，不是写作规范）
• Make a README — README 基础写作指南
• Standard Readme Spec — 一个流行的 README 规范提案
• 本项目自身的 README_public.md — "诚实自用型" tone 的实践样本