跳到主要内容

Agent Skill

将 Skill 加入 Claude、Cursor、Codex 等编程 Agent，即可掌握 byheai MCP 的模型与画幅选择、Prompt 编写、存储和网页优化。

创建 API KeyMCP 配置

为确保技术标识和代码可直接复制，详细协议参考及代码示例保留英文。

byheai agent skill 是一组轻量的 instructions 和 helper scripts，可安装到你的 coding agent（Claude Code、Claude Desktop、Cursor、Codex 等）中。它与 MCP server 协同工作：MCP 为 Agent 提供生成图片的工具，而 skill 则教会 Agent 在真实 coding workflow 中更好地使用这些工具。

没有安装 skill 时，已连接 byheai MCP 的 Agent 可以生成图片——但它必须猜测很多信息：该选哪个 model、什么 aspect ratio、图片应保存在哪里、是否需要为 web 优化。安装 skill 后，这些猜测会基于 Agent 正在构建的内容成为有依据的决策。

skill 教会 Agent 什么

skill 由一个 SKILL.md、一些 reference files 和一个 helper script 组成。安装后，只要你要求 Agent 在项目中创建、生成或添加图片，它就会生效。它会在四方面改变 Agent 的行为：

  1. 选择合适的 model。 Agent 不会默认使用上次见到的 model，而会提供 2–3 个选择及一句话的权衡说明——Nano Banana 适合快速、低成本，Nano Banana Pro 适合高要求作品，GPT Image 2 适合 photorealism 等。如果任务明显指向某个 model（例如需要可读文字的海报 → Nano Banana Pro），Agent 会跳过提问并说明原因。

  2. 选择合适的 aspect ratio。 Landing page hero → 16:9。Mobile splash → 9:16。Avatar → 1:1。并排 product card → 4:3。skill 包含 layout-to-ratio table，Agent 会查表，而不是每次生成都向你提问。

  3. 为你起草 Prompt。 如果你要求“add a hero image”却没有说明是什么，Agent 会读取周边代码——headings、brand copy、现有 colors——并提出一个可供确认的 Prompt。无需再经历“Prompt 应该写什么？”的往返沟通。

  4. 正确保存和优化。 Agent 会根据 framework 推断正确 folder（Next.js → public/、Astro → src/assets/ 等），并使用 bundled Pillow script 自动将用于 web 的图片转为 WebP。Poster、video thumbnail 和 OG card 则保持 full-resolution PNG，因为这些 surface 确实需要该格式。

完整的决策规则、model catalog、aspect-ratio guide 和 worked recipes（Next.js hero、MDX blog inline image、YouTube thumbnail、OG card、app icon、infographic 等）均位于 skill 中；Agent 会在需要时加载对应 reference file。

前提条件

安装 skill 前，请先确认已经完成以下两件事：

  1. 已创建 byheai API key。 skill 会调用 MCP server，而 MCP server 需要 key。若尚未创建，请打开 Dashboard > API keys。

  2. 已将 byheai MCP server 连接至 Agent。 没有它所教授的 MCP tools，skill 无法发挥作用。请先按客户端完成 MCP setup guide。

skill 本身不需要额外 credentials——它只是本地安装给 Agent 的 instructions。

安装 skill

skill 通过 skills.sh（开放的 agent-skill ecosystem）发布。使用 skills CLI 即可通过一条命令安装，支持 macOS、Linux 和 Windows。无需全局安装 CLI；npx 会按需运行它。

安装到当前项目：

npx skills add leonvanzyl/get-images-app --skill get-images

这会将 skill 放入项目的 Agent directory（.claude/skills/、.cursor/skills/ 或你的 Agent 使用的其他目录），使它和代码一起保存，团队成员下次 clone 后即可获得。

全局安装（供本机所有项目使用）：

npx skills add leonvanzyl/get-images-app --skill get-images -g

会安装到 ~/.claude/skills/get-images/。

只针对特定 Agent：

npx skills add leonvanzyl/get-images-app --skill get-images -a claude-code

CLI 默认会自动识别你已安装的所有 Agent。使用 -a 可将安装限制到一个 Agent（claude-code、cursor、codex、windsurf、cline 及其他 50 多种 Agent）。

先只查看 bundle 中的内容：

npx skills add leonvanzyl/get-images-app --list

该命令会列出可用 skills，但不会安装。

验证是否已安装

运行 CLI 的 list command：

npx skills list

输出中应能看到 get-images 及其安装目标 Agent。

然后在 Agent 中测试。例如询问：

Add a hero image to the top of the landing page.

正确安装的 skill 应出现下列行为之一，而不是立即调用 getimages_generate_image：

  • Agent 提供 2–3 个 model 选项和简短权衡（例如“Banana Pro for quality, Banana for cheap+fast”），或自行选择并说明原因。
  • 它根据 hero layout 推断 16:9 aspect ratio，而不是提问。
  • 它从 page copy 起草 Prompt 并请你确认后再消耗 credits。
  • 生成后，它将结果转为 WebP 并保存到 public/。

如果 Agent 只是盲目调用 MCP tool，而没有呈现这些决策，skill 可能没有被加载——请检查 install location 是否与该 Agent 读取的位置一致。

保持 skill 最新

npx skills update get-images

更新单个 skill。不带参数时，CLI 会更新它管理的全部 skills。

npx skills remove get-images

移除 skill。全局安装时使用 -g；或使用 -a 移除指定 Agent 的安装。

源码与贡献

skill 是开源的，与 MCP server 一同位于 GitHub 上的 leonvanzyl/get-images-app。核心内容由三个部分构成：

  • SKILL.md — 核心 trigger description 和 four-decision workflow。
  • references/models.md、references/aspect-ratios.md、references/workflows.md — Agent 按需读取的深入 reference。
  • scripts/optimize_for_web.py — 当图片用于 web 时，Agent 运行的 Pillow-based WebP converter。

欢迎提交 PR 和 issue，尤其是尚未覆盖的 workflow recipes（mobile app onboarding screen、podcast cover art、Twitter / X header 等）。

常见问题

已经使用 MCP 时还需要 skill 吗？ 不需要，skill 是可选的。没有它 MCP 也能正常工作；skill 只是让 Agent 更聪明、减少重复沟通，从而让你少花 Prompt 去协商本可由上下文推断的决定。

skill 会消耗 credits 吗？ skill 本身只是 instructions 和一个 Python script，不产生 credit cost。它教 Agent 调用的 MCP tools 仍会按正常方式消耗 credits；skill 的作用是让 Agent 更慎重地消耗它们。

skill 是否适用于不是 Claude Code 的 MCP-aware Agent？ 是。skills CLI 支持 50 多种 Agent（Cursor、Codex、Windsurf、Cline、Zed、JetBrains AI Assistant 等）。可使用 -a 指定一个 Agent，或让 CLI 自动识别。

WebP optimizer 从哪里获得 Pillow？ script 在首次运行时会检查 Pillow；若缺失，会输出 pip install Pillow 提示。大多数 coding environment 已安装它；否则只需执行一条 pip command。

不使用 npx 可以安装吗？ 可以。clone repo，然后手动将 .claude/skills/get-images/ 复制到 Agent 的 skills folder。CLI 只是为了方便。