Back to Details

beautify-github-readme

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Beautify GitHub README

美化GitHub README

Turn a repository homepage or a requested SVG asset into a concise, theme-specific visual story. Treat SVG as the visual layer and Markdown as the content layer.
将仓库主页或指定的SVG资产转化为简洁、贴合主题的视觉叙事。将SVG视为视觉层，Markdown视为内容层。

Workflow

工作流程

1. Confirm the mode before editing

1. 编辑前确认模式

Use exactly one execution mode:
  • README mode — improve the whole README: information order, copy hierarchy, proof, Markdown, and visual system.
  • Asset-only mode — create only the requested static SVG or visual asset set. Static SVG is the default. Only after the user explicitly opts into meaningful motion, optionally deliver a GitHub-safe GIF while keeping the SVG as the editable fallback. Do not rewrite, reorder, or embed anything in the README unless the user explicitly adds that scope.
If the mode is not explicit, ask one compact question before making changes:
Would you like me to improve the whole README or only create visual assets? If asset-only, tell me whether you need a hero, section headers, workflow, badge, motion graphic, or a coordinated set.
When a hero, badge, workflow, or diagram has meaningful motion and the user has not specified static or animated output, ask one compact follow-up:
Should this stay as a static SVG, or would you like a GitHub-safe GIF animation with the SVG kept as the editable fallback?
GIF is opt-in and never the default. If the user declines, does not answer, or has no meaningful motion case, continue with static SVG only. Do not ask when motion would be purely decorative or the user already chose the output. Read-only inspection is allowed before the answer when it helps understand the repository. Do not interpret “use this Skill,” a repository path, or “beautify it” as permission to modify the whole README. Once the user chooses asset-only mode, expanding into README edits requires new authorization.
If the user explicitly asks only for an audit, audit without editing and do not force the two-mode question.
仅使用以下一种执行模式：
  • README模式 — 优化整个README：信息顺序、文案层级、校对、Markdown格式及视觉系统。
  • 仅资产模式 — 仅创建指定的静态SVG或视觉资产集。默认输出静态SVG。仅当用户明确要求添加有意义的动态效果时，可额外提供GitHub兼容的GIF，同时保留SVG作为可编辑的备选方案。除非用户明确扩展范围，否则不得重写、调整顺序或在README中嵌入任何内容。
若模式不明确，在进行修改前需先问一个简洁的问题：
您希望我优化整个README，还是仅创建视觉资产？如果是仅资产模式，请告知您需要Hero、章节标题、流程图、徽章、动态图形，还是一套协调的资产组合。
当Hero、徽章、流程图或图表包含有意义的动态效果，且用户未指定静态或动画输出时，需跟进一个简洁的问题：
该资产应保持静态SVG格式，还是需要生成GitHub兼容的GIF动画并保留SVG作为可编辑备选方案？
GIF为可选选项，且绝非默认输出。若用户拒绝、未回复或无合适的动态应用场景，仅需继续提供静态SVG。当动态效果仅为装饰性或用户已指定输出格式时，无需询问。在等待回复前，可进行只读检查以帮助理解仓库内容，但不得将“使用此Skill”、仓库路径或“美化它”视为修改整个README的许可。一旦用户选择仅资产模式，扩展至README编辑需获得新的授权。
若用户明确仅要求审核，则仅进行审核不做编辑，无需强制询问双模式问题。

2. Inspect before designing

2. 设计前检查

  • Read the existing README, repository tree, package metadata, screenshots, examples, design tokens, logo, and real outputs.
  • In asset-only mode, inspect only the context needed to design the requested assets. Reading the README for context does not authorize changing it.
  • For a GitHub URL, inspect the current remote page and default branch before proposing changes.
  • Identify the audience, the problem solved, the clearest proof, the shortest path to first use, and any claims that lack evidence.
  • Preserve unrelated user changes. Start read-only; do not commit, push, rename, or publish without explicit authorization.
  • 阅读现有README、仓库目录、包元数据、截图、示例、设计标记、Logo及实际输出成果。
  • 在仅资产模式下，仅检查设计指定资产所需的上下文信息。阅读README获取上下文不代表获得修改权限。
  • 对于GitHub URL，在提议修改前需检查当前远程页面及默认分支。
  • 明确受众、解决的问题、最清晰的证明、首次使用的最简路径，以及任何缺乏证据的声明。
  • 保留用户无关的修改。初始阶段为只读模式；未经明确授权，不得提交、推送、重命名或发布内容。

3. Extract the project story

3. 提炼项目叙事

Write these before drawing:
text
Audience:
One-sentence value:
Primary proof:
First successful action:
Visual theme:
Do not invent adoption, benchmarks, compatibility, testimonials, or features. Prefer a real screenshot, output, diagram, or generated artifact over decorative stock imagery.
在开始设计前需先撰写以下内容：
text
受众:
一句话价值定位:
核心证明:
首次成功操作:
视觉主题:
不得虚构用户采用率、基准测试、兼容性、推荐语或功能。优先使用真实截图、输出成果、图表或生成的工件，而非装饰性库存素材。

4. Define a theme-specific visual system

4. 定义贴合主题的视觉系统

Read references/visual-direction.md. Freeze a compact art-direction spec:
text
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
Derive the motif from the project. A terminal tool may use prompts and cursor marks; an icon system may use keylines and cutouts; a research project may use coordinates and evidence labels. Never apply the same yellow-grid template to every repository.
Before designing the hero, read references/project-native-hero.md. Build the title from project content rather than treating it as a banner placed above the proof. Choose the typography, composition, and right-side material from the repository itself.
阅读 references/visual-direction.md。确定简洁的艺术指导规范：
text
配色方案: 背景色 / 前景色 / 主色 / 强调色 / 中性色
排版: 系统字体栈 / 字号比例 / 字重对比
形状: 圆角半径 / 描边 / 网格 / 间距
主题元素: 一个重复出现的项目专属视觉线索
构图风格: 沉稳 / 编辑感 / 技术风 / 活泼 / 电影感
主题元素需源自项目本身。终端工具可使用提示符和光标标记；图标系统可使用基准线和镂空设计；研究项目可使用坐标和证据标签。绝不能对所有仓库套用相同的黄色网格模板。
在设计Hero前，阅读 references/project-native-hero.md。基于项目内容构建标题，而非将其视为放置在证明内容上方的横幅。从仓库本身选择排版、构图及右侧素材。

5. Execute only the selected mode

5. 仅执行选定的模式

README mode

README模式

Decide how deeply the README needs to change:
  • Full redesign — restructure the story and build a new visual system.
  • Visual refresh — preserve the information architecture while replacing weak or inconsistent presentation.
Use the smallest change inside README mode that can produce a meaningful improvement. Rebuild the reading order only when the selected scope requires it. A strong default is:
  1. Hero: name + plain-language value.
  2. Proof: screenshots, outputs, or a showcase wall.
  3. What it is: one short explanation.
  4. Why it is different: mechanism, not slogans.
  5. How it works: a short process or architecture.
  6. How to use: install + first command.
  7. Limits, compatibility, license, or contribution details when relevant.
Put the example before the long explanation. Remove repeated promises and internal implementation detail that does not help adoption.
确定README所需的修改深度：
  • 全面重设计 — 重构叙事逻辑并搭建新的视觉系统。
  • 视觉焕新 — 保留信息架构，替换薄弱或不一致的呈现方式。
在README模式下，采用能产生显著改进的最小修改幅度。仅当选定范围需要时，才重构阅读顺序。一个可靠的默认结构为：
  1. Hero: 名称 + 直白语言表述的价值定位
  2. 证明: 截图、输出成果或展示墙
  3. 项目简介: 简短说明
  4. 差异化优势: 技术机制，而非口号
  5. 工作原理: 简短流程或架构说明
  6. 使用方法: 安装步骤 + 首个命令
  7. 限制条件、兼容性、许可证或贡献说明（相关时添加）
将示例放在长篇说明之前。移除重复的承诺及无助于用户采用的内部实现细节。

Asset-only mode

仅资产模式

  • Confirm the requested asset type, whether the user wants one asset or a coordinated set, and whether a meaningful motion candidate should stay static or become a GIF. Derive exact copy and style from the repository when they are unambiguous; ask only for missing decisions that would materially change the result.
  • Create the assets under 
    assets/readme/
    or another user-approved path and provide rendered previews.
  • Default to pure, maintainable SVG for title systems, section headers, diagrams, badges, and deterministic decorative modules.
  • For approved animation, keep the SVG source, read references/motion-production.md, and derive a GitHub-safe GIF with the bundled 
    scripts/render_motion_gif.py
    workflow. Do not generate the GIF unless the user opted in.
  • Keep one shared visual grammar across a set, but give every asset a specific communication job.
  • Do not change README text, reading order, embeds, or links. Offer an embed snippet separately when useful; only insert it after explicit approval.
  • 确认指定的资产类型、用户需要单个资产还是一套协调的组合，以及有意义的动态效果候选资产应保持静态还是转为GIF。当文案和样式明确时，直接从仓库提取；仅当缺失会对结果产生实质性影响的决策时才询问用户。
  • 在 
    assets/readme/
    或其他用户批准的路径下创建资产，并提供渲染预览。
  • 标题系统、章节标题、图表、徽章及确定性装饰模块默认使用可维护的纯SVG格式。
  • 对于已批准的动画，保留SVG源文件，阅读 references/motion-production.md，并通过捆绑的 
    scripts/render_motion_gif.py
    工作流生成GitHub兼容的GIF。仅当用户选择时才生成GIF。
  • 一套资产需遵循统一的视觉语法，但每个资产需承担特定的传达任务。
  • 不得修改README文本、阅读顺序、嵌入内容或链接。当有用时可单独提供嵌入代码片段；仅在获得明确批准后才可插入。

6. Build the visual layer

6. 构建视觉层

Read references/github-readme-canvas.md and references/svg-production.md before creating assets.
  • Use SVG for the hero, section banners, diagrams, and deterministic design modules.
  • Use PNG/WebP for screenshots, generated art, photo material, and complex compositing. Use GIF only for approved motion that must play directly on GitHub.
  • Keep body copy, commands, tables, links, and details in Markdown.
  • Prefer a 
    1200
    -unit-wide SVG 
    viewBox
    , 
    width="100%"
    embeds, system fonts, semantic alt text, and rounded containers. Treat the 
    viewBox
    as a coordinate system, not the final pixel width: size and preview full-width assets at a conservative 
    900
    CSS-pixel GitHub render. At that width, keep essential diagram text at least 
    20
    SVG units and supporting labels at least 
    18
    ; text below that range must be nonessential. If a 
    360
    -pixel mobile preview makes required labels unreadable, reduce density, split the visual, or move the detail into Markdown.
  • Use one reusable component grammar, but vary the art direction by repository theme.
  • When a showcase contains several artifacts, arrange them with controlled scale, overlap, rotation, and whitespace; keep reading order obvious.
  • Let the hero absorb a real project diagram, screenshot, code fragment, output, specimen, or artifact when it makes the first screen more useful. Do not separate the title and proof by habit.
  • When the user explicitly wants attribution in a repository they own, design a compact project-native 
    README MADE WITH
    SVG instead of leaving a plain promotional sentence. Keep it near the footer and link it to this Skill. Never add this credit to a third-party repository without the maintainer's explicit request.
  • In README mode, when proof would become unreadable inside the hero, use a concise SVG title followed immediately by a larger proof board. When a few artifacts remain legible and define the product, integrate title and proof into one composed raster hero. Let proof legibility decide, not a fixed template. In asset-only mode, keep the requested SVG source and propose any raster or animated derivative as a separate, optional deliverable.
Do not rasterize the whole README. Do not use scripts, 
foreignObject
, remote fonts, essential animation, or CSS that GitHub strips. GitHub does not play animation embedded inside SVG; use a GIF plus static SVG fallback instead. Avoid decorative borders and heavy shadows unless the theme genuinely calls for them.
在创建资产前，阅读 references/github-readme-canvas.md 和 references/svg-production.md。
  • Hero、章节横幅、图表及确定性设计模块使用SVG格式。
  • 截图、生成的艺术作品、照片素材及复杂合成使用PNG/WebP格式。仅当需要在GitHub上直接播放的已批准动画时才使用GIF。
  • 正文文案、命令、表格、链接及细节保留在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栅格化。不得使用GitHub会剥离的脚本、
foreignObject
、远程字体、必需动画或CSS。GitHub不播放SVG内嵌的动画；需使用GIF加静态SVG备选方案。除非主题确实需要，否则避免装饰性边框和厚重阴影。

7. Preview and verify

7. 预览与验证

  • Render a local GitHub-width preview or inspect the README on a local Markdown renderer.
  • Check wide and narrow layouts, image legibility, clipped SVG text, missing assets, excessive file size, and dark/light-mode contrast.
  • In README mode, run:
bash
python3 scripts/audit_readme.py /path/to/repository/README.md
  • Visually inspect the hero, every section transition, and the final call to action.
  • In asset-only mode, render and inspect every requested asset at GitHub content width; for GIFs, inspect entry, settled hold, exit, and loop boundary. Verify that the README itself is unchanged unless embedding was separately approved.
  • Report what changed, what remains intentionally plain, and which files were deliberately left untouched.
  • 渲染本地GitHub宽度的预览，或在本地Markdown渲染器中检查README。
  • 检查宽屏和窄屏布局、图像可读性、SVG文本截断、缺失资产、过大文件尺寸及深色/浅色模式对比度。
  • 在README模式下，运行：
bash
python3 scripts/audit_readme.py /path/to/repository/README.md
  • 视觉检查Hero、每个章节过渡及最终行动号召。
  • 在仅资产模式下，以GitHub内容宽度渲染并检查每个指定资产；对于GIF，检查进入帧、稳定停留帧、退出帧及循环边界。验证README本身未被修改，除非嵌入内容已单独获得批准。
  • 报告修改内容、故意保留的朴素部分，以及未改动的文件。

8. Offer optional attribution and showcase sharing after approval

8. 获得批准后提供可选署名及展示分享

Only after the user explicitly approves the final README or asset set as satisfactory, make one friendly, non-promotional offer:
If you're happy with the finished README, there are two completely optional ways to wrap up: I can design a small project-native “README MADE WITH” signature that links back to this Skill, and—if this is a public repository you own or maintain—I can prepare a PR to add it to the Skill's real-world showcase. Either, both, or neither is perfectly fine.
  • Do not make this offer before final approval, infer satisfaction from silence or successful validation, or repeat it after the user declines.
  • Treat the signature and showcase PR as independent choices. Never require attribution in exchange for showcase consideration.
  • If the user opts into the signature, follow references/svg-production.md, show the rendered badge first, and modify the README only after separate approval.
  • If the user opts into the showcase, read references/showcase-contribution.md. Verify that the repository is public and that the user owns or maintains it; draft the exact listing copy and upstream diff before requesting permission to open the PR.
  • Do not add a backlink, fork a repository, push a branch, or open a PR without explicit authorization for that specific external action.
This gate controls unsolicited offers. If the user explicitly requests a signature or showcase contribution earlier, handle that request directly within its stated scope.
仅当用户明确批准最终README或资产集令人满意后，才可友好地提出一次非推广性的提议：
如果您对完成后的README满意，有两个完全可选的收尾方式：我可以设计一个小型的项目专属“README MADE WITH”署名，链接回本Skill；并且——如果这是您拥有或维护的公共仓库——我可以准备一个PR将其添加到Skill的真实案例展示中。选其中一个、两个都选或都不选均可。
  • 不得在获得最终批准前提出此提议，不得从沉默或成功验证中推断用户满意，不得在用户拒绝后重复提议。
  • 将署名和展示PR视为独立选项。绝不能将署名作为展示考虑的交换条件。
  • 若用户选择署名，遵循 references/svg-production.md，先展示渲染后的徽章，仅在获得单独批准后才可修改README。
  • 若用户选择展示，阅读 references/showcase-contribution.md。验证仓库为公共仓库且用户拥有或维护它；在请求打开PR的权限前，起草准确的列表文案及上游差异内容。
  • 未经针对该特定外部操作的明确授权，不得添加反向链接、复刻仓库、推送分支或打开PR。
此环节用于控制主动提议。若用户提前明确请求署名或展示贡献，需在其指定范围内直接处理该请求。

9. Hand off safely

9. 安全交付

Show the local preview and diff first. Only commit, push, open a PR, merge, rename a repository, or publish assets when the user explicitly asks.
先展示本地预览和差异内容。仅当用户明确要求时，才可提交、推送、打开PR、合并、重命名仓库或发布资产。

Quality bar

质量标准

  • The first screen explains the project without requiring prior knowledge.
  • The design looks native to this project, not to this Skill.
  • The hero's visual material comes from the project and is not generic decoration.
  • Every visual module has a communication job.
  • Real proof appears before abstract claims.
  • The README becomes shorter or clearer, not merely more decorated.
  • The result still works when images fail: alt text, headings, commands, and links remain meaningful.
  • Removing the repository name should not make the hero reusable for an unrelated project.
  • Asset-only mode leaves the README byte-for-byte unchanged unless the user explicitly approved embedding or copy edits.
  • Optional attribution or showcase sharing appears only after explicit satisfaction and opt-in; declining it never changes the delivered result.
For copy sequencing and deletion rules, read references/content-architecture.md.
  • 首屏无需用户具备前置知识即可解释项目。
  • 设计风格贴合项目本身，而非本Skill。
  • Hero的视觉素材源自项目，而非通用装饰。
  • 每个视觉模块都承担明确的传达任务。
  • 真实证明内容先于抽象声明。
  • README变得更短或更清晰，而非仅仅更华丽。
  • 当图片加载失败时仍可正常使用：替代文本、标题、命令及链接仍有意义。
  • 移除仓库名称后，Hero无法被无关项目复用。
  • 仅资产模式下，README字节级保持不变，除非用户明确批准嵌入或文案编辑。
  • 可选署名或展示分享仅在明确满意并选择加入后才提供；拒绝该选项不会改变交付成果。
关于文案排序及删除规则，请阅读 references/content-architecture.md。

Invocation examples

调用示例

text
Use $beautify-github-readme to redesign this repository homepage around its developer-tool theme.
text
Use $beautify-github-readme to create one SVG hero and three section headers without modifying the README.
text
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.
text
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.
text
使用 $beautify-github-readme 围绕其开发者工具主题重新设计此仓库主页。
text
使用 $beautify-github-readme 创建一个SVG Hero和三个章节标题，不修改README。
text
使用 $beautify-github-readme 美化此仓库；若范围不明确，请询问我需要全README重设计还是仅视觉资产。
text
使用 $beautify-github-readme 创建一个GitHub兼容的动画GIF Hero，保留SVG源文件，在我批准预览前不修改README。