GitHub README Generator

README 是项目的第一张作品集页面。它不是说明书的目录，也不是功能清单的容器。它要在很短时间内回答三件事：

1. 这是什么。
2. 为什么值得看。
3. 我怎么开始使用。

本 Skill 的目标是生成 100 分 README 作品：清楚、有审美、克制、可信，能让项目像一个完整作品一样被理解。

第一性原理

README 是信任入口和路径入口，不是完整文档。它应该帮助第一次打开仓库的人做出快速判断：

1. 这个项目解决什么问题。
2. 它适不适合我。
3. 我是否能马上运行、安装或继续了解。

1w star 以上开源项目通常不是靠信息量取胜，而是靠清晰的首屏、直接的上手路径、可信的文档入口和克制的社区信息取胜。图片、徽章、作者信息和设计理念都只是辅助；一旦它们拖慢理解，就是噪音。

本 Skill 的核心取舍：README 先讲清项目，再做美化；视觉服务理解，不替代理解。

作品标准

用下面的评分表约束所有输出：

低于 90 分的 README 不交付；先删噪音、放大重点、重排叙事。

高星项目基线

默认向高星开源项目学习这些结构：

• 项目名 + 一句话价值主张。
• 少量必要 badge，不堆状态装饰。
• 快速开始或文档入口靠前。
• 示例只在能降低上手成本时出现。
• 贡献、社区、安全、许可证简洁清楚。
• UI / 产品项目可放截图；库、SDK、基础设施项目少图或无图。

不要把 README 写成设计宣言、完整说明书、功能墙、社交名片或内部工作流报告。

设计原则

必须坚持

• H1 必须是项目正式名称，紧跟一句价值主张。
• README 开头先讲项目价值，再放安装细节。
• 图片只表达一个重点，但应该承担项目名片功能：让读者一眼看到项目名和定位。
• 默认最多两张图片：一张封面，一张核心能力或结果图。
• GitHub 会缩小图片显示，图片里的主文案必须按海报字号设计。
• 对功能的描述要具体，但不夸张；能用结果说明就不要自夸。
• 对作者和许可证保持简洁，不做社交名片堆砌。

必须避免

• ASCII 艺术标题。
• emoji 装饰标题或作者表格。
• 大段“我们很专业”的空话。
• 6 个以上小卡片堆在一张图里。
• 流程图里塞满阶段、命令和小字说明。
• 把第三张流程图当作默认产物；工作方式通常用正文讲更清楚。
• 把 Image Gen 当作长文排版工具。
• 把 README 写成完整产品手册；详细文档应放到 docs/。

总体流程

Phase 0    项目阅读和模式识别
Phase 1    项目故事提炼
Phase 2    视觉生成方式选择
Phase 3    作品级视觉资产生成
Phase 4    README 组装
Phase 5    GitHub 元信息建议
Phase 6    验证和交付

Phase 0: 项目阅读和模式识别

先读取项目，而不是直接写模板。

检查：

ls
find . -maxdepth 2 -type f | sed 's#^\./##' | sort | head -80

优先读取：

• README.md
• package.json / pyproject.toml / go.mod / Cargo.toml
• docs/
• 主要入口文件
• 示例、截图、演示文件

判断场景和视觉预算：

升级现有 README 时，不要删除用户已有的关键内容。先提取可保留内容，再重排。

降噪审查

写 README 前先标记哪些内容应外移或删除：

Phase 1: 项目故事提炼

采集或推断 7 个字段：

不要问太多问题。能从项目里推断就直接推断；只有影响叙事准确性时才问用户。

推荐叙事结构

项目名
一句话价值主张
视觉封面（按项目类型决定是否需要）

这是什么
为什么需要它
你会得到什么
快速开始
示例或输出
工作方式（正文，不默认配图）
安装
许可证
作者

如果项目偏工具、库或基础设施，把“快速开始”提前到“为什么需要它”之后。README 的顺序要服务读者行动，不服务模板完整性。

Phase 2: 视觉生成方式选择

README 图片有两类：

1. 作品封面：传达气质、主题、记忆点。
2. 结构说明图：传达步骤、能力、对比、流程。

根据用户意图选择模式：

默认先判断项目类型，不要强行套 portfolio。视觉资产生成优先级固定为：

1. Codex Image Gen Skill：优先用 Codex 内置图片生成能力生成视觉资产。
2. 轻量化：README 展示图优先转成 WebP，再写入 README 引用路径。
3. HTML to PNG fallback：只有当 Image Gen 不可用、输出不符合要求、或用户明确要求结构化精确文字时，才退化到 HTML/CSS 模板截图。

不要把 HTML 截图当默认路径。它是可靠兜底，不是首选视觉方案。

Phase 3: 作品级视觉资产生成

默认输出使用两个稳定文件名：

assets/banner.webp
assets/features.webp

这样 README 引用路径稳定，不管图片来自 Codex Image Gen 还是 HTML 截图兜底。

图片职责

不要默认生成 workflow.png 或 workflow.webp。如果用户明确要求流程图，把流程内容合并进 features.webp 或放到正文，不新增第三张图。

默认视觉风格

所有 README 视觉资产默认采用同一套风格：

黑底、极简、电影打光、高对比、大留白、低亮度、白/灰/暖金三色、高级杂志封面感。
画面质感：极深黑背景 #050505，纸张颗粒，浅景深，体积雾，细窄轮廓光，局部金属质感。
质量目标：出自 1w star 设计师水准作品。

设计约束：

• 背景以 #050505 深黑为主。
• 色彩只使用白、灰、暖金；不要引入彩虹渐变、紫蓝霓虹或高饱和装饰色。
• 使用大留白和局部光，而不是堆元素。
• 图片应该有少量高价值文字，承担传播和定位，不做长说明。
• 文字越少越强：每张图只保留读者离开 README 后仍该记住的信息。
• 不放段落、命令、表格、版本号堆叠和密集说明。

项目名片文字策略

默认使用「项目名片型图片」，不是纯氛围图。

好文字应该像封面标题，不像说明书：

• 项目名必须清楚，优先放在 banner.webp。
• 定位句说结果，不说口号，例如 “Portfolio-grade README design for open source projects”。
• 标签只放搜索和记忆价值最高的词，例如 Story、Visual、Signal。
• 中文可以用，但要少；英文项目名、短英文标签通常更稳。
• 如果 Image Gen 把文字写错，重试一次；仍不准确时，保留 Image Gen 视觉底图，用 HTML/CSS fallback 承载精确文字。
• 不为了“全程 AI 生成”牺牲项目名和定位的准确性。

字号底线

按 1920×1080 设计时：

不要使用 18px 以下文字。GitHub 缩放后会不可读。

Codex Image Gen 产物只要求保持 16:9 和足够清晰，不要为了凑 1920×1080 而把好图强行重采样。README 展示图优先保存为 WebP；1920×1080 是 HTML to PNG fallback 的模板尺寸。

HTML to PNG fallback

仅在 Image Gen 不可用、用户要求精确结构化文字、或 Image Gen 输出无法通过检查时使用：

node scripts/gen_infographic.mjs /tmp/readme-banner.html assets/banner.png 1920 1080
node scripts/gen_infographic.mjs /tmp/readme-features.html assets/features.png 1920 1080
node scripts/convert_webp_assets.mjs assets/banner.png assets/banner.webp assets/features.png assets/features.webp

模板来自：

templates/banner.html
templates/features.html

模板变量：

{{PROJECT_NAME}}
{{TAGLINE}}
{{PRIMARY_COLOR}}
{{CATEGORY}}
{{PLATFORM}}
{{LANGUAGE}}
{{VERSION_INFO}}
{{TECH_CARDS}}
{{FEATURE_CARDS}}
{{FEATURE_COUNT}}

卡片结构：

• {{TECH_CARDS}} 用在封面右侧，建议 2-3 条，只放短标签和一句说明。
• {{FEATURE_CARDS}} 只放 2-3 张大卡，第一张可加 featured。
• 如果需要表达工作流程，用 features.webp 的 3 个结果阶段承载，不新增第三张图。

Codex Image Gen / gpt-image-2 方式

默认优先调用 Codex 自带图片生成能力，不要在项目里临时硬编码 API 脚本。

适合 Image Gen 的内容：

• README 封面。
• 产品氛围图。
• 作品集视觉。
• 抽象概念图。
• 用现有图片做风格延展。

不适合 Image Gen 的内容：

• 精确流程图。
• 大量中文文字或多段说明。
• 命令、版本、表格。
• 必须逐字准确的长文或 UI 图。

推荐 prompt 结构：

Use case: productivity-visual
Asset type: GitHub README visual asset, 16:9
Project: <project_name>
Story: <origin + promise>
Visual direction: black background, minimalist, cinematic lighting, high contrast, large negative space, low brightness, premium magazine cover
Texture and lighting: #050505 deep black background, subtle paper grain, shallow depth of field, volumetric haze, thin rim light, selective metallic highlights
Palette: white, gray, warm gold only
Composition: one strong visual idea, restrained, spacious, no dense UI
Quality bar: 10k-star designer portfolio quality
Text policy: include only high-value name-card text. Use the exact project name, one short positioning line, and optional 1-3 short labels. No paragraphs, commands, tables, tiny captions, or decorative text.
Avoid: emoji, clutter, fake interface text, tiny labels, generic gradients, bright neon, overdesigned dashboards

如果 Image Gen 不支持、无法调用、或输出出现错误文字/风格偏差，先用一个更短的文字 prompt 重试一次；如果仍不准，再退回 HTML to PNG 兜底流程承载精确文字。

图片轻量化

README 展示图片默认使用 WebP。WebP 通常比 PNG 更适合 README 加载；PNG 只作为 HTML 截图兜底的中间产物、透明图或需要无损保存时使用。

默认命令：

npm run webp

如果项目没有 WebP 转换脚本，优先使用 cwebp、sips 或可用的轻量工具。不要为了转换引入重型依赖。无法转换时再保留 PNG，并说明原因。

视觉检查

每张图生成后检查：

• 缩小到 GitHub README 显示宽度后仍能读。
• 一张图只讲一个重点。
• 没有小字堆叠。
• 项目名和定位句一眼可见。
• 图中文字没有拼写错误、乱码或伪文字。
• 没有过度装饰。
• 视觉风格和项目故事一致。
• Image Gen 图没有错误文字或多余水印。
• 压缩后图片仍然清晰，没有明显色带、噪点破坏或文字糊边。

Phase 4: README 组装

默认结构：

<div align="center">

# 项目名

**一句话价值主张**

<img src="assets/banner.webp" alt="[项目名] — [价值主张]" width="100%">

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

</div>

---

## 这是什么

[2-3 句话讲清项目、背景、结果。]

## 为什么需要它

[讲真实问题，不列反模式清单。]

## 你会得到什么

<img src="assets/features.webp" alt="[3 个核心能力]" width="100%">

## 工作方式

[2-4 行讲清工作方式；不要默认再放第三张图。]

## 快速开始

[最短可执行路径。]

## 安装

[依赖和安装命令。]

## 许可证

[MIT](./LICENSE)

## 关于作者

[简洁作者信息。]

规则：

• 不要超过 3 个 badge，除非项目确实需要状态标识。
• 不要在图片后重复同样的功能列表。
• 不要把“设计原则”“项目结构”“生成内容”都塞进 README；只保留对读者有用的部分。
• 不要默认放第三张 workflow 图；两张图已经足够承载作品感和核心信息。
• 如果有详细说明，放到 docs/，README 只做入口。

Phase 5: GitHub 元信息推荐

Repository Description 和 Topics 是 GitHub 搜索、Trending 关联、AI 搜索引用和人工快速判断的入口。它们不是 README 内容，不要写进 README.md；只在最终回复里作为独立建议输出。

First-principles 目标

• Description 回答：这个项目为谁创造什么结果。
• Topics 回答：这个项目应该被放进哪些搜索桶。
• 推荐数量 由信号质量决定，不追求多；高质量 7-9 个通常优于铺满 20 个。
• Trending / SEO / GEO 三者平衡：既要覆盖热门搜索词，也要保持项目事实准确，方便 AI 引用。

Description 生成规则

生成 3 个候选，并逐个打分：

[Verb] [specific outcome] for [audience] — [1-3 precise keywords]

硬约束：

• 英文优先，≤ 160 字符。
• 动词开头：Design / Generate / Build / Create / Convert / Automate。
• 包含项目最核心的 2-3 个关键词。
• 不用 emoji、感叹号、营销形容词。
• 不写无法从项目事实支撑的能力。

评分：

星级：

Topics 生成规则

先建立候选池，再筛选最终推荐。

候选来源：

• 项目类型：agent-skill, cli-tool, developer-tools, documentation
• 核心技术：nodejs, playwright, codex, image-generation
• 应用领域：readme, github-readme, open-source, portfolio
• 当前趋势：AI agent、image generation、developer tooling、documentation automation
• 项目实际文件和 README 叙事中出现的关键词

筛选规则：

• 推荐 7-9 个，不超过 10 个，除非项目确实横跨多个明确领域。
• Topic 必须小写，只用字母、数字和 hyphen。
• 删除太泛的词：software, tool, app, github, project, ai。
• 删除重复词：readme 和 github-readme 可以共存；open-source 和 opensource 只留一个。
• 不为追热门添加不真实 topic。

每个 topic 给出星级和理由：

输出格式：

GitHub Description 推荐：

1. ★★★★★ <description>
   理由：...

2. ★★★★☆ <description>
   理由：...

最终推荐：<description>

GitHub Topics 推荐：

加入：
- ★★★★★ github-readme — 精准描述项目用途
- ★★★★★ agent-skill — 符合项目形态
- ★★★★☆ image-generation — 当项目支持 Image Gen 时加入

不建议加入：
- ★★☆☆☆ ai — 太泛，搜索噪音大
- ★★☆☆☆ github — 太泛，不能帮助分类

可选 gh CLI 更新

如果用户安装了 gh，当前目录已经是 Git 仓库，并且能解析 GitHub remote，可以建议用户让 Agent 用 gh repo edit 更新。不要擅自更新；必须先给出将执行的内容并等待用户确认。

检查：

gh --version
git remote -v

建议命令格式：

gh repo edit OWNER/REPO \
  --description "<final-description>" \
  --add-topic topic-one \
  --add-topic topic-two \
  --add-topic topic-three

如果需要替换旧 topics，先读取当前 topics，再只移除明确不推荐的项：

gh repo view OWNER/REPO --json description,repositoryTopics
gh repo edit OWNER/REPO --remove-topic old-topic --add-topic new-topic

说明：git 不能更新仓库元信息

git 命令不能修改 GitHub 仓库的 Description 或 Topics。原因：Description 和 Topics 是 GitHub 平台元信息，不是 Git 仓库里的 commit、branch、tag 或 remote 配置。

git remote -v 只能用来识别 OWNER/REPO，不能用来更新元信息。

如果没有 gh，只给出推荐值，让用户到 GitHub 页面手动更新；不要提供复杂备选命令。

不要用 README 文件保存这些推荐；它们属于交付时对用户的操作建议。

Phase 6: 验证和交付

交付前必须验证：

node --version
npm run showcase
file assets/banner.webp assets/features.webp
git status --short

如果改了模板或实际图片，必须重新生成 WebP 并打开检查。

最终汇报只说清楚：

• 改了什么。
• 结果怎样。
• 哪些验证跑过。
• 是否还有需要用户决定的点。

不要把实现细节和冗长过程写给用户。