Communitygithub.com

geekjourneyx/readme-generator

為 GitHub 專案生成作品集等級的 README.md。支援「幫我寫 README」「生成 README」「優化 README」等請求,輸出包含克制的敘事、高品質視覺資產、MIT 授權、GitHub 描述與主題建議。

readme-generator 是什麼?

這是一個專為 AI 代理(如 Claude Code、Cursor、Codex)設計的技能,能自動為 GitHub 專案生成高品質、作品集風格的 README.md。它遵循「先敘事、再美化」的第一性原理,優先幫助專案講好故事,避免套模板、堆資訊或過度設計。該技能支援多種平台,其核心流程包括:讀取專案結構提煉故事、判斷視覺類型(單純文件型或視覺型)、使用 Codex Image Gen 或 HTML to PNG 備案生成不超過兩張的視覺資產(banner 與 features),最後組裝出符合 100 分標準的 README。此外,它還會提供 GitHub Description 與 Topics 的星級建議,並可選用 gh CLI 自動更新倉庫元資訊。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add geekjourneyx/readme-generator

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

預覽

來自技能 README

License: MIT
readme-generator preview
readme-generator preview

說明文件

GitHub README Generator

README 是專案的第一張作品集頁面。它不是說明書的目錄,也不是功能清單的容器。它要在很短時間內回答三件事:

  1. 這是什麼。
  2. 為什麼值得看。
  3. 我怎麼開始使用。

本 Skill 的目標是生成 100 分 README 作品:清楚、有美感、克制、可信,能讓專案像一個完整作品一樣被理解。


第一性原理

README 是信任入口和路徑入口,不是完整文件。它應該幫助第一次打開倉庫的人做出快速判斷:

  1. 這個專案解決什麼問題。
  2. 它適不適合我。
  3. 我是否能馬上執行、安裝或繼續了解。

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.md
  • package.json / pyproject.toml / go.mod / Cargo.toml
  • docs/
  • 主要入口檔案
  • 範例、截圖、演示檔案

判斷場景和視覺預算:

場景判斷方式策略圖片上限
新建 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 圖片有兩類:

  1. 作品封面:傳達氣質、主題、記憶點。
  2. 結構說明圖:傳達步驟、能力、對比、流程。

根據用戶意圖選擇模式:

模式適用場景圖片策略
portfolio預設推薦,適合需要展示完整作品感的專案1 張封面 + 1 張核心能力圖
clean-docSDK、庫、後端工具、嚴肅基礎設施0-1 張圖,優先快速開始和範例
visual-storyAI 工具、設計工具、獨立產品、作品展示最多 2 張圖,Codex Image Gen 負責記憶點
structured用戶明確要資訊圖、對比圖、流程圖1-2 張 HTML/CSS 海報,保證文字準確

預設先判斷專案類型,不要強行套 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 截圖兜底。

圖片職責

圖片目標推薦方式
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.webp2-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: 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、驚嘆號、行銷形容詞。
  • 不寫無法從專案事實支撐的能力。

評分:

維度分值判斷
準確性40是否忠於專案真實能力
搜尋價值25是否覆蓋 GitHub / Google 常搜詞
AI 可引用性20是否能被 ChatGPT / Claude / Perplexity 直接理解
克制程度15是否沒有誇張和廢話

星級:

分數星級
90-1005 星,推薦使用
80-894 星,可用但可再精簡
70-793 星,只適合備選
< 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 並打開檢查。

最終匯報只說清楚:

  • 改了什麼。
  • 結果怎樣。
  • 哪些驗證跑過。
  • 是否還有需要用戶決定的點。

不要把實現細節和冗長過程寫給用戶。

相關技能