Communitygithub.com

brag-more

将当前项目的 GitHub README 转化为精美、引人注目的首页,包含动画 SVG 英雄区、设计精美的功能卡片、演示视频或实时循环演示,以及浅色/深色主题适配。

brag-more 是什么?

brag-more 是一个 AI 代理技能,旨在自动美化 GitHub 仓库的 README 文件,使其像精心维护的开源项目首页一样专业、可扫描、有视觉冲击力。它支持 Claude Code、Cursor、Codex 等 AI 代理平台。该技能通过以下步骤工作:首先深入检查项目代码、配置清单和现有 README,提取品牌颜色、字体、徽章信号和真实功能;然后制定详细的 README 规划,确保所有声明可验证、所有命令可运行;接着构建核心视觉元素,包括一个使用 CSS 动画、项目自有字体和颜色的自包含 SVG 英雄区,以及利用项目实际界面的演示 GIF 或视频;最后生成包含英雄区、演示、功能介绍、快速开始、完整使用指南等模块的 README 文件。技能提供 `clean`、`bold`、`minimal`、`showcase` 四种风格,适应不同项目类型,并严格遵守真实性、可运行性、可扫描性等 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

你构建了它,现在让仓库也炫耀一下吧。README 是任何人看到 GitHub 项目时首先映入眼帘的东西;将其转化为一个能在五秒内推销项目,并让陌生人在一分钟内从零开始运行的首页。

无论项目是什么,最终结果都应像一封来自备受喜爱的开源项目的 README:自信、可扫描、可视化且真实。页面上没有任何无用的内容。

用法:/brag-more [选项]。选项(标志或自然语言):

选项默认值
--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 引用的资源放在仓库的 .github/readme/ 目录下,以便随项目一起提供。

1. 检查

阅读项目,而不仅仅是旧的 README:

  • 现有的 README,逐行阅读。这是用户的写作。保留所有真实且有用的内容(安装步骤、配置表、致谢、许可说明、赞助商链接、鸣谢);进行重新排版,而不是直接丢弃。
  • 身份标识: 来自样式表或主题配置的确切品牌颜色和字体,logo 或 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 个真实功能是什么?从克隆到运行的最短路径是什么?

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. 演示 — 产品正在使用中,就在英雄区下方,边框内:brag 视频循环、真实 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 中的其他所有内容 — 配置、FAQ、路线图、贡献、致谢 —— 整理后,长内容折叠到 <details> 中。
  9. 页脚 — 许可证行,以及结尾的艺术条(见构建)。

README 法则

  • 真实。 每个声明、数字、功能和徽章都必须有项目支持。不得编造星标、下载量、基准测试、推荐语或“被...使用”的 logo。只有指向存在的内容(已发布的包、真实的工作流、许可证文件)时,徽章才能出现。
  • 可运行。 快速开始和用法中的每个命令都必须在项目中原样存在。如果可以安全运行(安装、构建、--help、测试),就运行它。如果某个步骤需要密钥或付费服务,请明确说明而不是隐藏。
  • 五秒测试。 从推文中跳转到仓库的人能在不滚动第一屏的情况下知道它是什么、看到它在工作、找到安装命令。
  • 展示实物。 演示显示真实产品正在使用中,而不是 logo 动画或抽象艺术。重用真实 UI、真实 CSS、真实文案。
  • 指出仓库是什么。 如果仓库是网站、登录页或产品的演示,请在一行介绍中说明;不要暗示人们可以下载应用程序或安装仓库未提供的包。
  • 具体。 它必须感觉是为这个确切项目编写的。“极快”、“无缝”、“下一代”、“简化你的工作流”是被禁止的,除非项目可衡量地值得它们。
  • 可扫描。 短段落、有意义的标题、每个要点一个想法。仅当项目自己的语气使用表情符号时才在标题中使用表情符号,并且要克制(showcase 风格是例外:每个章节标题一个表情符号,这是特意设计的)。
  • 双主题。 GitHub 阅读器使用浅色和深色模式。每张图片在 #ffffff 和 #0d1117 上看起来都很好:带有可见边缘的透明 PNG,或使用 <picture> 为每个主题提供 prefers-color-scheme 来源。
  • 适配列宽。 README 列在桌面上约 830px 宽,在手机上更窄。横幅文字在缩放到手机宽度时仍应清晰;表格列数少;避免在移动设备上撑坏宽原始 HTML 布局。
  • 每个链接都可解析。 相对链接指向存在的文件;锚点匹配真实的标题。

风格

风格感觉使用时机
clean带有克制运动的动画英雄、边框演示、整洁卡片大多数项目;默认
bold使用品牌颜色的全出血英雄,带有更大的动画时刻、有力的一行介绍、演示居中消费者应用、趣味项目、发布
minimal小的动画 logo 徽标 + 名称 + 一行介绍,简洁的章节库、CLI、基础设施、严肃工具
showcase密集的、表情符号分节的技术 README(像获奖的黑客松或研究项目):顶部是真实产品截图、奖项或状态行,然后每个话题一个表情符号引导的章节黑客松、研究、ML、数据或科学项目;任何有深度可展示的项目。当用户要求“像 Find My Shark 那样”或详细、文档风格的 README 时选择它

showcase 配方

以项目所有者 Find-My-Shark README 为蓝本。保留其精华,修复其缺陷:

  • 带有一个表情符号的标题和下面的成就行(“NASA Space Apps 2025, Galactic Impact Winner”),仅当项目真正获得该成就时才使用。从旧 README 中询问或读取;绝不编造。
  • 标题下直接放一个真实截图或演示 GIF,带边框(见演示,边框)。仅当动画英雄有额外价值时才保留它;这里真实产品才是主角。
  • 2-3 行介绍和“为什么重要”行,然后每个章节由一个表情符号引导:功能、区域/范围或输入、数据源(表格)、工作原理或数学模型、快速开始(安装、基本用法、API 用法)、项目结构(带注释的树)、配置(真实配置)、输出文件、命令行选项、背景、未来扩展、测试、日志、结尾标语。
  • 仅包括项目有真实内容的章节。 深度是关键,因此保持具体:参数、公式、阈值、数据集名称和项目树。
  • 修复常见的失误: 使用真实的克隆 URL(绝不是 your-username)、用存在的条目替换项目树代码块中的过时条目、一旦有超过六个章节就添加目录或快速链接行、将长的参考章节(CLI 选项、完整配置、科学背景)包装在 <details> 中、为真实技术栈添加徽章(Python 版本、许可证、关键库)、为双主题提供 <picture> 或带边框的截图、在交付时设置仓库描述和话题。
  • 带表情符号的锚点: GitHub 从标题的 slug 中移除表情符号但保留连字符,所以 ## 🚀 Quick Start 是 #-quick-start,而不是 #quick-start。以这种方式编写每个导航链接和徽章链接,并检查每个链接是否与其标题匹配。<details> 摘要不是标题,也没有锚点。
  • 仍然遵循每条 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=…> 定位元素,并动画化内部元素。
  • 减少动效: 将关键帧包装在 @media (prefers-reduced-motion: no-preference) 中,以便选择退出的读者看到完整、稳定的帧。稳定帧必须能独立发布并展示产品,因此任何仅在循环中间出现的内容(匹配叠加、toast)都以 opacity="0" 属性开始隐藏,仅由其关键帧揭示。
  • 自包含。 通过 <img> 加载的 SVG 不能获取任何内容:不能通过 URL 使用 web 字体、不能使用外部图像、不能使用脚本。将字体作为 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="<站点或演示链接>"><img src=".github/readme/hero.svg" alt="<Project> — <one-liner>" width="100%"></a>
</p>

还要将稳定帧捕获为 1280×640 到 .github/readme/social-preview.png(不透明)用于仓库的社交卡片;在无头浏览器中渲染 SVG,开启减少动效。

如果项目没有值得动画化的视觉身份(没有 UI 的库),则制作一个动画文字标记:使用合适的字体显示名称,一个动效说明它的功能(值流过管道、文本被格式化、测试变绿)。

演示,边框内

按优先顺序:

  1. brag 视频。 在检查中找到或在视频步骤中制作的视频。如果存在 brag.mp4,从其最强的 4-8 秒制作一个循环预览 GIF 或动画 WebP。

相关技能