| 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 内容，然后附一段简短摘要。
<完整的美化后 README.md 内容>
---
**美化摘要**
改动了以下几点：
- ...
建议后续补充（不在本次改动范围内）：
- ...
README 已经规范、无需改动时的输出格式（检查摘要），见 references/output-template.md 末尾。两种完整交付模板都在该文件，定稿前对照一遍。
边界情况
- README 非常短（< 10 行）：只做格式修复，不人为撑篇幅
- README 非常长（> 300 行）：优先修复结构问题，格式问题只修最刺眼的
- 多语言 README：只美化当前文件，不动其他语言版本
- README 本身就很好：不强行改，按 references/output-template.md 末尾的「检查摘要」格式回复
