用途
readme-polish 用于把一份现有的 GitHub README（或空白起点）重写为符合 2025-2026 年主流开源项目视觉与版式习惯的版本。它的定位是“形状优先”：不发明内容，内容来自项目本身，技能只决定这些内容如何被呈现。核心目标有两个——浏览者应在 10 秒内明白项目做什么、面向谁、如何安装；有动力的读者则通过折叠块、表格和后续章节获取更多细节。
适用与不适用场景
适用：README 是一整面文字墙、缺少视觉锚点、一眼看不出项目用途；开源版本即将发布但 README 未做过可发现性编辑；参考材料与快速开始混在一起导致安装路径被埋没；需要通过徽章、主视觉图或章节重组来提升采用率；作者希望 README 同时传达“这个项目靠谱”和“这是用法”而不互相抢注意力。
不适用：README 已符合现代模式且内容良好时不应为风格而反复改动；内部或私有且从不发布的项目没有需要优化的受众；项目需要站点级文档（教程、API 参考、示例集）时应使用 Sphinx / MkDocs / Docusaurus，本技能只覆盖仓库根目录的 README。
主要能力：三阶段流程
阶段一：审计现有 README
编辑前先按现代 README 检查清单逐项标记“已具备 / 缺失 / 损坏”，判断哪些模式缺失、哪些被误用、哪些内容应移动、折叠或删除。关键审计问题包括：首屏（首屏范围内）是否可见项目名、一句话标语、徽章和安装命令，若否，说明有其他内容挤占了它们；维护者介绍是否以 100 字以上的长文挡在第一屏，应移入 > [!NOTE] 提示块或脚注；“为什么使用”部分中的条目是叙事型（因果、前后对比）还是功能型，每个章节应选定一种表达模式；读者能否在 5 秒内找到一条可用的安装命令；局限、相关项目、仓库结构、维护策略等参考材料是否被放在首屏；首屏是否至少有一个视觉锚点（徽章、主视觉图或示意图）；示例块是否使用多种视觉形式，而非连续堆叠三段等宽代码块；Mermaid 图是否用 %%{init: ...}%% 匹配品牌配色；所有 H2、H3 是否统一使用 Title Case；若版本发布包含尚未接线的底层能力，README 是否明确划出“今天可用 / 排队中”的边界；点分导航链接是否指向真实存在的章节锚点。
阶段二：套用现代模式
首屏部分：用 <div align="center"> 居中标题、一句话标语、徽章行、点分导航和电梯陈述；使用 Shield.io 徽章展示包版本（PyPI、npm）、许可证、CI 状态、GitHub stars，控制在 4-5 个以内；徽章下方放点分导航（如 [Install](#install) · [Workflow](#workflow) · [Features](#features)）；主视觉图可用 HTML 稿经无头 Chrome 渲染为 PNG，或用 <picture> 标签提供明暗两版标志；维护者可信度信息放入 > [!NOTE] 提示块，2-3 句，含可验证信号。
正文部分：用 GitHub 提示块 > [!NOTE]、> [!TIP]、> [!WARNING]、> [!CAUTION]、> [!IMPORTANT] 做强调，每个大章节至多一个；功能类条目用“1 个 emoji + 加粗功能名 + 一句话要点”的列表，5-8 条为宜；叙事类内容（因果、前后对比）用加粗引导句段落；在“How It Works”与“Install”之间放 3-5 个“What This Looks Like”示例，每个使用不同视觉形式（截图、文件树、主题化 Mermaid、HTML 双栏前后对比、终端模拟）；需要承载引用块、斜体或 <mark> 的丰富前后对比时使用 HTML 双栏表格，每份 README 一个即可；本质上呈表格形态的参考材料优先用表格而非密集列表；架构图、流程图和时序图使用主题化 Mermaid，且不用 Mermaid 充当主视觉图；平台变体、局限、相关项目、仓库结构、FAQ 等参考型内容放入 <details> 折叠块；长 README 底部加返回顶部锚点。
结构上，首屏（约前 40 行）依次为居中标题、徽章、导航、主视觉图、维护者提示块、标语、电梯陈述；中部为快速开始与安装、功能列表、可选的“为什么 / 理念”叙事；下方为日常用法、贡献说明、局限、相关项目、许可证；平台安装变体、仓库结构、观点与理由、局限、相关项目、维护策略折叠进 <details>。
阶段三：验证
必须在 GitHub 上（而非本地 IDE 预览）验证渲染效果：推送分支后查看 GitHub 页面，因为 > [!NOTE] 提示块、Mermaid 图、<picture> 明暗媒体查询、非 ASCII 标题的自动锚点、单元格内含 Markdown 引用块的 HTML 表格在多数本地预览中不渲染；逐个点击点分导航链接（重写后最常见的缺陷是锚点失效）；在不同视口宽度下检查表格溢出与主视觉图响应式；确认徽章为实时状态而非破图；若项目有多处入口（README、文档站首页、中文版 README），做跨端漂移检查，确保标语、How It Works 结构等一致；对自定义颜色元素检查明暗两套主题下的 WCAG AA 对比度（正文 ≥ 4.5:1）；若 README 引用渲染产物，确认源文件与渲染脚本一并提交以保证可复现；提交前运行 git diff --cached --check 检查行尾空白。
与其他技能的配合
当 README 需要定制主视觉图时，可配合 ci-mockup-figure 完成 HTML 到 PNG 的截图流程；重写完成后可用 implement-review 跑一轮 Codex 评审（关注首读流程、锚点有效性、内容准确性、版本边界诚实度等），大改通常需 2-4 轮；文案规则由 agent-style 规则包约束（共 21 条，其中 RULE-G 管 H2/H3 的 Title Case，RULE-B 禁随意破折号，RULE-E 禁段落末尾总结句，RULE-F 要求术语一致）。
输出与限制
产出为一份重写后的 README.md（以及可选的 docs/ 下主视觉素材）：标语与安装路径可在 10 秒内读懂；含徽章、点分导航、主视觉图、至少一个提示块和至少一个折叠块；除过时或重复内容外，原有内容均被保留（移动或折叠而非删除）；在 GitHub 上渲染正确。
明确限制：只覆盖仓库根目录的 README，不替代站点级文档；不生成新的事实性内容；不提供具体收费、价格或平台信息（资料未涉及）。