Communitygithub.com

onovich/RepoCover

一个开源 AI 编码技能,用于在创建可编辑的 1280×640 GitHub 社交预览图前读取你的仓库。

RepoCover 是什么?

RepoCover 是一个专为 AI 编码代理(如 Claude Code、Codex)设计的开源技能,用于自动生成仓库特定的 GitHub 社交预览图。它通过读取仓库内容(如 README、源代码、视觉资源),优先采用确定性的、可编辑的 SVG 组合方式,而非通用的随机生成横幅。技能支持多种证据模式(远程静态、本地静态、构建测试等),并严格遵循产品不变量,例如输出精确的 1280×640 像素、小于 1MB 的 PNG 文件,以及保留可编辑的 SVG 源文件。整个工作流程包括:检查证据、编写设计台账、选择生产路径(代码原生 SVG、截图混合或插画混合)、构建并版本化 SVG、通过脚本进行机械渲染和验证,以及最终的视觉检查。它强调基于仓库证据的真实性,不冒用 GitHub 官方关联,并在上传前要求用户明确授权。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add onovich/RepoCover

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

RepoCover 是做什么的?

创建仓库特定的社交预览图,确保在缩略图大小时依然清晰可读。优先采用确定性的、可编辑的组合方式,而非通用生成的横幅。

产品不变量

  • 输出精确的 1280×640 光栅图,通常为 PNG 格式,体积小于 1,000,000 字节。
  • 在光栅图旁保留可编辑的源文件,通常为 SVG 格式。
  • 所有可见声明、指标、截图和证据均基于仓库实际内容。
  • 保留仓库的独特性,而非强加某种统一风格。
  • 在浅色和深色背景下验证完整尺寸及 320×160 缩略图效果。
  • 将图像创建与 GitHub 上传视为独立的授权边界。
  • 不暗示与 GitHub 有关联或背书。

加载正确的参考资料

每张封面都需要读取以下两个文件:

然后根据实际情况,仅读取适用的路径:

不要仅仅因为某个路径存在就加载不相关的参考资料。references/design-recipes.md 仅作为旧版提示词的兼容索引。

工作流程

1. 检查并界定证据范围

读取适用的 AGENTS.md 文件、README、包元数据、有意义的源代码路径、视觉资源以及任何现有的社交预览图。确定:

  • 仓库名称和主要用户任务;
  • 一个具体的价值主张;
  • 最多三个证据点;
  • 最有力的产品证据;
  • 已建立的视觉风格和需要排除的次要事实;
  • 证据模式:remote-static、local-static、build-tested 或 runtime-tested。

切勿在仅检查静态证据时,暗示已执行构建、运行时、场景或测试。如果 GitHub 的图像要求可能已变更,请根据官方 GitHub 文档进行验证。

对于远程仓库,使用可用的公共或经过身份验证的 GitHub 证据来检查其 README、目录树、清单文件、有意义的源代码、当前预览图以及最强的视觉资源。将输出保存在持久的用户可访问目录中,并记录源 URL 和声明边界。如果无法访问运行时或代表性界面,应说明此限制,而非假装远程证据等同于可工作的本地预览。可预览的本地项目(尤其是带有现有界面的 Web 项目)通常能提供最丰富的视觉证据。

2. 编写台账并选择路径

在开始绘图之前,根据附带的模板创建设计台账。至少记录:

  • 承诺、证据、排除项;
  • 证据模式及声明边界;
  • 源材料诊断或冷启动语义骨架;
  • 选择的生产路径和解释路径;
  • 素材、资产角色、布局和线条决策;
  • 输出版本、验证及推广判定(如适用)。

选择能保留仓库特色且规模最小的生产路径:

  • 代码原生 SVG(首选): 适用于开发者工具、图表、Logo、库和推断出的视觉系统。
  • 截图或源码混合: 仅当诊断后,自包含的源制品仍是最清晰的证据时才使用。
  • 插画混合: 仅当插画是仓库身份的核心时使用;生成不包含重要文字的插画,并在 SVG 中叠加精确的文本。

不要为了模仿已有的矢量系统而调用图像生成。

3. 构建并版本化可编辑源文件

默认输出路径为 docs/social-preview.svg 和 docs/social-preview.png,除非仓库有明确的资产约定或用户指定了其他目录。

  • 使用 1280 640 的 viewBox 和全画布背景。
  • 将关键内容保持在约 72 像素的外部安全区域内。
  • 将文案、产品证据、说明和签名划分为不重叠的区域。
  • 使用系统字体,除非仓库提供了合适的授权字体。
  • 嵌入本地证据或使用确定的 SVG 基元再现;避免外部运行时依赖。
  • 将图表、截图、重复标记和波形图裁剪到其所属区域内。
  • 除非明确要求替换,否则保留现有封面并创建带版本号的姊妹文件。

4. 机械渲染与验证

当 Sharp 可用时,使用附带的脚本进行渲染:

node <skill-directory>/scripts/render_svg.mjs <source.svg> <output.png>

仅在明确要求替换命名输出时使用 --force。在 Codex Desktop 中,加载工作区依赖项,并通过 NODE_PATH 使用返回的 Node 可执行文件和包路径;未经许可不得安装依赖项。

验证 PNG 和 SVG:

python <skill-directory>/scripts/validate_preview.py <output.png> --svg <source.svg>

创建标准缩略图检查表:

node <skill-directory>/scripts/create_review_sheet.mjs <preview.png> <review.png>

在 Windows 旧版代码页上,为读取 UTF-8 源码的工具设置 PYTHONUTF8=1。

5. 视觉验证

以完整尺寸检查光栅图,并检查生成的检查表。确认:

  • 仓库名称和价值主张在 320×160 尺寸下仍然可读;
  • 产品证据可识别且技术准确;
  • 文字、标记、裁剪、面板和装饰元素不重叠或裁切;
  • 布局在浅色和深色背景下均表现良好;
  • 每个可见元素都与承诺或证据对应;
  • 设计通过每一条适用的路径特定否决条件。

从左到右、从上到下扫描,每次修复一个命名的缺陷,重新渲染并重新验证。切勿将已知缺陷遗留下去。

对于批量生成,创建联系表并检查是否存在意外共享模板导致的偏差,然后再推广候选方案。

6. 仅在请求时上传

创建资产不代表授权更改 GitHub 设置。当用户明确请求上传时,打开:

https://github.com/<owner>/<repo>/settings

使用 社交预览 → 编辑 → 上传图片… 并遵循当前 UI 确认策略。上传后,获取公开仓库页面并验证 og:image 是否解析为新的 1280×640 图像。不要仅凭设置页面的缩略图报告成功。

移交

展示最终图像并报告:

  • 可编辑源文件路径;
  • 光栅图路径、格式、尺寸和字节大小;
  • 一句话设计理由;
  • 验证和版本推广状态;
  • 上传状态:未请求、待处理或已公开验证。

不要将项目特定的输出仅保留在临时或模型拥有的目录中。

相关技能