goose-graphics

1. 概述

goose-graphics 是面向 Agent Skills 生态的便携式视觉技能包。样式和格式保存在中央 Gooseworks 库中，按需通过 npx gooseworks 获取，而不是随本仓库一起打包。该技能将此目录与一种用于参考图像的提取式工作流、一个 Unsplash + ASCII art 图像来源层，以及一个基于 Playwright 的 HTML 转 PNG 导出流程结合起来。

它可加载到任何会读取 SKILL.md 的宿主中——Claude Code Agent 可调用它进行自动渲染，Goose 流水线可将其接入内容生成，Cursor/Codex 项目可通过 .cursor/rules/ 或 ~/.codex/skills/ 引入它。每种样式都可通过 npx gooseworks styles get <slug> 获取精简的 DESIGN.md 规范，也可以直接上传到 Claude Design，作为设计系统脚手架。

格式模板、图像来源辅助工具和截图流程都位于此技能包中。样式、格式和示例渲染均按需从中央库获取，不会将任何 slug 写死在其中。

2. 调用方式

此技能支持 三种调用模式——完整参数、部分参数和交互式。根据需求选择最快的方式。

2.1 完整参数调用（最快方式）

/goose-graphics --style <slug> --format <format> [--brief "..."] [--ref <image-path>]

• --style <slug> — 任意社区发布的样式 slug。使用 npx gooseworks styles list / search 查找。选择样式生成时必填。省略此参数则由用户通过交互方式选择。
• --format <format> — 任意社区发布的格式 slug（例如 carousel、story、infographic、slides、poster、chart、tweet，以及社区添加的其他格式）。使用 npx gooseworks formats list 查找。选择格式生成时必填。
• --brief "..." — 主题／内容描述。此参数可跳过内容探索阶段。
• --ref <image-path> — 若提供此参数，则从参考图像中提取临时样式，用于本次渲染，而不使用预设样式。提供 --ref 时，将忽略 --style。若要创建可供其他 Agent 查找的持久发布样式，请改用专用的 /goose-graphics-create-style 技能。

三种分支：

1. 已提供所有必需参数（--style + --format + --brief 或 --ref + --format + --brief）→ 跳过探索和样式选择，直接进入 §7（设置输出路径）和 §8（生成 HTML）。
2. 部分参数 → 只询问缺少的内容。如果已设置 --style，但未设置 --format，则只询问格式。如果缺少 --brief，则只询问主题／内容。
3. 未提供参数 → 从 §3 开始执行交互流程。

2.2 示例

# Full args — one-shot generate
/goose-graphics --style matt-gray --format carousel --brief "How founders find their first 100 customers in 2026"

# Reference-driven — extract a one-off style from an image and build with it
/goose-graphics --ref ~/Desktop/mood.png --format poster --brief "Summer studio open house, August 14"

# Partial — Claude asks for the missing brief
/goose-graphics --style deep-ocean --format slides

# No args — full interactive flow
/goose-graphics

若要创建持久发布样式（包含精简规范、主视觉渲染和一些额外示例，并推送到中央库，供其他 Agent 查找），请改用专用的 /goose-graphics-create-style 技能。

2.3 参数不完整但含义明确时的默认处理方式

• 如果缺少 --brief，但可从用户后续文本中明确推断，则不要阻止流程，直接继续。
• 如果缺少 --format，则默认询问（不同格式之间没有安全的默认选项）。
• 如果 --style 和 --ref 都缺少，则进行询问——样式是必需项。

3. 查找样式和格式

样式和格式保存在中央 Gooseworks 库中，而不在此技能包中。请务必先列出或搜索，再判断某个 slug 是否存在——目录由社区驱动，并会随时间变化。

# List or search styles
npx gooseworks styles list
npx gooseworks styles search "warm editorial"
npx gooseworks styles list --mood "Organic & Warm" --tag warm

# Fetch a specific style's DESIGN.md (the slim spec) — pipe into Claude Design,
# or include in the agent context for HTML generation
npx gooseworks styles get <slug>

# Same shape for formats
npx gooseworks formats list
npx gooseworks formats search "vertical"
npx gooseworks formats get <slug>

用户提到某种样式或格式时，先运行 list / search，再获取所选 slug 的规范。切勿凭记忆假定某个 slug 存在——随着社区发布和弃用条目，slug 也会不断变化。

4. 发布你的风格

当用户通过 extract-style.md（或专用的 /goose-graphics-create-style 技能）创建新的美学风格并对其满意后，请将其发布到社区库，方便其他 Agent 和用户发现：

cd <directory-with-rendered-examples>
npx gooseworks styles publish

CLI 要求工作目录中包含 gooseworks-style.json 清单以及其中引用的 PNG 文件。具体格式请参阅 §13 清单格式。

4.1 描述撰写指南（至关重要）

描述决定了 AI Agent 能否在搜索目录时发现该风格。请将其视为搜索索引，而非装饰性文字。

• 50–200 个词，关键词密集。
• 开头点明氛围和用途。“大胆的杂志封面风格，适用于产品发布和活动海报。”
• 提及字体特点。“超大号窄体无衬线标题，搭配精致的正文衬线字体。”
• 提及配色特点。“锈橙色 + 奶油色 + 近黑色。”
• 适用时提及行业或受众。“DTC 美妆、独立出版、活动传单。”
• 避免只用泛泛的形容词。“漂亮”“现代”“简洁”若没有具体特点就毫无意义；请搭配配色、字体或行业背景。

4.2 标签撰写指南

• 使用 3–10 个小写标签。
• 涵盖：氛围（温暖、暗黑、活力）、密度（稀疏、密集）、正式程度（企业风、编辑风、俏皮）、时代（世纪中期、y2k、复古）、行业适配（saas、dtc、美妆、金融）。
• 跳过只是重复名称的标签。

4.3 示例数量指南

• 必须有主视觉示例——恰好一个示例标记为 isHero: true。选择最能展示该风格的格式。
• 建议额外提供 2–3 种格式，让目录图块展现多样性。
• 主视觉优先级顺序（如果可以渲染多个）：poster > carousel > infographic > slides > chart > story > tweet。

5. 发布你的格式

当现有社区发布的格式不适合用户的画布（例如，LinkedIn 横幅 1584×396、故事封面 1080×1920、活动传单 8.5×11in）时，请使用关联的 /goose-graphics-create-format 技能制作格式规范和至少一个渲染示例，然后发布：

cd <directory-with-format-bundle>
npx gooseworks formats publish

发布格式至少需要一个渲染示例——后端会拒绝空的 examples 数组。具体格式请参阅 §13 清单格式，了解 gooseworks-format.json 的确切结构。

格式的描述和标签指南与风格相同（§4.1、§4.2），但开头应写明尺寸 + 内容密度，而非氛围：

“1080×1920 的竖版画布，适用于 Instagram 和 TikTok 故事。单页构图，标题最多 5 个词，配大型主视觉图或数据统计。适用于快速公告和互动帖子，观众通常会在 2 秒内滑过。”

6. 宿主兼容性

将此技能包安装到正确路径后，大多数 Agent Skills 宿主都会自动加载 SKILL.md（本文件）。Claude Design 是唯一不会自动加载技能包的宿主——它通过手动上传，一次使用一个样式文件（DESIGN.md），并按需通过 npx gooseworks styles get <slug> 获取。

宿主	安装	说明
Claude Code	npx gooseworks@latest install --claude --with goose-graphics	与 GooseWorks 技能一同安装
Claude Desktop	（与上述相同的安装方式）	Desktop 使用相同的 Claude 技能
Claude Cowork	（与上述相同的安装方式）	基于 Claude Desktop 构建
Cursor	npx gooseworks@latest install --cursor --with goose-graphics
Codex (OpenAI)	npx gooseworks@latest install --codex --with goose-graphics
Claude Design	npx gooseworks styles get <slug> → 上传生成的 DESIGN.md，并通过 CD 的“创建新设计系统”操作完成	每种风格分别上传 DESIGN.md；不支持 CLI 同步

7. 首次运行设置

首次使用前，请检查截图工具的依赖项是否已安装。在 screenshot/ 文件夹中（相对于此技能文件）查找 node_modules/ 目录。

如果 node_modules/ 不存在，请运行：

cd [skill-pack-dir]/screenshot && npm install && npx playwright install chromium

将 [skill-pack-dir] 替换为包含此 SKILL.md 文件的目录的绝对路径。

8. 交互式工作流

1. Discover Intent   --> What format? What content?
2. Select Style      --> Pick from the catalog or extract from reference image
3. Select Sources    --> Unsplash photos? ASCII art? None?
4. Set Output Path   --> Where to save exports
5. Generate HTML     --> Using format spec + style spec + sources
6. Screenshot        --> Playwright PNG export
7. Deliver           --> Present results with file listing

9. 步骤 1：了解意图

询问用户想要创作什么。运行 npx gooseworks formats list 查看当前目录。七种基准格式如下：

格式	尺寸	适用场景
Carousel	每张幻灯片 1080x1080px	LinkedIn、Instagram 多页帖子
Story	每张幻灯片 1080x1920px	Instagram/LinkedIn Stories、TikTok、Snapchat
Infographic	宽 1080px，高度可变	社交媒体、博客嵌入
Slides	每张幻灯片 1920x1080px	演示文稿、网络研讨会
Poster	1080x1350px	Instagram 帖子、活动传单
Chart	1080x1080px	单张数据图表图片
Tweet	1080x1080px	推文尺寸的方形截图

社区库可能会发布其他格式（故事封面、播客封面、方形用户评价等）——始终先运行 list，不要假定只有七种基准格式 slug。请注意，每种社区格式都必须使用上述七种画布尺寸之一（渲染器锁定为此允许列表）；它们与基准格式的差异仅在于名称、用途和内容规则。如果没有已发布的格式符合用户需求，请推荐 /goose-graphics-create-format 技能。

用户选择格式后，获取其完整规格：

npx gooseworks formats get <format-slug>

返回的 spec.md（或内容规则）会说明布局、内容密度以及各部分的内容规则。遵循其中的内容探索阶段，向用户收集主题、内容和该格式所需的其他输入。

10. 步骤 2：选择风格

如果用户没有指定风格，请指引他们查看完整目录，以便直观浏览：

前往 https://skills.gooseworks.ai/styles 浏览风格目录，查看所有已发布风格及其渲染示例。

然后运行 npx gooseworks styles list（或 search "..." / list --mood "..." --tag ...），在线展示相关选项。按情绪分组展示候选项及其宣传语，供用户选择。

用户也可能会说：“我有一张参考图片”——此时，请阅读此技能包中的 extract-style.md，并按照其中的工作流，根据提供的图片提取自定义风格。该工作流会生成可发布的资源包（gooseworks-style.json + 渲染后的 PNG），用户可通过 npx gooseworks styles publish 发布。发布后，从步骤 3 开始继续工作流，并使用新的 slug。

用户选择 slug 后，获取其精简规格：

npx gooseworks styles get <slug>

返回的 DESIGN.md 包含生成所需的全部内容：配色方案、排版、布局、注意事项，以及可直接粘贴的 CSS 片段。

11. 步骤 3：图片来源（可选）

询问用户：“你想在图片中加入图像吗？”

选项：

• Unsplash 照片 — 阅读 sources/unsplash.md，并按照其中的搜索工作流查找和嵌入高质量图库摄影作品。
• ASCII 艺术装饰 — 阅读 sources/ascii-art.md，并按照其中的工作流生成和嵌入 ASCII 艺术元素。
• 两者都要 — 阅读两个来源文件，并同时融入这两种内容。
• 不需要图片 — 完全跳过此步骤。图片将仅使用纯 CSS/HTML 样式。

12. 步骤 4：输出路径

询问用户：“导出文件应该保存在哪里？”

默认位置：./goose-graphics-exports/

在该目录中，按照以下命名约定创建子文件夹：

[YYYY-MM-DD]-[slugified-name]/

例如：2026-04-17-q2-product-roadmap/

13. 步骤 5：生成 HTML

遵循所选格式规范中的 HTML 生成阶段。生成时：

• 应用所选样式的 CSS 变量、字体排版规则、调色板和间距系统 — styles get 返回的 DESIGN.md 包含所需的一切。
• 如果用户在步骤 3 中选择了图片来源（Unsplash URL 或 ASCII 艺术块），请将其纳入。
• 严格遵守格式规范的内容密度限制和结构要求。
• 将所有 HTML 文件写入步骤 4 中确定的输出目录。

14. 步骤 6：截图

运行截图脚本，将 HTML 文件导出为高分辨率 PNG：

node [skill-pack-dir]/screenshot/screenshot.js --format CANVAS --input INPUT_PATH --output OUTPUT_PATH

其中：

• [skill-pack-dir] 是此技能包目录的绝对路径。
• CANVAS 始终是七个内置画布标识之一，绝不能使用格式的目录标识。渲染器的允许列表很严格 — 传入 story-cover 或 linkedin-banner 之类的社区格式标识会导致失败。
• INPUT_PATH 是包含生成的 HTML 的目录或文件。
• OUTPUT_PATH 是保存 PNG 文件的目录。

使用下表，将格式的 width/height（来自 npx gooseworks formats get <slug>）映射到画布标识：

width × height	画布标识
1080 × 1080	carousel
1080 × 1350	poster
1920 × 1080	slides
1080 × 1920	story
1080 × ≥1080（可变）	infographic

示例：

• 内置 poster（1080×1350）→ --format poster。
• 社区格式 story-cover（1080×1920）→ --format story（因为该格式继承了 story 画布）。
• 社区格式 linkedin-quote-card（1080×1080）→ --format carousel（任何 1080×1080 的目录格式都会使用 carousel 画布渲染）。

如果格式的 width/height 与以上任何一行都不匹配，则表示该格式发布有误 — 请告知用户并停止。不要尝试使用自定义尺寸渲染；该工具不支持。

15. 步骤 7：交付

向用户展示结果：

• 列出所有生成的文件（HTML 源文件和 PNG 导出文件）及其文件大小。
• 提供输出目录的完整路径。
• 建议预览方式：在浏览器中打开 HTML 文件，或直接查看 PNG 文件。
• 对于轮播图和幻灯片，请注明幻灯片数量和顺序。

16. 特殊模式

• “给我惊喜” — 选择轮播图格式和 npx gooseworks styles list 返回的随机样式。只询问用户内容/主题，然后自动生成其余内容。
• 多格式 — 如果用户说“将此内容同时制作为轮播图和信息图”，则使用相同的内容和样式、不同的格式标识，完整运行两次工作流。将输出分别保存到不同的子目录中。
• 样式预览 — 在开始完整生成之前，先生成一张示例幻灯片或一个示例版块，供用户确认视觉方向。如果用户希望修改，请在生成其余内容前调整样式或切换标识。

17. Manifest 格式

这些 manifest 是用户在运行 publish 之前于其工作目录中创建的 CLI 输入文件。它们不会存放在此仓库中。

17.1 样式清单（gooseworks-style.json）

{
  "name": "Desert Sunset",
  "slug": "desert-sunset",
  "description": "Warm dusk gradients with rust and amber on cream paper. Editorial serif headlines paired with a single sans-serif accent. Built for DTC beauty product launches, lifestyle long-form, and event posters where you want a confident, sun-soaked, high-end magazine feel.",
  "designMd": "# Desert Sunset\n\n…full slim spec markdown — palette table, typography table, layout rules, do/don'ts, optional CSS variables block…",
  "moodGroup": "Organic & Warm",
  "tags": ["warm", "desert", "editorial", "serif", "dtc"],
  "palette": [
    { "hex": "#E06A2C", "role": "primary" },
    { "hex": "#3A1F1A", "role": "ink" },
    { "hex": "#F5EFE7", "role": "paper" }
  ],
  "examples": [
    { "format": "poster", "isHero": true, "file": "./poster.png", "caption": "Hero render" },
    { "format": "carousel", "file": "./carousel.png" },
    { "format": "story", "file": "./story.png" }
  ]
}

字段限制：

• name：1–120 个字符
• slug：可选的 kebab-case 格式 [a-z0-9-]+；如果缺省，后端会自动生成。若发生冲突，将返回 409 和 suggestedSlug — CLI 会处理重新提交。
• description：20–1000 个字符（必填）
• designMd：至少 50 个字符（必填）
• moodGroup：可选；取值之一为 "Dark & Moody"、"Light & Editorial"、"Organic & Warm"、"Bold & Energetic"、"Retro & Cinematic"、"Structural & Technical"、"Friendly Corporate"
• tags：字符串数组（默认值为 []）
• palette：{ hex: "#RRGGBB", role?: string } 数组
• examples：数组，至少包含 1 个条目，其中必须恰好有 1 个条目的 isHero: true
• examples[].format：现有图形格式的 slug（可使用 npx gooseworks formats list 中的任意格式）
• examples[].file：工作目录中 PNG 文件的相对路径

17.2 格式清单（gooseworks-format.json）

{
  "name": "Story Cover",
  "slug": "story-cover",
  "description": "1080×1920 vertical cover slide for Instagram and TikTok stories. Single hero panel, 5-word title max, optional brand mark in the lower 10%. Use for product launches and event reminders where the viewer scrolls past in 2 seconds.",
  "width": 1080,
  "height": 1920,
  "contentRulesMd": "## Rules\n\n- Title: 5 words max, large display, centered or top-left\n- One hero element (image, stat, or large icon) in the upper 70% of the canvas\n- Optional brand mark in the lower 10%, ≤8% of canvas height\n…",
  "tags": ["story", "vertical", "social", "instagram", "tiktok"],
  "examples": [
    { "file": "./example-1.png", "styleSlug": "matt-gray", "caption": "Paired with matt-gray" },
    { "file": "./example-2.png", "styleSlug": "neon-dashboard" }
  ]
}

字段限制：

• name：1–120 个字符
• slug：可选的 kebab-case 格式
• description：20–1000 个字符（必填）
• width / height：必须匹配七种内置画布之一：1080×1080（轮播图/图表/推文）、1080×1350（海报）、1920×1080（幻灯片）、1080×1920（快拍），或 1080×≥1080（信息图）。发布时会拒绝自定义尺寸，因为渲染器的允许列表严格受限。
• contentRulesMd：至少 50 个字符（必填）
• tags：字符串数组
• examples：数组，至少包含 1 个条目（必填 — 后端会拒绝空数组）
• examples[].styleSlug：可选，用于引用渲染示例所用的样式

18. 文件参考

此技能包仅提供渲染和获取图像所需的本地辅助工具 — 样式、格式和渲染示例均通过 npx gooseworks 从中央库获取。

图像来源

文件	描述
sources/unsplash.md	搜索并嵌入 Unsplash 库存照片。
sources/ascii-art.md	生成并嵌入 ASCII 艺术装饰。

提取样式

文件	描述
extract-style.md	根据参考图像派生自定义样式，并生成可发布的套件（gooseworks-style.json + 渲染后的 PNG）。

截图工具

文件	描述
screenshot/screenshot.js	基于 Playwright 的 HTML 转 PNG 导出脚本。
screenshot/package.json	截图工具的 Node.js 依赖项。