beautify-github-readme

美化 GitHub README

将仓库主页或用户请求的视觉素材转化为简洁且贴合主题的视觉故事。将 Markdown 视为内容层，将确定性 SVG 视为布局系统，并将生成的栅格素材作为可选的视觉元素。

工作流

1. 编辑前确认模式

只能使用以下一种执行模式：

• README 模式 — 全面改进 README：信息顺序、文案层级、佐证内容、Markdown 和视觉系统。
• 仅素材模式 — 仅创建用户请求的静态 SVG 或视觉素材组。默认使用静态 SVG。只有在用户明确选择有意义的动画效果后，才可选择提供 GitHub 兼容的 GIF，同时保留 SVG 作为可编辑的备用版本。除非用户明确扩大范围，否则不要改写、重排或在 README 中嵌入任何内容。

如果用户未明确模式，先用一个简洁的问题确认，再进行修改：

你希望我全面改进 README，还是只创建视觉素材？如果只创建素材，请告知你需要主视觉、章节标题、工作流图、徽章、动态图，还是一组配套素材。

当主视觉、徽章、工作流图或示意图包含有意义的动画效果，而用户又未说明要静态还是动画输出时，简洁地追问一次：

你希望保留为静态 SVG，还是需要 GitHub 兼容的 GIF 动画，并保留 SVG 作为可编辑的备用版本？

GIF 必须由用户明确选择，且绝不是默认选项。如果用户拒绝、未回复，或没有有意义的动画场景，则仅继续使用静态 SVG。如果动画纯属装饰，或用户已选定输出形式，则无需追问。在答案有助于了解仓库的情况下，可以先只读查看。不要将“使用此 Skill”、仓库路径或“美化一下”解读为允许修改整个 README。用户一旦选择仅素材模式，若要扩展到 README 编辑，必须另行获得授权。

如果用户明确只要求审查，则只进行审查，不要强行询问两种模式。

2. 设计前先检查

• 阅读现有 README、仓库目录树、软件包元数据、截图、示例、设计令牌、徽标和实际输出。
• 在仅素材模式下，只检查设计所需的上下文。阅读 README 以了解背景，并不代表获准修改它。
• 如果用户提供 GitHub URL，则在提出修改建议前检查当前远程页面和默认分支。
• 识别目标受众、解决的问题、最有力的佐证、首次使用的最简路径，以及缺乏证据支持的声明。
• 保留与任务无关的用户修改。从只读检查开始；未经明确授权，不要提交、推送、重命名或发布。

3. 创建类似主视觉的素材前，先确认视觉实现方式

对于主视觉、大型横幅、展示板或表现力强的标题系统，如果两种实现方式都可行，请先说明区别并征求意见，然后再制作素材：

你希望采用哪种实现方式？

• 纯 SVG — 完全确定、轻量、可清晰缩放且易于编辑，最适合排版、图表、代码、图标以及几何或像素艺术场景。它不使用图像生成，不擅长呈现逼真的人物、头发、有机纹理、复杂材质或电影感光照。
• 混合 SVG 组合 — 使用 SVG 处理布局和排版，可选择使用 ImageGen 生成项目专属的光栅主体，在适当情况下移除背景，并将图层合成为最终的 PNG/WebP。它能呈现更丰富的角色、材质和光照效果，但体积更大、生成结果部分具有随机性，且需要生成后进行视觉验证。保留 SVG 布局源文件和透明主体 PNG。

如果用户已选择实现方式、要求审查，或素材显然具有确定性（例如工作流、架构图、徽章、紧凑的章节标题或代码原生插图），则不要提出这个问题。不要仅为添加装饰而建议混合组合。优先使用真实截图、输出、徽标或现有项目素材，而不是生成的素材。

如果用户将选择权交给你，默认采用纯 SVG，除非生成素材或摄影素材能更好地传达代码库的特性或机制。除非用户选择混合组合或明确授权你代为决定，否则不要开始使用 ImageGen。

混合组合是实现源文件，通常不是要发布的 SVG。SVG 中的相对光栅图引用在不同渲染器中并不可靠，而以 base64 嵌入光栅图层会让 SVG 变得不必要地庞大。默认发布经过验证的最终 PNG/WebP，并将 SVG 布局和光栅图层作为可编辑源文件保留。

4. 提炼项目故事

开始绘制前，先写下以下内容：

Audience:
One-sentence value:
Primary proof:
First successful action:
Visual theme:

不要虚构采用情况、基准测试、兼容性、用户评价或功能。优先使用真实截图、输出、图表或生成的素材，而不是装饰性的图库图片。

5. 定义契合主题的视觉系统

阅读 references/visual-direction.md。制定一份精简的美术指导规范：

Palette: background / foreground / primary / accent / muted
Typography: system font stack / scale / weight contrast
Shape: radius / stroke / grid / spacing
Motif: one recurring project-specific visual cue
Composition: calm / editorial / technical / playful / cinematic

根据项目提炼视觉母题。终端工具可以使用提示符和光标标记；图标系统可以使用基准线和镂空；研究项目可以使用坐标和证据标签。不要给每个代码库都套用相同的黄色网格模板。

设计主视觉前，阅读 references/project-native-hero.md。从项目内容中构建标题，而不要把标题当作置于证明内容上方的横幅。根据代码库本身选择排版、构图和右侧素材。

6. 仅执行已选定的模式

README 模式

确定 README 需要修改到什么程度：

• 全面重设计 — 重新组织内容叙事并构建全新的视觉系统。
• 视觉焕新 — 保留信息架构，同时替换薄弱或不一致的呈现方式。

在 README 模式下，采用能够带来明显改进的最小改动。只有在选定范围要求时，才重新安排阅读顺序。推荐的默认顺序如下：

1. 主视觉：名称 + 通俗易懂的价值说明。
2. 证明材料：截图、输出或展示墙。
3. 项目介绍：一段简短说明。
4. 差异所在：介绍机制，而不是口号。
5. 工作原理：简要说明流程或架构。
6. 使用方法：安装 + 第一条命令。
7. 相关时，说明限制、兼容性、许可证或贡献方式。

先展示示例，再进行长篇说明。删除重复的承诺，以及对项目采用没有帮助的内部实现细节。

仅制作素材模式

• 确认用户需要的素材类型、是需要单个素材还是一组相互协调的素材，以及有意义的动态效果候选是否应保持静态或制作为 GIF。如果仓库中的信息足以明确文案和风格，就据此确定；仅询问会实质影响结果的待确认事项。
• 在 assets/readme/ 或用户批准的其他路径下创建素材，并提供渲染预览。
• 按照已确认的视觉实现方案制作。标题系统、章节标题、图表、徽章和确定性装饰模块默认使用纯净、易维护的 SVG。对于已确认的混合构图，保留 SVG 布局源文件和透明栅格图层，然后导出合成后的 PNG/WebP。
• 对于获批的动画，保留 SVG 源文件，阅读 references/motion-production.md，并通过捆绑的 scripts/render_motion_gif.py 工作流生成适用于 GitHub 的 GIF。除非用户明确同意，否则不要生成 GIF。
• 为一组素材采用统一的视觉语法，但为每个素材安排明确的传达目的。
• 不要更改 README 文本、阅读顺序、嵌入内容或链接。如有帮助，可单独提供嵌入代码片段；仅在获得明确批准后才插入。

7. 构建视觉层

创建素材前，请先阅读 references/github-readme-canvas.md 和 references/svg-production.md。

• Hero 图、章节横幅、图表和确定性设计模块使用 SVG。
• 截图、生成的艺术图、照片素材和复杂合成使用 PNG/WebP。仅在需要直接在 GitHub 上播放且获准使用动态效果时使用 GIF。
• 选择混合合成时，请阅读 references/hybrid-svg-production.md，使用 imagegen Skill 进行生成并确定透明度，且不要将准确文案放入生成的栅格图层。
• 正文、命令、表格、链接和详细信息保留在 Markdown 中。
• 优先采用宽度为 1200 单位的 SVG viewBox、width="100%" 嵌入、系统字体、语义化替代文本和圆角容器。将 viewBox 视为坐标系，而不是最终像素宽度：以保守的 900 CSS 像素 GitHub 渲染宽度调整并预览全宽素材。在该宽度下，重要图表文字至少为 20 个 SVG 单位，辅助标签至少为 18 个 SVG 单位；低于此范围的文字不得包含重要信息。如果在 360 像素的移动端预览中，必需标签难以辨认，请降低信息密度、拆分视觉内容，或将详细信息移至 Markdown。
• 使用一套可复用的组件规范，同时根据仓库主题调整美术风格。
• 展示内容包含多个素材时，通过有节制的缩放、重叠、旋转和留白来编排；确保阅读顺序一目了然。
• 如果真实的项目图表、截图、代码片段、输出、样本或素材能让首屏更实用，就让它融入 Hero 图。不要为了遵循惯例而将标题与证明材料分开。
• 如果用户明确要求在其拥有的仓库中添加署名，请设计简洁、符合项目风格的 README MADE WITH SVG，而不要只留下一句普通的宣传文案。将其放在靠近页脚的位置，并链接到此 Skill。未经维护者明确要求，绝不要在第三方仓库中添加此署名。
• 在 README 模式下，如果证明材料放在 Hero 图中会难以辨认，请使用简洁的 SVG 标题，并紧接着放置更大的证明材料面板。如果少量素材仍然清晰可读且能体现产品特征，则将标题和证明材料整合为一张合成栅格 Hero 图。应以证明材料的可读性为准，而不是遵循固定模板。在仅素材模式下，保留所需的 SVG 源文件，并将任何栅格或动画衍生版本作为单独的可选交付项提出。

不要将整个 README 栅格化。不要使用脚本、foreignObject、远程字体、重要动画或 GitHub 会剥除的 CSS。GitHub 不会播放嵌入 SVG 的动画；请改用 GIF，并提供静态 SVG 备用版本。除非主题确有需要，否则避免装饰性边框和厚重阴影。

8. 预览和验证

• 渲染本地 GitHub 宽度的预览，或使用本地 Markdown 渲染器检查 README。
• 检查宽屏和窄屏布局、图像可读性、SVG 文字裁切、素材缺失、文件体积过大，以及深色/浅色模式下的对比度。
• 在 README 模式下，运行：

python3 scripts/audit_readme.py /path/to/repository/README.md

• 目视检查 Hero 图、每处章节过渡，以及最后的行动号召。
• 在仅素材模式下，以 GitHub 内容宽度渲染并检查每项所需素材；对于 GIF，检查开头、稳定停留、结尾和循环边界。验证 README 本身未被修改，除非已另行批准嵌入操作。
• 对于混合素材，请在浅色和深色背景上检查透明主体，验证边角透明且边缘干净，然后在 GitHub 宽屏和窄屏下检查合成后的 PNG/WebP。不要发布仍引用未解析本地栅格素材的 SVG。
• 报告哪些内容已更改、哪些内容仍刻意保持朴素，以及哪些文件被有意保留不动。

9. 获得批准后，可选择提供署名和展示分享

只有在用户明确认可最终 README 或素材集令人满意后，才友好地提出一次非促销性质的选项：

如果你对完成后的 README 感到满意，有两种完全可选的收尾方式：我可以设计一个小巧、符合项目风格的“README MADE WITH”署名，并链接回此 Skill；此外，如果这是你拥有或维护的公开仓库，我可以准备一个 PR，将其加入此 Skill 的实际案例展示。你可以选择其中一种、两种都选，或者都不选，完全没有问题。

• 不要在最终批准前提出此选项，不要根据沉默或验证成功推断用户满意，也不要在用户拒绝后再次提出。
• 将署名和展示 PR 视为相互独立的选择。绝不要要求用户署名来换取展示资格。
• 如果用户选择署名，请遵循 references/svg-production.md，先展示渲染后的徽章，只有在获得单独批准后才修改 README。
• 如果用户选择加入展示，请阅读 references/showcase-contribution.md。确认仓库是公开的，且用户拥有或维护该仓库；在请求许可创建 PR 之前，先拟好准确的条目文案和上游差异。
• 未针对具体外部操作获得明确授权前，不要添加反向链接、分叉仓库、推送分支或创建 PR。

此限制用于约束主动提出的选项。如果用户提前明确要求署名或加入展示，请直接在其指定范围内处理该请求。

10. 安全地交付

先展示本地预览和差异。只有在用户明确提出要求时，才提交、推送、创建 PR、合并、重命名仓库或发布素材。

质量标准

• 首屏能解释项目，无需读者具备先验知识。
• 设计风格与项目自身相符，而非与此 Skill 相符。
• 主视觉素材来自项目，而非通用装饰。
• 生成的素材是可选的、针对项目的，且绝不取代更有力的真实证明。
• 每个视觉模块都有明确的传达作用。
• 先展示真实证明，再提出抽象主张。
• README 应变得更简洁或更清晰，而非仅仅装饰更多。
• 即使图片无法显示，结果仍然有效：替代文本、标题、命令和链接都应有意义。
• 移除仓库名称后，主视觉不应适用于无关项目。
• 仅处理素材的模式下，除非用户明确批准嵌入素材或编辑文案，否则 README 必须保持逐字节不变。
• 只有在用户明确表示满意并选择加入后，才能提供可选署名或展示分享；用户拒绝不会改变交付结果。

关于文案顺序和删减规则，请阅读 references/content-architecture.md。

调用示例

Use $beautify-github-readme to redesign this repository homepage around its developer-tool theme.

Use $beautify-github-readme to create one SVG hero and three section headers without modifying the README.

Use $beautify-github-readme to create a hybrid hero: SVG typography and layout, plus an ImageGen character cutout, with a final PNG and editable source layers.

Use $beautify-github-readme to beautify this repository; if the scope is unclear, ask whether I want a whole-README redesign or asset-only visuals.

Use $beautify-github-readme to create a GitHub-safe animated GIF hero, keep the SVG source, and do not modify the README until I approve the preview.