readme-beautifier

---
name: readme-beautifier
description: README 美化器。接收结构混乱、格式不统一的 README（或同类 markdown 项目文档如 CONTRIBUTING.md、docs/index.md、项目说明.md），输出结构清晰、标题层级正确、列表/代码块/表格格式一致、视觉专业的完整版本，并附一段改动摘要——内容不增不减，只改结构和格式。当用户请求美化、整理、排版、格式化、修复 README，或只是把一份杂乱的 README 丢给你说"太乱了""看下""帮我弄一下"时使用，即使没有明确说"美化"二字。触发词：美化 README、README 美化、整理 README、README 排版、README 格式化、README 太乱了、看下我这个 README、beautify README、fix/format/clean up/tidy/polish/reformat README、reorganize readme、my readme looks messy/ugly、make my README look professional。
---

# README 美化器

接收一份结构混乱或格式不统一的 README，输出结构清晰、格式一致、视觉专业的版本。

## 核心原则

- **内容不增不减**：不编造信息，不删除有效内容，只做结构和格式层面的改善
- **忠于原意**：保留作者的表达意图和语气，不做风格改写
- **最小改动**：能小修的不大改，能调格式的不重写
- **尊重原文，不强行套用**：原文已有的合理选择（章节顺序、是否加徽章/目录/中英文空格）一律保留，缺什么也不主动补——下面的检查清单据此判断，不再逐项重复这条原则

## 美化流程

```
1. 读取 README → 理解项目是什么、面向谁
2. 诊断问题 → 逐项检查下面的检查清单
3. 制定方案 → 列出要改什么、为什么改
4. 执行美化
5. 给出摘要
```

第 4、5 步按下面「输出格式」交付。

## 检查清单

按优先级从高到低排列。每项只在确实存在问题时才修复。

### 1. 标题层级

- h1 只出现一次，用于项目名
- 层级连续递增，不跳级（h1 → h3 是错的）
- 同级标题的粒度对齐（不要一个 h2 是"安装"，另一个 h2 是"如何在 Docker 里用 volume 挂载配置文件"）

### 2. 一句话描述

- 项目名下方紧跟一句话说清楚这个项目是什么、做什么
- 用 `>` 引用块或普通段落均可，但要有
- 如果原文已有但藏在中间，提到开头

### 3. 段落结构

- 每个章节有明确的职责，不混杂多个主题
- 常见的合理顺序：是什么 → 快速开始 → 用法 → 配置 → 目录结构 → 贡献 → 许可证
- 空章节（只有标题没有内容）删掉或补一句说明

### 4. 列表格式

- 同一个列表内的条目格式统一（全用 `-` 或全用 `*`，不混用）
- 嵌套缩进一致（2 空格或 4 空格，不混用）
- 有序列表用 `1.` 自动编号而非手动编号（避免插入条目后序号错乱）
- 列表前后有空行

### 5. 代码块

- 所有代码块标注语言（```bash / ```yaml / ```text 等）
- 行内代码用反引号包裹：命令、文件名、变量名、包名
- 命令示例中去掉不必要的 `$` 前缀（除非需要区分输入和输出）
- 多行命令用代码块而非行内代码

### 6. 表格

- 列对齐（不要求像素级对齐，但至少视觉上整齐）
- 表头有意义
- 如果表格只有两列且内容简短，考虑是否列表更合适
- 如果列表有三个以上平行维度的信息，考虑是否表格更合适

### 7. 链接与引用

- 链接文字有意义（不要 "点击这里"、"链接"）
- 检查明显的死链格式（`[text]()` 空链接、`[text](TODO)` 占位符）
- 相对路径与绝对路径的使用是否合理

### 8. 空白与分隔

- 标题前空一行
- 段落之间空一行
- 不要连续两个以上空行
- 中英文之间加空格（原文大部分已加则统一补齐，大部分没加则跟随原文）
- 列表和段落之间空一行
- 文件以单个换行符结尾（无多余空行，也不缺换行）

### 9. 徽章（Badges）

- 原文有徽章才整理：统一放在项目名下方、一句话描述上方
- 徽章之间用空格分隔，不换行

### 10. 目录（TOC）

- 章节超过 6 个时建议添加目录，6 个以内不加
- 目录用链接列表，指向对应标题的锚点
- 如果原文已有目录但锚点失效，修复而非删除

## 不做的事

- **不加装饰性元素**：不加 emoji、分隔线、花哨的 ASCII art，除非原文已有
- **不改技术内容**：不改命令、不改配置项、不改代码示例的逻辑
- **不翻译**：不把中文翻成英文，也不反过来
- **不补内容**：如果缺少"贡献指南"章节，不自动补一个——只在摘要里提一句"可以考虑补充"
- **不改文件名**：输出的还是 README.md，不改成别的

## 换用别的技能

本技能只管格式和结构，不管内容对不对。用户说"检查我的 README"时要区分意图：

- 想确认 README 写的内容跟代码/配置/接口是否一致、有没有过时 → 用 **hai-audit-docs-against-code**
- 想做文档内部一致性 / 陈旧内容审查（不跟代码对比）→ 用 **hai-audit-docs-internally**
- 想美化排版、统一格式、理顺结构 → 就是本技能

## 输出格式

常规路径：直接输出美化后的完整 README 内容，然后附一段简短摘要。

```markdown
<完整的美化后 README.md 内容>

---

**美化摘要**

改动了以下几点：
- ...

建议后续补充（不在本次改动范围内）：
- ...
```

README 已经规范、无需改动时的输出格式（检查摘要），见 [references/output-template.md](references/output-template.md) 末尾。两种完整交付模板都在该文件，定稿前对照一遍。

## 边界情况

- **README 非常短（< 10 行）**：只做格式修复，不人为撑篇幅
- **README 非常长（> 300 行）**：优先修复结构问题，格式问题只修最刺眼的
- **多语言 README**：只美化当前文件，不动其他语言版本
- **README 本身就很好**：不强行改，按 references/output-template.md 末尾的「检查摘要」格式回复