README Craft

README 写作与优化。从零创建、审计已有、或重写 README。蒸馏自 OMC/ECC 实战 README + awesome-readme/Standard README/Art of README 社区标准 + ClawHub 10+ README skills。当需要为项目写 README、审计 README 质量、或重写现有 README 时使用。不适用于：API 文档生成（用 doc-gen）、CHANGELOG 生成（用 git log）、CLAUDE.md 编写（那是机器配置，不是人类文档）。

_silhouette@lanyasheng

Install

openclaw skills install @lanyasheng/readme-craft

README Craft

写出让人在 30 秒内决定用不用你项目的 README。

不是模板填空。是认知漏斗设计——每一层让读者决定：继续深入，还是转身离开。

模式

模式	说明	适用场景
`create`	从零创建 README	新项目、无 README 的项目
`audit`	评分 + 诊断，不改动文件	想知道 README 好不好
`rewrite`	基于现有 README 重写	README 过时、质量差、AI味重

text

/readme-craft                          # 自动检测模式（有 README → audit，无 → create）
/readme-craft --mode create            # 强制创建
/readme-craft --mode audit             # 只评分不改
/readme-craft --mode rewrite           # 重写现有
/readme-craft --mode audit --score-only # 仅输出分数

When to Use

项目需要一个新 README
现有 README 读起来像 AI 生成的模板
README 超过 6 个月没更新，和代码脱节
开源项目想提升 star/contributor 转化率
内部项目文档让新人看不懂

When NOT to Use

API 参考文档 → 用 doc-gen 或自动生成工具
CLAUDE.md / AGENTS.md → 那是机器配置，结构完全不同
CHANGELOG → 从 git log 生成
纯营销落地页 → README 不是广告，是技术文档

场景: Node.js CLI 工具项目没有 README 输入: /readme-craft reasoning: 检测到无 README.md → create 模式。读取 package.json 发现 "bin" 字段 → CLI 项目类型。输出: ```markdown # logparse

Fast structured log parser for JSON and NDJSON streams.

Quick Start

```bash npm install -g logparse echo '{"ts":"2026-01-01","msg":"hello"}' | logparse --format table ```

Install

...

text

</example>

<example>
场景: README 有 800 行，One-liner 是 "A utility for various things"
输入: /readme-craft --mode audit
输出:

README Audit Report

Score: 52/100 (D)

Category	Score	Max	Issues
Hook	8	25	一行描述模糊（反模式 #7），无 Hero Visual
Onboarding	12	25	Quick Start 有 8 步，应精简到 3 步
...

Anti-patterns: #7 模糊描述, #3 垃圾场, #14 README当API文档

text

</example>

<example>
场景: Python 库的 README 缺少代码示例
输入: /readme-craft --mode rewrite
reasoning: audit 得 61 分(C)。主要扣分：O3 Usage 无代码块(-5)、H3 无 Hero Visual(-7)、C1 Features 用散文(-5)。保留好的部分（安装说明完整、License 正确），补充代码示例和功能表格。
输出: 重写后的 README.md（新分 82 分 A 级），展示 diff 供确认。
</example>

<anti-example>
错误: 用 readme-craft 写 API 文档
原因: README 是项目入口，不是完整文档。API 文档应该在 docs/ 或用 doc-gen 工具。readme-craft 只在 README 中放 API 概览和链接。
</anti-example>

<anti-example>
错误: README 里列出全部 47 个函数的签名和参数
修正: README 只放 Top 3-5 核心 API 的概览表，底部加 `[Full API Reference](docs/api.md)` 链接。
</anti-example>

---

## 核心原则

### 1. 认知漏斗（Cognitive Funnel）

README 的每一层都是一个过滤器。读者在任何一层都可以决定离开或深入。

┌─────────────────────────────────┐ │ 项目名 → 这东西和我有关吗？ │ 0.5 秒 ├─────────────────────────────────┤ │ 一行描述 → 它解决什么问题？ │ 2 秒 ├─────────────────────────────────┤ │ Demo/截图 → 长什么样？ │ 5 秒 ├─────────────────────────────────┤ │ Quick Start → 用起来难不难？ │ 30 秒 ├─────────────────────────────────┤ │ 功能详情 → 能满足我的需求吗？ │ 2 分钟 ├─────────────────────────────────┤ │ API / 配置 → 具体怎么用？ │ 5 分钟 ├─────────────────────────────────┤ │ 贡献指南 → 我能参与吗？ │ 按需 └─────────────────────────────────┘

text


**规则：不要在漏斗上层放下层的信息。** Quick Start 里不放 API 细节。一行描述里不解释架构。

### 2. Show, Don't Tell

一个语法高亮的代码块 > 三段文字描述。一个 GIF demo > 一页功能列表。

### 3. 「无源码测试」

如果有人不看源码就能用你的项目，README 就够了。（Ken Williams 原则）

### 4. 不卖广告

README 的职责是让人快速评估——合适就用，不合适就走。不是让人留下。

### 5. 保持同步

过时的 README 比没有 README 更有害——它会误导人。

---

## Golden Structure

根据项目类型，使用适当的结构。所有类型共享前 3 节和最后 1 节。

### 通用结构（12 节）

| # | Section | 必需 | 说明 |
|---|---------|------|------|
| 1 | **Title + Badges** | 必需 | 项目名 + 状态徽章（CI/version/license） |
| 2 | **One-liner** | 必需 | < 120 字符，和 package manager 描述一致 |
| 3 | **Hero Visual** | 推荐 | GIF demo / 截图 / 架构图（按项目类型选） |
| 4 | **Quick Start** | 必需 | 3 步以内从零到跑通 |
| 5 | **Features** | 推荐 | 要点列表或表格，不要写散文 |
| 6 | **Installation** | 必需 | 所有平台/包管理器的安装方式 |
| 7 | **Usage** | 必需 | 带语法高亮的代码示例 |
| 8 | **Configuration** | 按需 | 环境变量 / 配置文件 / CLI flags |
| 9 | **API** | 按需 | 核心 API 概览（详细文档链到外部） |
| 10 | **Contributing** | 推荐 | 简短说明或链到 CONTRIBUTING.md |
| 11 | **Credits** | 按需 | 致谢、灵感来源 |
| 12 | **License** | 必需 | SPDX 标识符 + 链接到 LICENSE 文件，放在最后 |

### 项目类型适配

| 类型 | Hero Visual | Quick Start 重点 | 特殊节 |
|------|------------|------------------|--------|
| **CLI 工具** | 终端 GIF (vhs/asciinema) | `npm i -g && cmd --help` | Magic Keywords / Commands 表格 |
| **库/SDK** | 代码截图 | `npm i && import` + 3行用法 | API 概览 + 完整文档链接 |
| **Web 应用** | 浏览器截图/GIF | `git clone && npm start` | 技术栈表格、环境变量 |
| **框架** | 架构图 (Mermaid) | `npx create-xxx` | 概念解释、对比表格 |
| **插件/扩展** | 安装截图 | 一键安装命令 | 兼容性表格、依赖关系 |
| **Monorepo** | 目录树 | 顶层入口 + 子包导航 | 包关系图 |

---

## 徽章规范

必需：CI/Build Status + License。推荐：Version + Coverage。总数 ≤ 8 个，否则信噪比下降。

详细徽章格式和选择指南见 `references/badge-and-visuals.md`。

---

## 审计评分体系（22 项，100 分）

6 类别加权评分。详细 22 项检查清单见 `references/quality-checklist.md`。

| 类别 | 权重 | 核心判定 |
|------|------|----------|
| **Hook** | 25% | 项目名清晰？一行描述 < 120 字符？有 Hero Visual？ |
| **Onboarding** | 25% | Quick Start ≤ 3 步？安装命令可复制？Usage 有代码块？ |
| **Content** | 20% | Features 用列表不用散文？配置有文档？信息不过时？ |
| **Trust** | 15% | License 在最后？Contributing 存在？CI badge 绿色？ |
| **Structure** | 10% | 认知漏斗顺序？超 100 行有 TOC？无信息重复？ |
| **Polish** | 5% | 无死链？Markdown 格式正确？移动端可读？ |

等级：**S**(90-100) **A**(80-89) **B**(70-79) **C**(60-69) **D**(<60)

---

## 反模式速查

最常见 5 个（完整 15 个见 `references/anti-patterns.md`）：

| # | 反模式 | 修复 |
|---|--------|------|
| 7 | **模糊描述**「A utility for things」 | 说清楚解决什么问题、给谁用 |
| 8 | **省略安装** | 写完整命令，包括前置依赖 |
| 9 | **只说不做**（无代码示例） | 每个功能至少一个代码块 |
| 3 | **垃圾场**（全塞一个文件） | 拆分到 docs/、CONTRIBUTING.md |
| 10 | **时光胶囊**（README 过时） | 改代码时同步改 README |

---

## 执行流程

### Create 模式

扫描项目 → package.json / Cargo.toml / pyproject.toml / go.mod / Makefile
检测项目类型 → CLI / 库 / Web 应用 / 框架 / 插件 / Monorepo
提取信息 → 名称、描述、依赖、入口点、脚本/命令
扫描源码 → 核心导出、公共 API、主要功能
选择模板 → 按项目类型选 Golden Structure 变体
生成 README → 填充内容，生成代码示例
自审 → 跑 22 项检查，确保 ≥ 80 分
写入文件 → README.md（如有需要同时生成 README_CN.md）

text


### Audit 模式

读取 README.md
逐项检查 22 个评分点
计算总分 + 等级
输出诊断报告：
- 总分和等级
- 每个类别的得分
- Top 3 改进建议（按影响力排序）
- 反模式检测结果

text


### Rewrite 模式

读取现有 README.md
Audit（内部）→ 获取当前分数和问题列表
扫描项目获取最新信息
重写 → 保留好的部分，修复问题，补充缺失
自审 → 确保新版 ≥ 旧版分数 + 10 分（或 ≥ 80）
展示 diff → 让用户确认再写入

text


---

## 视觉资产

按项目类型自动选择：CLI → 终端 GIF (vhs/asciinema)，库 → 代码截图，框架 → Mermaid 架构图，Web 应用 → 浏览器截图。

具体格式模板见 `references/badge-and-visuals.md`。

---

## 输出格式

### Create / Rewrite 输出

直接写入 `README.md`。如果要求双语，同时生成 `README_CN.md`（或 `README_EN.md`）。

### Audit 输出

```markdown
## README Audit Report

**Score: 73/100 (B)**

| Category | Score | Max | Issues |
|----------|-------|-----|--------|
| Hook | 18 | 25 | 缺少 Hero Visual |
| Onboarding | 20 | 25 | Quick Start 超过 5 步 |
| Content | 15 | 20 | 配置项未文档化 |
| Trust | 12 | 15 | 无 Contributing 指南 |
| Structure | 5 | 10 | 缺少 TOC |
| Polish | 3 | 5 | 2 个死链 |

### Top 3 Improvements
1. 添加 GIF demo（+7 分）
2. 简化 Quick Start 到 3 步（+5 分）
3. 添加 CONTRIBUTING.md 链接（+3 分）

### Anti-patterns Detected
- #8 省略安装：缺少前置依赖说明
- #9 只说不做：Features 节没有代码示例

输出制品

请求类型	主产物	辅助产物
create	`README.md`	`README_CN.md`（如需双语）
audit	审计报告（stdout）	无文件变更
rewrite	`README.md`（更新）	diff 预览

Related Skills

Skill	关系
deslop	README 写完后可用 deslop 去 AI 味
doc-gen	生成 API 文档、架构文档（README 之外的文档）
slopbuster	更强的去 AI 味工具，适合对外发布的 README
improvement-learner	评估此 skill 本身的质量

References

详细参考资料见 references/ 目录：

references/quality-checklist.md — 完整 22 项检查清单与评分细则
references/anti-patterns.md — 15 个反模式完整版 + 检测方法
references/badge-and-visuals.md — 徽章格式模板、视觉资产生成指南
references/community-standards.md — 社区标准汇总（awesome-readme, Standard README, Art of README）
references/real-world-patterns.md — 从 OMC/ECC 等项目提取的实战模式

README Craft

Install

README Craft

模式

When to Use

When NOT to Use

Quick Start

Install

README Audit Report

Anti-patterns: #7 模糊描述, #3 垃圾场, #14 README当API文档

输出制品

Related Skills

References

Related skills