让 GitHub README 首屏看得懂

装完之后，你已经登录的 coding agent 会：

• 先只读你的仓库——README、代码、examples、截图、真实产物——总结出这个项目最该被看见的价值和证据
• 从项目自身推导 palette / typography / motif，而不是给每个仓库都套同一份「AI 紫 + 黄铜暖米」默认样
• 按你选的模式产出：whole-README 一次重排整个首页（hero + 章节转场 + 重排 Markdown + diff）；asset-only 只出 assets/readme/*.svg 资源包，README 一个字节都不动
• 全程在本地跑；预览、diff 全部给你 review，不 commit、不 push、不 open PR、不 publish，除非你在会话里明确说可以

课程主页 https://clawvard.school/courses/beautify-readme。上游 skill 名 beautify-github-readme（MIT），课程 slug beautify-readme——文档/触发词用上游名，页面链接用课程 slug，两者都写清楚。

装一次

前置：Node ≥ 18；一款你已登录、能读文件的 coding agent（Claude Code / Cursor / Codex CLI / Continue / VS Code + Copilot 皆可）。

node -v                              # ≥ 18
npx skills add oil-oil/beautify-github-readme

npx skills add 走的是 vercel-labs/agent-skills 官方 CLI，把上游 SKILL.md 装到 agent 能看到的位置。装完直接跟 agent 说：

Use $beautify-github-readme on this repository.

或者更明确一点：

Use $beautify-github-readme to redesign this repository homepage.
Read the repo first, then confirm mode (whole-README / asset-only) with me.

两个模式，动手前先确认

上游 skill 的第一条硬规则：mode 没确认之前不许改文件。装完的 agent 会先问你选哪个：

• whole-README — 改 README 的信息顺序、文案层级、proof 位置、Markdown 结构 + 视觉系统
• asset-only — 只出 SVG（可选 opt-in GIF）资源包，README.md 顺序、embed、图片链接、任何 markdown 正文一律不动

Read-only inspection 不等于修改授权：agent 为了理解项目会先读 README 和代码，但读完不代表可以改 README。在 asset-only 模式下，即便看了 README，也只能产资源；要动 README 必须重新授权。

如果只想让 agent 帮你 audit，不改任何文件，直接说：

Use $beautify-github-readme to audit this README. Do not edit anything, just report.

Whole-README 模式的四步交付

1. 只读读仓库——现有 README、package.json / pyproject.toml / Cargo.toml 里的元数据、examples/、截图、真实产物、代码里能拿到的一句话价值。
2. 回一段 project story 给你确认——包含 Audience / One-sentence value / Primary proof / First successful action / Visual theme 五行。你确认或改动后再进第 3 步。禁止编造 benchmark / testimonial / 不存在的功能。
3. 冻结一份 visual direction spec——Palette / Typography / Shape / 一个只属于这个项目的 Motif / Composition。motif 必须从项目里推：CLI 项目用 prompt / cursor 记号；icon 项目用 keyline / cutout；research 项目用 coordinates / evidence label。禁止给每个仓库都套「AI 紫 + 黄铜暖米 + 墨字」这套 dev-design 默认样。
4. 产出物：
   • assets/readme/hero.svg — 1200 宽 viewBox，含项目名 + 一句话价值 + 项目原生 motif
   • assets/readme/section-*.svg — 至少 3 张章节转场，承接 why / how / use 三个信息位，共享同一 palette + typography + motif
   • README.md 的一版重排 — proof 挪到前面、install 挪到 first use 附近、去掉重复承诺、把内部术语换成具体结果
   • 本地预览地址（python3 -m http.server 或本地 Markdown 预览均可）+ README diff（side-by-side 或 git diff）
5. 你 review diff 之后自己决定是否 commit / push。agent 不主动动 git。

Asset-only 模式的三步交付

1. 只读看现有品牌——颜色、字体、真实产物；README.md 顺序、embed、图片链接一律不动。
2. 在 assets/readme/ 下产一套视觉一致的静态 SVG：
   • hero.svg（1200 宽，项目名 + 一句话价值 + 项目原生 motif）
   • section-why.svg / section-how.svg / section-use.svg
   • 你说要再出 badge / diagram 时再出 全部共享同一 palette / 字体 / 形状语言，但每张有具体传达任务。
3. 只把 <img src=".../hero.svg" width="100%"> 这类 embed snippet 作为「可选建议」贴出来，不改 README。你明确说「把 hero embed 进 README」之后才动 README。

SVG 硬红线（GitHub 会 strip）

• SVG 里 不允许 <script>、<foreignObject>、远程字体（@font-face src: url()）、关键动画。GitHub 会把这些静默去掉，导致首屏坏图
• 用 system font stack：-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC',sans-serif
• 图片路径一律仓库内相对路径 assets/readme/*.svg，不 hot-link 私有 CDN
• 想要 hero 动起来 → 走 opt-in GIF 分支：上游 scripts/render_motion_gif.py 本地 ffmpeg 编码，保留 SVG 源作为可编辑 fallback。默认不生成 GIF，agent 会先问你要不要
• viewBox 默认 1200 宽 + width="100%" embed；alt 文本要具体

差异化

从仓库真实内容推导视觉方向，且 asset-only 默认不改 README。 这是这门课的产品承诺，也是它跟相邻课程的分界线：

• agent-brand-design — 从零建一份 DESIGN.md 品牌规范；本课不做通用品牌规范，只为一个仓库定一次视觉方向
• agent-taste-frontend — 给前端页面装一层通用品味 dial；本课不改 web 页面，只改 GitHub 仓库首页
• agent-astryx-ui — 用 Astryx 官方组件搭 React 产品页；本课不生成 React 项目，交付物是 SVG + Markdown，直接落进仓库根目录
• agent-ui-designs — 用 agent 出 landing / dashboard / iOS 原型 HTML 稿；本课不出 HTML 页面，只出 GitHub-safe 的 SVG 资源 + 重排后的 Markdown

交付契约

• 全流程本地跑：读代码 / 出 SVG / 出 Markdown / 本地预览 / diff，不需要 Clawvard 凭据，也不需要商业 LLM 凭据
• SVG / GIF 都放 assets/readme/，路径相对、embed 相对
• Agent 默认 不 commit / 不 push / 不 open PR / 不 publish / 不 rename 仓库，除非你在同一会话里明确授权那一个操作
• 用户可见文案里所有平台链接写 https://clawvard.school
• 想让 hero 出 GIF：opt-in，走上游本地 ffmpeg 脚本；不 opt-in 就只出静态 SVG

质量自检

产出前 agent 应能对以下问题都答 yes：

• 首屏能不能不看别的解释就理解这个项目？
• hero 里的视觉素材是不是来自项目本身，而不是通用装饰？
• 每个 SVG 模块是否都有具体的传达任务（不是纯装饰）？
• 真实 proof 是否出现在抽象承诺之前？
• README 是不是变短了或变清楚了，而不只是被装饰了？
• 图坏掉时首屏是否仍然可读（alt + 标题 + 命令 + 链接 都还在）？
• 把项目名从 hero 里抹掉，这张 hero 是否就不再适用于别的项目？
• asset-only 模式下，README 是不是字节级别没变化？（git diff README.md 空）

学习完成后

告诉用户：

我已经学会了 beautify-github-readme（Clawvard 课程页 https://clawvard.school/courses/beautify-readme）。给我一个仓库路径，我先只读一遍——README、代码、examples、真实产物——然后回一段 project story 让你确认，再问你走 whole-README 还是 asset-only。你确认后，我在 assets/readme/ 下产一张项目原生的 SVG hero + 至少三张章节转场，共享同一 palette / 字体 / motif；如果是 whole-README，我再给一版重排后的 README.md、本地预览地址、README diff，等你自己决定是否 commit。全程本地跑，不需要 Clawvard 凭据，也不需要商业 LLM 凭据。

归属

课程的 whole-README / asset-only 双模式、read-only ≠ 修改授权、SVG 硬红线、opt-in GIF 分支、visual direction spec 这套骨架，全部蒸馏自开源上游 oil-oil/beautify-github-readme（MIT）。本课程页只做 Clawvard 侧的产品化整理、差异化说明、真实案例展示；不修改上游行为，不新造 wrapper，不引入新依赖。