social-preview

社交预览图

为 GitHub 仓库生成 Open Graph 社交预览图（1280x640px）。仓库在 Twitter、LinkedIn、Slack 和 Discord 上分享时，社交预览图是影响力最高的视觉素材。

安装

claude skill install social-preview

使用场景

• 新建的公开仓库需要社交预览图，然后才能分享
• 项目重新打造品牌形象（更换配色、名称或徽标）
• 重大版本发布或项目上线——更新预览图以体现这一里程碑
• 营销推广前（LinkedIn 帖子、Twitter 主题帖、博客专题）
• 检查现有仓库，找出缺失或过时的社交预览图

用法

/social-preview generate [repo-path]   # Create OG image from repo context
/social-preview audit [repo-path]      # Check if social preview is set, dimensions correct

如果未指定，repo-path 默认为当前工作目录。

---

流程：生成

按顺序执行每个步骤。不要跳过任何步骤。

步骤 0：解析命令

预期格式：/social-preview {mode} [repo-path]

提取模式（generate 或 audit）。如果缺失或无效：

Error: Invalid or missing mode.
Usage:
  /social-preview generate [repo-path]
  /social-preview audit [repo-path]

停止。

验证 repo-path 是包含 .git 的目录。如果未指定，则默认为当前工作目录。

步骤 1：扫描仓库以获取上下文

收集：

• 项目名称——来自 package.json 中的 name、Cargo.toml 中的 [package] name、pyproject.toml 中的 name，或目录名称
• 描述/标语——来自 package.json description、仓库描述，或询问用户
• 主要语言——根据文件扩展名、包管理器文件，或通过 gh repo view --json primaryLanguage 获取
• 徽标/图标——检查 logo.png、logo.svg、icon.png、icon.svg、.github/logo.png、assets/logo.*、branding/logo.*
• Git 远程地址——运行 git remote get-url origin 提取 owner/repo
• 现有社交预览图——通过 gh api repos/{owner}/{repo} 检查当前状态

步骤 2：选择模板

向用户展示模板选项：

1. 深色（推荐）——深色背景（#0d1117 或 #141414），浅色文字。对比度最高，在大多数信息流中的效果最好。
2. 浅色——浅色背景（#fafbfc），深色文字。符合某些品牌美学。
3. 极简——仅显示项目名称和标语，不加装饰。简洁且注重排版。

询问：“选择哪个模板？[dark/light/minimal]（默认：dark）”

如果仓库已有成熟的品牌配色（从 CSS 变量、tailwind 配置或用户指定的配色中检测），询问是否将其用作强调色。

步骤 3：生成 HTML 模板

创建一个独立的 HTML 文件（视口尺寸为 1280x640px），包含：

• 项目名称——醒目大字显示，最多 40 个字符。仅使用系统安全字体（不依赖外部字体）。
• 单行描述/标语——位于名称下方，字重较轻，最多 80 个字符。
• 主要语言/技术图标（可选）——简单的文字标识或 Unicode 符号。不依赖外部图片。
• 作者/组织署名（可选）——放在底部角落，以较小字号显示。GitHub 用户名或组织名称。
• 背景——纯色、CSS 渐变或细微的 CSS 图案（圆点、网格）。不使用外部图片。

将 HTML 文件写入 {repo-path}/social-preview.html（如果用户更倾向于使用临时文件，则写入 /tmp/social-preview-{repo-name}.html）。

步骤 4：渲染为 PNG

引导用户从以下三种渲染方式中选择：

选项 A——浏览器截图（最简单，无需依赖）：

1. 在任意浏览器中打开 HTML 文件
2. 将视口精确设置为 1280x640
3. 截取整页截图
4. 保存为 PNG

选项 B——Puppeteer/Playwright（自动化，需要 Node）：

node -e "
const puppeteer = require('puppeteer');
(async () => {
  const browser = await puppeteer.launch({ headless: true });
  const page = await browser.newPage();
  await page.setViewport({ width: 1280, height: 640, deviceScaleFactor: 2 });
  await page.goto('file:///PATH/TO/social-preview.html', { waitUntil: 'networkidle0' });
  await page.screenshot({ path: 'social-preview.png', clip: { x: 0, y: 0, width: 1280, height: 640 } });
  await browser.close();
})();
"

选项 C——云端渲染器：

• 如果用户更倾向于通过 URL 生成，可使用 npx @vercel/og 或托管式 OG 图像服务。

步骤 5：设置社交预览图

引导用户通过以下两种方式之一设置：

方法 A——GitHub UI：

1. 前往 https://github.com/{owner}/{repo}/settings
2. 滚动到“Social preview”
3. 点击“Edit” -> “Upload an image...”
4. 上传生成的 PNG
5. 点击“Save”

方法 B——GitHub API：

gh api repos/{owner}/{repo} \
  --method PATCH \
  --field "social_preview=$(base64 -i social-preview.png)"

注意：GitHub REST API 不支持直接通过 base64 上传社交预览图。UI 方式最可靠。若要自动化，请使用仓库设置页面。

步骤 6：验证

提供验证 URL：

• Twitter Card Validator：https://cards-dev.twitter.com/validator
• Facebook Sharing Debugger：https://developers.facebook.com/tools/debug/
• LinkedIn Post Inspector：https://www.linkedin.com/post-inspector/inspect/
• Open Graph Debugger：https://opengraph.dev/

告知用户粘贴仓库 URL，并确认预览能正确显示。

---

流程：审计

步骤 1：检查仓库

验证 repo-path 是一个带有远程仓库的 git 仓库。

步骤 2：获取当前社交预览状态

gh api repos/{owner}/{repo} --jq '.description, .homepage'

检查是否已设置自定义社交预览图（否则 GitHub 会自动生成一张）。

步骤 3：报告

=== Social Preview Audit: {repo-name} ===

Custom preview set: {YES / NO (using auto-generated)}
Description:       {repo description or "MISSING -- add one"}
Homepage URL:       {homepage or "not set"}

Recommendations:
  - {actionable items: missing preview, missing description, etc.}

Run /social-preview generate to create one.

---

设计原则

• 缩略图尺寸下清晰易读。 社交动态中的预览宽度约为 400px。文字在该尺寸下必须清晰可辨。
• 高对比度。 深色背景搭配浅色文字在大多数平台上效果更好。对比度至少为 4.5:1。
• 不要使用小字。 如果在 400px 宽度下无法清晰阅读，就删掉。画布为 1280px 时，项目名称应为 48-72px。
• 宽高比为 2:1。 1280x640 是标准尺寸。平台会裁切超出该比例的部分。
• 不依赖外部资源。 HTML 必须在不发起任何网络请求的情况下渲染。仅使用系统字体。所有 CSS 均内联。
• 文字越少越好。 项目名称 + 一句话标语。只有这些内容能确保清晰可读。
• 按实际分享尺寸测试。 定稿前务必在 400x200 尺寸下预览。

核心原则

1. 深色背景在 Twitter、LinkedIn 和 Slack 动态中效果更好。
2. 文字最多两行：名称 + 标语。
3. 按实际分享尺寸（宽 400px）测试，而不是按原始分辨率测试。
4. 使用 PNG 格式，文件小于 1MB。避免将 JPEG 用于文字较多的图片（会产生压缩伪影）。
5. 项目描述或品牌形象发生变化时，更新预览图。
6. 缺少社交预览图比一张简单的预览图更糟——GitHub 自动生成的预览图千篇一律，令人难忘的程度也很低。

文件

• HTML 模板： {repo-path}/social-preview.html 或 /tmp/social-preview-{repo-name}.html
• PNG 输出： {repo-path}/social-preview.png

反模式

• 不要使用外部字体 CDN 链接——仅使用系统字体，以确保可靠渲染
• 不要使用需要发起网络请求的图片或徽标——改用内联 SVG，或直接省略
• 在 1280px 画布上，文字不得小于 24px（否则在缩略图尺寸下难以辨认）
• 不要使用繁杂背景或照片背景——仅使用纯色或渐变
• 总颜色数不超过 3 种（背景、正文、强调色）
• 不要使用小尺寸下难以辨认的圆角或复杂形状
• 图片中不要包含完整 URL——浪费空间，且在缩略图尺寸下无法阅读