SurgePix Skills 完整教程(安装 + 使用)

一篇讲清楚：SurgePix Skills 怎么装、怎么用。装完之后，你在 Claude Code、Cursor 里直接说人话，就能做 PPT、出海报、抠图、生成小红书套图。

先搞懂：Skill 到底是什么

最近 Agent Skill 火了，各家出的技能五花八门，看得人眼花缭乱。

说白了，Skill 就是给 AI 装的“专业插件”——装上之后，你的 AI 就从“只会聊天”变成“能真正干活”。

SurgePix Skills是一套专门做视觉设计的技能。装上后，在 Claude Code / Cursor / Codex CLI 等本地 agent 里，不用打开浏览器，一句话就能让 AI 帮你抠图、做 PPT、出海报、生成小红书套图。

本文分两部分：怎么装和怎么用。

一、开始前的准备

已安装支持skill的本地Agent（Claude Code/ Cursor / Codex CLI 等）

已安装Node.js（终端跑 node -v 能显示版本号）

一个SurgePix API Key（到 surgepix.ai 获取）

网络能访问 GitHub 和 api.surgepix.ai

二、怎么装

有两条路线，任选一条。两条路线配 Key 的方式不同，建议别混着用。

路线 A：npx 一行安装（推荐）

最省心，而且以后更新也方便。

1. 安装

npx skills add SurgePix/agent-skills

安装器会问几个选项，按这个选就行：

看到 Installation complete 就装完了。

2. 配 API Key（环境变量方式）

npx 路线用环境变量存 Key，全局生效。

Windows（PowerShell）：

[Environment]::SetEnvironmentVariable(”SURGEPIX_API_KEY”, ”你的key”, ”User”)

设完关掉 PowerShell 重开才生效。

Mac / Linux（zsh）：

echo 'export SURGEPIX_API_KEY=你的key' >> ~/.zshrcsource ~/.zshrc

3. 验证

echo $env:SURGEPIX_API_KEY

（Mac / Linux 用 echo $SURGEPIX_API_KEY）能把 Key 打印出来，就配好了。

以后怎么更新

重跑一次就行，不用 clone、不用复制：

npx skills add SurgePix/agent-skills

路线 B：手动 clone

适合想把配置跟项目走的人。这条路线用 .env 文件配 Key。

1. 克隆仓库并进入

git clone https://github.com/SurgePix/agent-skills.gitcd agent-skills

2. 把 skills 复制到对应目录

以 Claude Code（Windows）为例：

Get-ChildItem skills\surgepix-* -Directory | Copy-Item -Destination ”$env:USERPROFILE\.claude\skills” -Recurse -Force

各工具的目标目录：

⚠️ 注意：SKILL.md 要直接在 surgepix-xxx 文件夹里，不能多嵌套一层，否则 agent 识别不到。

3. 配 API Key（.env 文件方式）

必须在agent-skills仓库文件夹里做——因为 .env.example 模板就在这里。

cp .env.example .env

打开 .env，找到这一行，把 Key 填在等号后面（不加引号、不留空格）：

SURGEPIX_API_KEY=sk-你的实际key

保存关闭。

4. 验证

node surgepix-setup/scripts/check_env.mjs

⚠️ 这条验证命令只在手动 clone 的仓库里有效（脚本就在仓库里）。如果你是用 npx 装的，目录结构不同，跑这条会报 Cannot find module——改用路线 A 的环境变量验证即可。

以后怎么更新

git pull

然后重新复制一次skills 到目标目录（这一步很容易忘）。

两条路线怎么选

再强调一遍：两条路线的配 Key 和验证方式不能混用。用 npx 装的就用环境变量验证；只有 clone 出来的仓库才能跑 check_env.mjs。

三、怎么用

装完之后，你不需要记任何命令——直接说人话就行。agent 会自己匹配对应的 skill，跑完把下载链接给你。

先确认装好了：启动 agent，问它一句「你现在有哪些 skills？」，能看到 surgepix-* 系列就对了。

💡 如果看不到，先重启一下 agent，大多数情况就好了。

目前支持的能力

直接说就行

生成 PPT：

生成一份 10 页的 Q3 营销复盘 PPT，商务风格，中文。

有大纲文件？直接把路径丢给它，它会自己读：

根据这个大纲生成 PPT：C:\Users\me\Desktop\大纲.docx

💡 Windows 拿路径小技巧：按住 Shift + 右键点文件 →「复制为路径」，最准。

生成海报：

创作一幅活动海报：「2026 产品发布会」，3 月 15 日，上海中心，现代科技风。布局以一幅中心主图为主，辅以较小的插图、辅助线和图表标注，并附上注释文字

生成小红书套图：

帮我生成一套小红书图，主题是咖啡馆开业，封面 + 3 张内页，温暖极简风。

文章插图：

给一篇讲远程办公效率的博客生成 16:9 插图。

去背景：

把 ./product.jpg 去背景

图片翻译：

把这张海报里的文字翻译成英文，设计保持不变：./poster-zh.png

竖版还是横版？说清楚能省一轮

有两个 skill 都能出图集，但不能混用：

如果你只说「帮我做几张图」，agent 会反问你要哪种。直接报平台名或比例，能省一轮对话。

一个重要的输出规则

每次生成，只会返回一个下载链接：

单张图

→ 直接给图片 URL

多张图

→ 给一个 ZIP 包，里面是整套图

图集里没有"单张链接"这个东西。如果 agent 给你列了「封面图链接」「第 2 张链接」之类的 URL，那是它编的——以 ZIP 为准。

长任务怎么办

生成是异步跑的，但默认 skill 会帮你等到底，一次性把成品链接给你，你什么都不用管。

如果是很长的任务、不想干等，可以让它立即返回一个 taskId，回头再查：

查一下任务 task_abc123 的进度

不满意？接着改

生成 PPT 会返回一个 sessionId。把它带上，就能在同一份稿子上迭代，而不是从头重生：

还是这份 PPT，换成浅色极简风格、蓝白配色 — session ID 123。

两版结果会落在 SurgePix 网页端的同一个 session 里。

本地文件怎么给

大部分 skill 直接支持本地路径，agent 会自己读、自己传。两个小技巧：

在文件所在的文件夹里启动 agent

，这样直接写 ./大纲.docx 就行，不用写全路径。

需要一个公开链接？说一句「把 ./logo.png 传上去，给我 URL」即可。

四、踩坑速查

🔒 最后，保护好你的 API Key

API Key 相当于密码。不要分享，不要出现在截图、录屏或公开仓库里。

万一泄露，立即到 surgepix.ai 吊销并重新生成一个。

源码与反馈
🔗 GitHub：https://github.com/SurgePix/agent-skills
📖API接入指引：https://surgepix.ai/blog/developer-guides/api-keys-reference
关注并回复【技能】获取全部教程及安装命令