GitHub README Generator
README 是專案的第一張作品集頁面。它不是說明書的目錄,也不是功能清單的容器。它要在很短時間內回答三件事:
- 這是什麼。
- 為什麼值得看。
- 我怎麼開始使用。
本 Skill 的目標是生成 100 分 README 作品:清楚、有美感、克制、可信,能讓專案像一個完整作品一樣被理解。
第一性原理
README 是信任入口和路徑入口,不是完整文件。它應該幫助第一次打開倉庫的人做出快速判斷:
- 這個專案解決什麼問題。
- 它適不適合我。
- 我是否能馬上執行、安裝或繼續了解。
1w star 以上開源專案通常不是靠資訊量取勝,而是靠清晰的首屏、直接的上手路徑、可信的文件入口和克制的社群資訊取勝。圖片、徽章、作者資訊和設計理念都只是輔助;一旦它們拖慢理解,就是噪音。
本 Skill 的核心取捨:README 先講清專案,再做美化;視覺服務理解,不替代理解。
作品標準
用下面的評分表約束所有輸出:
| 維度 | 分值 | 判斷標準 |
|---|---|---|
| 15 秒理解 | 25 | 首屏能看懂專案名、價值、適用對象 |
| 專案故事 | 20 | 不是堆功能,而是講清背景、動機和結果 |
| 視覺表達 | 20 | 圖片像作品,不像小字流程截圖 |
| 快速開始 | 15 | 安裝和使用路徑短、明確、可複製 |
| 可信產物 | 10 | 展示真實輸出、能力邊界或結果 |
| 克制降噪 | 10 | 去掉重複、口號、過度解釋和裝飾 |
低於 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.mdpackage.json/pyproject.toml/go.mod/Cargo.tomldocs/- 主要入口檔案
- 範例、截圖、演示檔案
判斷場景和視覺預算:
| 場景 | 判斷方式 | 策略 | 圖片上限 |
|---|---|---|---|
| 新建 README | 沒有 README,或 README 很短 | 完整生成,但保持短路徑 | 1-2 |
| 升級 README | 已有 README,有有效內容 | 保留獨特內容,重寫結構和首屏 | 0-2 |
| 作品集強化 | 用戶強調美學、故事、展示 | 優先做敘事和封面表現 | 2 |
| 純文件模式 | SDK、庫、後端工具、基礎設施 | 少圖,重安裝、API、文件入口 | 0-1 |
| UI / 產品展示 | 有介面、截圖、demo、視覺結果 | 用真實結果或封面輔助理解 | 1-2 |
升級現有 README 時,不要刪除用戶已有的關鍵內容。先提取可保留內容,再重排。
降噪審查
寫 README 前先標記哪些內容應外移或刪除:
| 內容 | 預設處理 |
|---|---|
| 設計評分表、工作原則、內部方法論 | 放在 SKILL.md 或 docs/,不進 README |
| 生成檔案樹、模板變數、腳本細節 | 只在用戶需要開發文件時保留 |
| 第三張流程圖 | 刪除,改成 2-4 行正文或簡短列表 |
| 過多社交連結 | 只留 GitHub / 主頁等核心入口 |
| 太泛的功能列表 | 合併成 3 個結果導向能力 |
| 安裝前的長背景 | 縮短,快速開始提前 |
Phase 1: 專案故事提煉
採集或推斷 7 個欄位:
| 欄位 | 說明 |
|---|---|
project_name | 專案正式名稱 |
tagline | 一句話價值主張,短、有判斷 |
origin | 專案出現的背景:為什麼需要它 |
audience | 誰會用它 |
promise | 它幫用戶得到什麼結果 |
proof | 真實能力、截圖、輸出、範例、指標 |
start | 最短上手路徑 |
不要問太多問題。能從專案裡推斷就直接推斷;只有影響敘事準確性時才問用戶。
推薦敘事結構
專案名
一句話價值主張
視覺封面(按專案類型決定是否需要)
這是什麼
為什麼需要它
你會得到什麼
快速開始
範例或輸出
工作方式(正文,不預設配圖)
安裝
授權條款
作者
如果專案偏工具、庫或基礎設施,把「快速開始」提前到「為什麼需要它」之後。README 的順序要服務讀者行動,不服務模板完整性。
Phase 2: 視覺生成方式選擇
README 圖片有兩類:
- 作品封面:傳達氣質、主題、記憶點。
- 結構說明圖:傳達步驟、能力、對比、流程。
根據用戶意圖選擇模式:
| 模式 | 適用場景 | 圖片策略 |
|---|---|---|
portfolio | 預設推薦,適合需要展示完整作品感的專案 | 1 張封面 + 1 張核心能力圖 |
clean-doc | SDK、庫、後端工具、嚴肅基礎設施 | 0-1 張圖,優先快速開始和範例 |
visual-story | AI 工具、設計工具、獨立產品、作品展示 | 最多 2 張圖,Codex Image Gen 負責記憶點 |
structured | 用戶明確要資訊圖、對比圖、流程圖 | 1-2 張 HTML/CSS 海報,保證文字準確 |
預設先判斷專案類型,不要強行套 portfolio。視覺資產生優先級固定為:
- Codex Image Gen Skill:優先使用 Codex 內建圖片生成能力產生視覺資產。
- 輕量化:README 展示圖優先轉成 WebP,再寫入 README 引用路徑。
- HTML to PNG fallback:只有當 Image Gen 不可用、輸出不符合要求、或用戶明確要求結構化精確文字時,才退化到 HTML/CSS 模板截圖。
不要把 HTML 截圖當預設路徑。它是可靠兜底,不是首選視覺方案。
Phase 3: 作品級視覺資產生
預設輸出使用兩個穩定檔名:
assets/banner.webp
assets/features.webp
這樣 README 引用路徑穩定,不管圖片來自 Codex Image Gen 還是 HTML 截圖兜底。
圖片職責
| 圖片 | 目標 | 推薦方式 |
|---|---|---|
banner.webp | 專案名片,建立專案名、定位和記憶點 | Codex Image Gen 優先 |
features.webp | 核心能力、結果或必要流程的傳播圖 | Codex Image Gen 優先;文字精確時 HTML 兜底 |
不要預設生成 workflow.png 或 workflow.webp。如果用戶明確要求流程圖,把流程內容合併進 features.webp 或放到正文,不新增第三張圖。
預設視覺風格
所有 README 視覺資產預設採用同一套風格:
黑底、極簡、電影打光、高對比、大留白、低亮度、白/灰/暖金三色、高級雜誌封面感。
畫面質感:極深黑背景 #050505,紙張顆粒,淺景深,體積霧,細窄輪廓光,局部金屬質感。
品質目標:出自 1w star 設計師水準作品。
設計約束:
- 背景以
#050505深黑為主。 - 色彩只使用白、灰、暖金;不要引入彩虹漸變、紫藍霓虹或高飽和裝飾色。
- 使用大留白和局部光,而不是堆元素。
- 圖片應該有少量高價值文字,承擔傳播和定位,不做長說明。
- 文字越少越強:每張圖只保留讀者離開 README 後仍該記住的資訊。
- 不放段落、命令、表格、版本號堆疊和密集說明。
專案名片文字策略
預設使用「專案名片型圖片」,不是純氛圍圖。
| 圖片 | 推薦文字 | 上限 |
|---|---|---|
banner.webp | 專案名 + 一句話定位 + 1-3 個短標籤 | 18 個英文詞或 28 個中文字 |
features.webp | 2-3 個結果短語,必要時加一個短標題 | 每個短語 2-5 個詞 |
好文字應該像封面標題,不像說明書:
- 專案名必須清楚,優先放在
banner.webp。 - 定位句說結果,不說口號,例如 “Portfolio-grade README design for open source projects”。
- 標籤只放搜尋和記憶價值最高的詞,例如
Story、Visual、Signal。 - 中文可以用,但要少;英文專案名、短英文標籤通常更穩。
- 如果 Image Gen 把文字寫錯,重試一次;仍不準確時,保留 Image Gen 視覺底圖,用 HTML/CSS fallback 承載精確文字。
- 不為了「全程 AI 生成」犧牲專案名和定位的準確性。
字號底線
按 1920×1080 設計時:
| 元素 | 最小字號 |
|---|---|
| 主標題 | 92px |
| 中文主標題 | 80px |
| 大卡標題 | 48px |
| 正文說明 | 28px |
| 輔助標籤 | 22px |
| 頁腳 | 20px |
不要使用 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)
</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、驚嘆號、行銷形容詞。
- 不寫無法從專案事實支撐的能力。
評分:
| 維度 | 分值 | 判斷 |
|---|---|---|
| 準確性 | 40 | 是否忠於專案真實能力 |
| 搜尋價值 | 25 | 是否覆蓋 GitHub / Google 常搜詞 |
| AI 可引用性 | 20 | 是否能被 ChatGPT / Claude / Perplexity 直接理解 |
| 克制程度 | 15 | 是否沒有誇張和廢話 |
星級:
| 分數 | 星級 |
|---|---|
| 90-100 | 5 星,推薦使用 |
| 80-89 | 4 星,可用但可再精簡 |
| 70-79 | 3 星,只適合備選 |
| < 70 | 不推薦 |
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 給出星級和理由:
| 星級 | 含義 |
|---|---|
| 5 星 | 強相關、高搜尋價值、應加入 |
| 4 星 | 相關且有發現價值,可加入 |
| 3 星 | 有一定關係,但不夠核心 |
| 2 星 | 相關性弱,通常不推薦 |
| 1 星 | 噪音,不加入 |
輸出格式:
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 並打開檢查。
最終匯報只說清楚:
- 改了什麼。
- 結果怎樣。
- 哪些驗證跑過。
- 是否還有需要用戶決定的點。
不要把實現細節和冗長過程寫給用戶。

