1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | beautify-github-readme |
| 作者/维护者 | oil-oil（Zhihuang Lin） |
| 来源链接 | https://github.com/oil-oil/beautify-github-readme |
| 许可证 | MIT |
| GitHub Stars | 902（GitHub API） |
| Forks | 50（GitHub API） |
| 最新版本 | 无正式 Release/Tag，以持续提交方式更新 |
| 安装方式 | npx skills add oil-oil/beautify-github-readme，或让 Agent 直接读取仓库地址安装 |
2. 功能介绍与亮点
这是一个把 GitHub 仓库主页拆成两层来处理的技能：视觉层交给 SVG/GIF，文字内容留在 Markdown。核心能力：
- 两种明确模式：整页重排（分析信息结构、重排阅读顺序、替换视觉系统）与仅生成素材（只做 hero 图、分节标题、图表、徽章，不碰 README 正文），两种模式都会先出本地预览、经用户确认后才会提交
- 先理解项目再设计：读取仓库真实的截图、目录结构、示例输出后再决定视觉方向和配色/字体/图形语言，明确禁止编造不存在的采用案例或性能数据
- 本地渲染、无云端依赖：内置
audit_readme.py检查 README 结构，render_motion_gif.py用本地 SVG 渲染器和 ffmpeg 把已批准的静态帧合成 GitHub 安全的 GIF - 真实案例驱动：README 中列出的 6 个使用案例均为其他开发者的公开仓库，可在 GitHub 上直接核实是真实改造效果，而非样例图
3. 适用场景
所属分类：前端与设计。面向想让开源库、组件库、个人项目的主页第一屏更专业的开发者——尤其是独立维护者、需要在黑客松或作品集展示中快速做出一个有说服力的项目主页的场景。
4. 跨 Agent 兼容性
- Claude Code：原生支持——SKILL.md 采用标准 Agent Skill 格式（YAML frontmatter + name/description）
- Codex：原生支持——仓库内置
agents/openai.yaml，专为 OpenAI 风格 agent 提供展示名与默认提示词 - OpenClaw：未验证——已获取材料中未见相关适配说明
- Hermes Agent：未验证——已获取材料中未见相关适配说明
5. 推荐理由
用项目真实素材定制视觉语言，每一步修改都需你先看预览再批准。
它不是套模板的美化工具：会先读懂项目本身在解决什么问题、证据是什么，再决定用什么视觉语言表达；“只做素材”和“重排整个 README”两种模式边界清晰，避免自动提交、过度承诺这类常见事故。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | GitHub 902 Stars（认证 API 数据），且已有至少 4 位独立用户通过 Issue/PR 参与——真实排版缺陷反馈、功能提问、两次第三方案例投稿 |
| 可用性 | 9 | 一条命令即可安装；SKILL.md 与三份参考文档完整含示例；近期持续维护；核心功能无付费依赖，仅可选的动图渲染需要本地 ffmpeg/SVG 渲染器 |
| 安全性 | 8 | 本地代码执行范围明确（仅调用 SVG 渲染器与 ffmpeg 处理本地图像，参数均为列表形式无注入风险）；无联网外发；无需任何 API key；脚本与 SKILL.md 全文未见可疑指令；MIT 许可证明确；近期仍在活跃维护 |
7. 跟同类 Skills 相比的优势
| Skill | 定位 | 与 beautify-github-readme 的差异 |
|---|---|---|
| beautify-github-readme | 只处理 README 的视觉设计层，先理解项目再定制视觉语言，改动前逐项获批 | 本项 |
| readme-ai（eli64s，2937 Stars，MIT） | 独立 CLI 工具，输入仓库路径即用 LLM 自动生成整份 README 的文字内容 | 解决“从零写文字”，而非“美化已有内容的视觉呈现”；作为独立 CLI 需单独安装，直接产出成品，没有分步预览与逐项批准环节 |
| GitHub Profile Readme Generator | 面向 GitHub 个人主页（profile README）的网页版模板生成器 | 处理对象是个人主页而非仓库主页；是网页工具而非可被 Agent 直接调用的技能，产出为固定模板而非按项目定制的视觉语言 |
8. 用户评价
- luo-zhan（GitHub Issue #10）：反馈生成的 SVG 按 1200px 宽度设计，但 GitHub 实际渲染宽度约 900px，导致字体在真实页面中偏小——具体的排版缺陷报告，作者随后提交了修复
- MS-Teja（GitHub Issue #9）：询问能否直接生成图表 SVG 而非手绘图表，反映了真实用户在图表生成场景下的诉求
- moesix 与 ShadyBad：分别通过 PR 把自己维护的仓库提交进该技能的案例展示列表，是两次独立的第三方采用记录
9. 其他补充
提供中英双语 README（含 README.zh-CN.md）；开放案例投稿流程，允许用户主动提交自己用该技能改造过的仓库作为展示案例，目前已有 6 个此类案例。
10. 安装使用方式
- 命令行安装：
npx skills add oil-oil/beautify-github-readme - 或直接把仓库地址
https://github.com/oil-oil/beautify-github-readme发给 Agent，要求安装该 Skill - 安装后无需重启，在对话中说“使用 $beautify-github-readme 重新设计这个仓库的 README”或“只生成一张 SVG 首图，不要改动 README 正文”即可触发
- 如需生成动图效果，本地需安装 ffmpeg 与 SVG 渲染器（如 rsvg-convert）；仅使用静态 SVG 与 Markdown 重排功能时无此依赖
11. 注意事项
- 目前仅确认了 Claude Code 与 Codex 上的适配，OpenClaw 与 Hermes Agent 上的表现尚未验证
- 动图渲染依赖本地安装的 ffmpeg/SVG 渲染工具，未安装时该功能不可用，但静态 SVG 与 README 重排功能不受影响
- 仓库暂无正式版本号，更新以持续提交方式进行，升级前建议查看最新提交记录
- 设计上默认不会自动提交、推送或发布任何改动，每一步都需要用户在对话中明确同意——这是安全保障，但也意味着它不适合接入全自动、无人值守的 CI 流水线