Communitygithub.com

brag-more

將當前專案的 GitHub README 轉換成精美的展示首頁——包含動畫 SVG 英雄區、專案專屬色彩與字型、設計過的特色卡片、宣傳影片或即時示範循環、誠實徽章、一句話標語、真實功能、可實際執行的快速入門指南,以及支援淺色/深色主題的視覺效果。

brag-more 是什麼?

brag-more 是一個智慧型 AI 代理技能,專門將專案的 GitHub README 從枯燥的文件轉變為吸睛的首頁。它會深入分析專案本體(程式碼、設定、轉折點),自動提取品牌色彩、字型、功能、安裝指令等資訊。技能的核心特色是生成一個精緻的動畫 SVG 英雄區,模擬產品的真實介面,並在專案自己的色彩和字型中展示。它還會自動建立示範影片或 GIF、設計特徵卡片,並以嚴格的準確性原則提供誠實徽章(只有當專案真正有發布、CI 管道或授權檔案時才會顯示)。brag-more 支援多種款式(clean、bold、minimal、showcase),並且專為 Claude Code、Cusor 和 Codex 等 AI 驅動的開發者環境設計。它確保所有宣稱都有專案支援、所有指令皆可執行、且 README 在任何裝置和主題下都易於閱讀。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/omer-chandna/brag-more/tree/HEAD/skills/brag-more

在你喜歡的 AI 中提問

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

預覽

來自技能 README

brag-more preview

說明文件

/brag-more

你已經把它做出來了。現在讓 repo 也會炫耀吧。README 是任何人在 GitHub 上看到的第一個東西;把它變成一個在五秒內就能推銷專案的首頁,並讓陌生人在一分鐘內從零開始執行。

無論是什麼專案,成果都應該像一個備受喜愛的開源專案的 README:自信、易於掃讀、視覺化、且真實。頁面上不應該有任何不值得存在的東西。

使用方式:/brag-more [options]。選項(標誌或自然語言):

選項預設值
--style clean|bold|minimal|showcase根據專案推斷(參見款式)
--preview關閉:直接寫入 README.md。啟用時,只寫入 brag-output/repo/,保留 README.md 不變
--no-banner橫幅開啟
--no-video關閉:如果專案沒有宣傳影片,先製作一個(參見影片)
--no-demo當有東西可展示時,示範開啟

工作檔案放在 brag-output/repo/ 中(如果 brag-output/ 已存在且不是來自本次執行,則使用時間戳 brag-output-YYYY-MM-DD-HHmmss/repo/)。README 引用的資源放在 repo 的 .github/readme/ 中,以便隨專案一起發佈。

1. 檢查

讀取專案,而不僅僅是舊的 README:

  • 現有的 README,每一行。這是使用者的撰寫。保留所有真實且有用的內容(安裝步驟、設定表格、致謝、授權條款、贊助連結、鳴謝);重新設計樣式,不要丟棄。
  • 識別身份: 來自樣式表或主題設定的精確品牌色彩和字型、標誌或 favicon、任何現有的英雄圖像或 OG 圖像。
  • 它是什麼: 套件清單(package.json、pyproject.toml、Cargo.toml、go.mod……)中的名稱、描述、版本、授權、二進位檔和腳本;入口點和主要路由或命令,以了解真實功能。
  • 如何執行: 來自清單腳本、Makefile、justfile、Dockerfile 或 CI 工作流程的實際安裝和啟動命令。注意專案鎖定的執行時期版本。
  • 徽章的訊號: LICENSE、.github/workflows/*、套件是否已發佈(npm、PyPI、crates.io——檢查清單中的名稱和 private 標誌)、git 遠端(git remote get-url origin)以取得 owner/repo。
  • 現有的 brag 輸出: 如果 brag-output*/brag.mp4 和 brag.jpg 存在,它們是機器上最好的示範素材。使用最新的。如果沒有,你將在下一個步驟中製作。

跳過建置輸出、鎖定檔案、.git/、環境和秘密檔案(.env、.env.*)、金鑰和憑證資料,以及 .gitignore 因這些原因排除的任何內容。

在寫入之前,回答:它用一句話就能讓陌生人理解是什麼?它是給誰用的?它比替代方案做得更好的那一件事是什麼?視覺鉤子是什麼——截圖、GIF 或橫幅,能讓人停止滾動?3–5 個真實功能是什麼?從 clone 到執行的最短路徑是什麼?

README 是公開的。絕不要將秘密、權杖、內部主機名稱、真實客戶或使用者名稱、電子郵件地址或其他個人資料帶入其中或其圖像中。如果截圖顯示了此類資料,請替換成合理的虛構替代品。

影片(在計劃之前,當還沒有時)

README 最好的示範是專案的啟動影片,所以 brag-more 在缺少時會製作它。當設定了 --no-demo 或 --no-video,或者 brag-output*/brag.mp4 已存在時,跳過此步驟。

  1. 如果已安裝 /brag 技能(檢查技能列表),透過 Skill 工具為此專案執行它,並傳遞任何 --tone 或格式需求。用一行話告訴使用者:「還沒有啟動影片,所以我先用 /brag 製作一個。」
  2. 否則讀取 <skill-dir>/video.md(這裡附帶的精簡影片工作流程,來自 brag-slim)並遵循它。它只需要機器上已有的工具。
  3. 完成時,影片、海報和分享文案都在 brag-output/ 中。繼續使用它們作為示範來完成 README。

如果製作影片失敗或使用者不想等待,則不使用它繼續進行,並使用示範下的備用方案。

2. 計劃

寫入 brag-output/repo/readme-plan.md:一句話介紹、選擇的款式、章節順序、你要製作哪些視覺效果以及它們各展示什麼、哪些徽章是有正當理由的(以及每個徽章的證據),以及你要從舊 README 中保留什麼。

形狀: 一個起始形狀,不是一個範本。刪除任何會是空或填充的章節。

  1. 英雄區 — 動畫 SVG 英雄區(參見建置),然後置中:一句話介紹、一行簡短徽章、以及一個導覽連結列(示範 · 安裝 · 文件 · …)。
  2. 示範 — 使用中的產品,就在英雄區下方,加上邊框:宣傳影片循環、真實 UI 的 GIF、或終端機錄製。一個大的視覺元素。
  3. 為什麼 — 2–4 句話:它為使用者做什麼以及它與眾不同的地方,用專案自己的話來說。對於開發者工具,一段 3–5 行的程式碼區塊作為賣點勝過一段文字(bun run index.tsx # TS and JSX out of the box)。
  4. 功能展示 — 3–6 個真實功能,每個都有自己的一個小視覺元素:真實 UI 的裁切截圖、每個指令的終端機 GIF、或一段程式碼片段及其輸出。視覺上豐富的以並排卡片方式佈局(參見建置)。純文字功能有一個粗體引導句和一行描述。
  5. 快速入門 — 可複製貼上,依序,每個指令都根據專案驗證過。先列出先決條件。
  6. 使用方式 — 一或兩個真實範例:一個指令及其輸出、一段程式碼片段、或一個設定區塊。
  7. 運作方式 — 可選。當架構是有趣的部分時,用一個簡短段落或 Mermaid 圖表。
  8. 舊 README 中的其他內容 — 設定、常見問題、路線圖、貢獻、致謝 — 整理好,當內容較長時折疊到 <details> 中。
  9. 頁尾 — 授權行,加上結尾的藝術條(參見建置)。

README 法則

  • 真實。 每一個宣稱、數字、功能和徽章都必須有專案支援。沒有虛構的星數、下載量、基準測試、推薦或「被用於」的標誌。徽章只有在它所指向的內容存在時才會出現(已發佈的套件、真實的工作流程、授權檔案)。
  • 可執行。 快速入門和使用方式中的每個指令都如撰寫般存在於專案中。如果可以安全地執行(安裝、建置、--help、測試),請執行它。如果某個步驟需要秘密或付費服務,請直接說明,而不是隱藏它。
  • 五秒測試。 從推文點進 repo 的人,知道它是什麼,看到它正在運作,並且無需滾動超過第一個畫面就能找到安裝指令。
  • 展示產品。 示範展示的是真實產品的使用情況,而不是標誌動畫或抽象藝術。重複使用真實的 UI、真實的 CSS、真實的文案。
  • 說明 repo 是什麼。 如果 repo 是產品的網站、登陸頁面或示範頁面,請在一句話介紹中說明;不要暗示人們可以下載一個 repo 沒有提供的應用程式或安裝一個套件。
  • 具體。 必須感覺是為這個特定專案撰寫的。「快如閃電」、「無縫」、「次世代」、「簡化你的工作流程」是被禁止的,除非專案確實值得使用這些詞。
  • 易於掃讀。 簡短的段落、有資訊量的標題、每個要點一個想法。只有在專案自己的語氣使用 emoji 時,才能在標題中使用,而且要節制(showcase 款式是例外:每個章節標題一個 emoji,這是刻意的設計)。
  • 兩種主題。 GitHub 的讀者使用淺色和深色模式。每張圖像在 #ffffff 和 #0d1117 上看起來都要好:具有可見邊緣的透明 PNG,或使用 <picture> 並為每種主題提供一個 prefers-color-scheme 來源。
  • 符合欄寬。 README 欄在桌面上約 830px 寬,在手機上更窄。橫幅文字在手機寬度下仍可閱讀;表格的欄數要少;不要使用會在行動裝置上中斷的寬原始 HTML 佈局。
  • 每個連結都可解析。 相對連結指向存在的檔案;錨點對應真實的標題。

款式

款式感覺使用時機
clean動畫英雄區,動作克制,有邊框的示範,整齊的卡片大多數專案;預設值
bold以品牌色彩全出血的英雄區,有更大的動畫時刻,強而有力的一句話介紹,示範放在最前面和中心消費者應用、有趣的專案、發表
minimal小動畫標誌鎖定 + 名稱 + 一句話介紹,樸素的章節函式庫、CLI、基礎設施、嚴肅的工具
showcase密集、emoji 分節的技術 README(想想獲勝的黑客松或研究專案):頂部有產品的真實截圖、獎項或狀態行、然後每個主題一個 emoji 引導的章節黑客松、研究、機器學習、資料或科學專案;任何有深度可以展示的內容。當使用者要求「像 Find My Shark 那樣的東西」或一個詳細、文件風格的 README 時選擇它

showcase 配方

以擁有者的 Find-My-Shark README 為模型。保留使其有效的部分,並修正無效的部分:

  • 標題帶一個 emoji 和成就行 在下面(「NASA Space Apps 2025, Galactic Impact Winner」),只有在專案真正獲得時才使用。詢問或從舊 README 中讀取;絕不要虛構。
  • 真實截圖或示範 GIF 直接放在標題下方,加上邊框(參見示範,有邊框)。只有當動畫英雄區能增加價值時才保留它;在這裡,真實產品才是主角。
  • 一個 2-3 行的介紹和「為什麼重要」行,然後是每個由一個 emoji 引導的章節:功能、區域/範圍或輸入、資料來源(表格)、運作方式或數學模型、快速入門(安裝、基本用法、API 用法)、專案結構(附註解的樹狀圖)、設定(真實的設定)、輸出檔案、命令列選項、背景、未來擴展、測試、日誌記錄、結尾標語。
  • 只包含專案有真實內容的章節。黑客松等級的深度是重點,所以保留細節:參數、公式、閾值、資料集名稱和專案樹狀圖。
  • 修正常見的疏漏: 使用真實的 clone URL(絕不要用 your-username),將專案樹狀圖程式碼區塊中過時的條目替換為實際存在的內容,在章節超過六個時添加目錄或快速連結行,將長的參考章節(CLI 選項、完整設定、科學背景)包裹在 <details> 中,為真實的技術棧(Python 版本、授權、關鍵函式庫)添加徽章,並在交付時使用 <picture> 或有邊框的截圖來支援兩種主題,並設定 repo 描述和主題。
  • 帶 emoji 的錨點: GitHub 會從標題的 slug 中移除 emoji,但保留連字號,所以 ## 🚀 Quick Start 是 #-quick-start,不是 #quick-start。以這種方式撰寫每個導覽連結和徽章連結,並檢查每個連結是否對應到其標題。<details> 的 summary 不是標題,也沒有錨點。
  • 仍然遵循每一條 README 法則(真實、可執行、兩種主題)和檢查步驟。

3. 建置

GitHub 上最好的 README(Excalidraw、Scalar、Supabase、Charm、Rich、Bun)都共享幾個技巧。全部使用它們;這就是讓這個 README 能讓人停止滾動的原因。

英雄區:一個動畫 SVG

這是簽名檔。一個靜態橫幅看起來像個範本;一個會動的英雄區——使用專案自己的色彩、字型和 UI——看起來就像為這個專案量身打造。GitHub 在 <img> 標籤中渲染 SVG,並執行其中的 CSS @keyframes,因此英雄區可以動畫化,而沒有 GIF 的條帶或體積問題。

建置 .github/readme/hero.svg(viewBox 約 1600×800,以 width="100%" 渲染):

  • 場景就是產品。 用 SVG 形狀重現專案的真實英雄區或關鍵畫面:其背景圖像、以自己字型呈現的標題、以及一個正在執行工作的真實 UI 元素(一張卡片滑動、一個指令打字、一個圖表繪製、一個 Toast 通知)。一個想法,一個循環。
  • 動畫: SVG 內部的 <style> 區塊中的 CSS @keyframes,只作用於 transform 和 opacity,任何會縮放或旋轉的元素都要加上 transform-box: fill-box; transform-origin: center。一個 6–10 秒的循環,能無縫回到起始畫面,進入動作交錯,每個文字行停留足夠長的時間以供閱讀。在背景上加入一個緩慢的飄移(在循環中從 1.0 縮放到 1.05),使畫面永遠不會感覺靜止。CSS transform 會取代元素的 SVG transform 屬性,所以使用外層的 <g transform=…> 定位,並動畫內層元素。
  • 減少動畫: 將 keyframes 包裹在 @media (prefers-reduced-motion: no-preference) 中,這樣選擇退出的讀者會看到已完成、靜止的畫面。靜止的畫面必須能單獨發布並展示產品,所以任何只在循環過程中出現的東西(一個匹配覆蓋層、一個 Toast)都應以 opacity="0" 屬性隱藏開始,並僅由其 keyframes 揭示。
  • 自包含。 透過 <img> 載入的 SVG 無法取得任何東西:無法透過 URL 取得網頁字型、無法取得外部圖像、無法執行腳本。將字型嵌入為 base64 @font-face(Google Fonts 的 latin 檔案已經約 20 KB,可以完整嵌入;使用 pyftsubset … --text="…" --flavor=woff2 子集化其他字型,這需要一個較新的 fontTools),或將文字轉換為路徑。將照片嵌入為 base64 JPEG,並調整大小為英雄區所需的大小。避免使用 <foreignObject>(Safari 在 <img> 內部不會渲染它)。保持檔案小於 ~1.5 MB。
  • 兩種主題。 如果英雄區是全出血且不透明的,它在兩種主題下都有效;否則也製作 hero-dark.svg,並使用 <picture> 或 #gh-dark-mode-only / #gh-light-mode-only URL 片段進行切換。
  • 文字: 專案名稱和一句話介紹,要大(英雄區在手機上會縮小到約 40%)。不要放其他東西。
<p align="center">
  <a href="<site or demo link>"><img src=".github/readme/hero.svg" alt="<Project> — <one-liner>" width="100%"></a>
</p>

也將靜止畫面以 1280×640 的大小捕捉到 .github/readme/social-preview.png(不透明),作為 repo 的社交卡片;在一個啟用減少動畫的無頭瀏覽器中渲染 SVG。

如果專案沒有值得動畫化的視覺識別(一個沒有 UI 的函式庫),則改為製作一個動態文字標誌:以合適字型呈現的名稱,一個能說明其功能的動作(一個值通過管道的流動、文字被格式化、測試變綠)。

示範,有邊框

按偏好順序:

  1. 宣傳影片。 在檢查步驟中找到或在影片步驟中製作的。如果 brag.mp4 存在,從其最精彩的 4–8 秒製作一個循環預覽 GIF 或動畫 WebP。

…

(完整內容因篇幅限制截斷)

相關技能