如果你最近在 GitHub 上翻 AI 项目大概率会产生一个感觉好像一夜之间所有东西都在聊Skill。从workbuddy skill这种工作流管理技能到taste skill这种个人偏好类的技能再到codex skill、claude code skill、opencode skill几乎每个热门 Agent 工具都在用自己的方式支持 Skill。而图片生成恰恰是 Skill 生态里最热闹、也最容易让人误解的领域。很多人以为“图片生成 Skill”就是给 AI 一个提示词然后让它出图。这个理解只对了一半。真正值得关注的是过去你要完成一张可用图片的产出需要经历注册模型服务、调 API、调参数、写提示词、过后处理、再落入项目目录这一整套流程。而 Skill 的出现把这条链路变成了一次“自然语言调用”。这篇文章我想围绕一个点展开Skill 解决的不是“AI 能不能画图”而是“AI 生成图片这个动作是否标准化、可复用、可沉淀到团队”。我会从零写一个图片生成 Skill也会聊一聊如何在 GitHub 上找到、安装、避坑第三方 Skill最后给出一套可以直接套用的工程规范。1. 这篇文章真正要解决的问题先抛一个场景。假设你是一个独立开发者正在给开源项目写 README需要一张简洁的项目架构图。你打开一个绘图工具拖了二十分钟画完发现风格和 README 整体不搭又改了一轮。这种时候你会不会想如果 AI 能帮我把这件事做掉就好了。再换一个场景。你是公司里的算法工程师给业务方做数据可视化图表。每次需求都要写一段 Python 脚本、调中文字体、设置配色、输出 PNG。脚本在不同机器上跑出来的效果还不一样。这时候你需要的不是“再调一次参数”而是一个能反复使用、不会偷偷改你风格的出图流程。这两个场景背后是同一个问题图片生成的技术门槛已经被模型服务商降得很低但“工程化门槛”却一直没人解决。你需要懂 API、懂参数、懂提示词、懂后处理还要把结果保存到正确的位置。Skill 就是冲着这个工程化门槛来的。我把“图片生成 Skill”的定义说清楚它是一个包含说明文件、脚本、依赖清单和元信息的小型技能包能让 Agent 在理解任务之后自动决定调用哪个脚本、传什么参数、把结果放到哪里。换句话说它不是“一个会画画的 AI”而是一个“按规范完成出图任务的自动化单元”。这篇文章适合三类读者第一已经入手 Claude Code、Codex、OpenCode 等 Agent 工具的开发者第二正在做 AI 产品、想给 Agent 增加图像能力的开发者第三被图片生成工具链折腾过、想找一套可复用方案的普通技术用户。读完你至少能写一个自己的图片生成 Skill并能判断 GitHub 上哪些 Skill 值得装、哪些不适合装。2. Skill 是什么与插件、自定义工具的核心区别Agent Skill 的概念这两年迅速兴起但很多人的理解停留在“插件换了个名字”。这个理解不准确。插件通常意味着一个独立的系统组件它运行在自己的进程里提供一组外部可见的能力。而 Skill 更接近“Agent 的说明书 脚本集”。它不是一个独立服务而是一套让 Agent 在面对某类任务时知道“该怎么做”的知识包。它的核心是两样东西说明文件描述这个技能在什么场景下使用、有哪些参数、内部流程是什么。可执行脚本真正干活的部分用 Python、Node.js 或者 Shell 脚本实现。对比表格更能说明问题维度传统插件Agent Skill运行方式独立进程或服务由 Agent 按需调用脚本核心能力对外提供 API 接口指导 Agent 完成任务流程可复制性需要安装到环境中一个目录即可分发维护方式插件框架升级时跟随升级纯脚本 文档基本不依赖框架开发者心智面向框架面向任务为什么选“目录 说明文件 脚本”这种看似简单的结构因为它把“能力”和“流程”解耦了。Agent 本身负责理解需求和拆解任务Skill 只负责提供某个环节的标准化操作。这个设计的直接收益是你可以把任意一个成熟的工作流封装成 Skill共享给团队或者发布到 GitHub 上让别人复用。从 GitHub 热点项目来看目前主流 Agent 都已经支持类似机制。Anthropic 的 Claude Code 有~/.claude/skills目录约定OpenAI 的 Codex 也在引入技能机制OpenCode 等开源命令行工具同样有自己的技能加载方式。这些工具虽然 API 不同但底层思路是高度一致的把能力描述成 Markdown 脚本放进约定目录Agent 自动发现并使用。这就是为什么我用“一个 Skill 搞定图片生成”来概括这次趋势——真正搞定的不是模型而是流程。3. 图片生成 Skill 的核心原理与典型工作流一个图片生成 Skill 内部到底发生了什么我用一个最小流程来拆解。当你在 Agent 里说“帮我生成一张 16:9 的项目封面图主题是云原生架构”时Agent 会经历以下步骤在技能目录中找到图片生成 Skill 的说明文件确认它能否处理这个任务。读取说明文件里的参数定义将“16:9”“云原生架构”映射到生成脚本的参数。执行封装好的脚本脚本负责调用图像生成模型的 API。脚本收到图片结果后按约定格式保存到项目目录或指定位置。将保存路径返回给 AgentAgent 再汇报给你。这个流程里真正关键的设计点是第 3 步。脚本不应该只做一次简单的 API 请求它应该具备参数校验、错误重试、文件命名、格式转换等基础能力。好的图片生成 Skill 和普通脚本的差距往往就体现在这些边界处理上。从模型服务层面看目前图片生成 API 主要分为两大类。一类是服务商提供的在线生成接口优点是开箱即用缺点是依赖网络和配额另一类是本地模型方案例如本地部署的 Stable Diffusion 及 ComfyUI优点是无外部依赖、可控性强缺点是需要 GPU 资源和环境配置。一个成熟的图片生成 Skill应该能通过配置项在这两种方案之间切换而不是写死某一种。网络热词里经常出现“ComfyUI 生成图片时预览窗口看不到图”这其实也属于工程化问题——模型已经把图生成了但前端预览没刷新。这类问题靠调 UI 或者换浏览器不一定根治正确的做法是在自动化脚本里直接轮询输出目录检测到新文件就返回。这也是为什么把图片生成封装成 Skill 之后体验更稳定的原因你不再依赖某个图形界面的状态而是直接和文件系统与 API 交互。4. 环境准备与前置条件实际动手前需要确认环境。我不会把版本号写死因为 Skill 生态变化太快本文演示的是通用思路。4.1 基础环境建议准备以下环境操作系统Linux、macOS 或 WindowsWSL 也可以。Python 3.9 以上包含pip命令。Node.js 18 以上部分 Skill 用 TypeScript 编写时需要。Git。如果你的机器上还没装 Python可以用系统包管理器安装。macOS 可以用brew install python3Ubuntu 可以用apt install python3 python3-pip。4.2 Agent 工具图片生成 Skill 最终要接进某个 Agent。目前推荐先选定一个工具避免同时维护多套配置。如果你已经在用 Claude Code直接使用~/.claude/skills目录。如果你在用 Codex参照官方文档启用技能目录。如果你偏好开源命令行工具OpenCode 等工具也有对应的 skills 目录约定。无论选哪个重点是理解一个原则Skill 的本质是目录、说明文件、脚本不绑定特定 Agent 的内部 API。这意味着同一个图片生成 Skill 理论上可以在多个工具之间复用只是目录位置不同。4.3 图像模型的访问凭证图片生成 Skill 总归要调用模型。准备一个可用的 API Token并配置到环境变量里。我建议使用形如IMAGE_API_KEY、IMAGE_API_BASE、IMAGE_API_MODEL的环境变量名后续脚本也从环境变量读取不要把密钥写进 SKILL.md 或脚本文件。如果你选择本地模型方案那需要确认你的服务已经在本机启动并开放了 HTTP 端口。以 ComfyUI 为例官方提供了 REST API但接口路径和请求格式以你部署版本的文档为准。4.4 目录规划建议我建议在项目根目录建一个skills目录或者用 Agent 约定的全局技能目录。下面所有示例都以本地项目内的skills/image-generator目录来说明路径清晰方便对照。5. 从零写一个图片生成 Skill完整代码实现这一节是本篇文章的核心实操部分。我们按三个文件来组织一个最小可用的图片生成 Skillskills/image-generator/ ├── SKILL.md └── scripts/ ├── generate_image.py └── requirements.txt5.1 编写 SKILL.md 说明文件SKILL.md是 Agent 发现和理解这个技能的入口。YAML frontmatter 中至少要有name和description尽量把触发条件写清楚这样 Agent 才更可能在合适的时候调用它。--- name: image-generator description: 用于生成图片、绘图、制作封面图、生成流程图或根据文本描述创建图像的技能。当用户要求生成图片、制作示意图、创建封面或根据文字描述画图时使用本技能。 --- # 图片生成技能 本技能封装了调用图像生成模型的完整流程负责参数构建、API 请求、文件保存与结果返回。 ## 使用场景 - 根据文本描述生成图片。 - 生成项目封面图、文章配图、海报草图。 - 根据用户指定的宽高比生成图片。 ## 参数说明 | 参数 | 说明 | 是否必填 | | --- | --- | --- | | prompt | 图片内容的自然语言描述 | 是 | | aspect_ratio | 宽高比例如 16:9、1:1 | 否默认 1:1 | | filename | 输出文件名不包含扩展名 | 否默认自动生成 | ## 运行方式 bash python scripts/generate_image.py --prompt 云原生架构图 --aspect-ratio 16:9 --filename cover执行完成后脚本会输出图片的保存路径。注意 SKILL.md 里不应该出现敏感信息、密钥、内部服务地址。它的定位是“给 Agent 看的说明”尽量让内容结构化且无歧义。 ### 5.2 编写生成脚本 scripts/generate_image.py 是真正执行的逻辑。以下示例采用 OpenAI 兼容的图片生成接口这是目前众多服务商普遍遵循的协议。如果你使用的服务不兼容这个协议改造请求函数即可。 python #!/usr/bin/env python3 # 文件路径skills/image-generator/scripts/generate_image.py import argparse import os import time import uuid from pathlib import Path import requests def load_config(): api_key os.environ.get(IMAGE_API_KEY, ) api_base os.environ.get(IMAGE_API_BASE, https://api.example.com/v1) model os.environ.get(IMAGE_API_MODEL, image-gen-default) if not api_key: raise RuntimeError( 未找到 IMAGE_API_KEY 环境变量请先配置模型服务的访问凭证。 ) return api_key, api_base, model def parse_aspect_ratio(aspect_ratio: str): # 简单将 16:9 转为 1024x576若服务商要求不同可自行调整尺寸表 size_map { 1:1: 1024x1024, 16:9: 1024x576, 9:16: 576x1024, 4:3: 1024x768, 3:4: 768x1024, } return size_map.get(aspect_ratio, 1024x1024) def generate_image(prompt, aspect_ratio, filename, output_diroutputs): api_key, api_base, model load_config() size parse_aspect_ratio(aspect_ratio) output_path Path(output_dir) output_path.mkdir(parentsTrue, exist_okTrue) if not filename: filename fimage-{int(time.time())}-{uuid.uuid4().hex[:6]} headers { Authorization: fBearer {api_key}, Content-Type: application/json, } payload { model: model, prompt: prompt, size: size, n: 1, } # 很多服务商将图片生成接口放在 /images/generations具体以官方文档为准 url f{api_base}/images/generations resp requests.post(url, jsonpayload, headersheaders, timeout120) resp.raise_for_status() data resp.json() # 解析返回结果两种常见格式b64_json 或 url if data in data and data[data]: first data[data][0] if b64_json in first: import base64 img_bytes base64.b64decode(first[b64_json]) file_path output_path / f{filename}.png file_path.write_bytes(img_bytes) return str(file_path) if url in first: img_url first[url] file_path output_path / f{filename}.png img_resp requests.get(img_url, timeout60) img_resp.raise_for_status() file_path.write_bytes(img_resp.content) return str(file_path) raise RuntimeError(f无法从响应中解析图片数据{data}) def main(): parser argparse.ArgumentParser(description图片生成 Skill 脚本) parser.add_argument(--prompt, requiredTrue, help图片内容描述) parser.add_argument(--aspect-ratio, default1:1, help宽高比例如 16:9) parser.add_argument(--filename, default, help输出文件名) parser.add_argument(--output-dir, defaultoutputs, help输出目录) args parser.parse_args() try: path generate_image( promptargs.prompt, aspect_ratioargs.aspect_ratio, filenameargs.filename, output_dirargs.output_dir, ) print(f图片已生成{path}) except Exception as exc: # 统一捕获异常方便 Agent 将错误信息返回给用户 print(f生成失败{exc}) raise if __name__ __main__: main()这段代码的关键设计有三点。第一通过环境变量读取模型配置脚本本身不保存任何服务商凭证降低了密钥泄露风险。第二对 API 响应做了两种常见格式的兼容处理b64_json和url。绝大多数在线生成接口至少支持其中一种脚本能自动识别。第三输出文件统一落到outputs目录文件名支持手动指定也支持自动生成。自动生成时加上了时间戳和随机后缀避免重名覆盖。5.3 编写依赖文件scripts/requirements.txt内容如下requests2.31.05.4 在需求中切换本地 ComfyUI 方案如果你的图片生成服务是本地 ComfyUI那么SKILL.md里的运行方式可以做另一套演示示意请求如何提交到本地接口。注意ComfyUI 的接口路径和请求结构不同这里只给思路不绑定某个具体版本# 示例向本地 ComfyUI 提交生成任务 # 文件路径skills/image-generator/scripts/generate_image_comfyui.py import json from pathlib import Path import requests COMFYUI_BASE http://127.0.0.1:8188 def submit_workflow(workflow: dict) - str: # POST /prompt 是 ComfyUI 的常见接口实际以部署版本文档为准 resp requests.post(f{COMFYUI_BASE}/prompt, json{prompt: workflow}) resp.raise_for_status() return resp.json().get(prompt_id) def poll_output(prompt_id: str, output_dir: str, timeout: int 120) - str: # 轮询 /history/{prompt_id} 获取输出文件信息 deadline time.time() timeout while time.time() deadline: history_resp requests.get(f{COMFYUI_BASE}/history/{prompt_id}) history_resp.raise_for_status() history history_resp.json() if prompt_id in history: outputs history[prompt_id].get(outputs, {}) for node_output in outputs.values(): if images in node_output: for image in node_output[images]: return f{output_dir}/{image[filename]} time.sleep(2) raise TimeoutError(等待 ComfyUI 生成超时) if __name__ __main__: # workflow 需要提前设计好这里只给出调用框架 prompt_id submit_workflow({}) print(poll_output(prompt_id, outputs))这个示例的价值在于告诉你即使走本地方案Skill 的封装方式依然不变变的只是脚本内部的请求逻辑。这也是为什么我反复强调“Skill 是流程标准化单元”它和具体模型 API 解耦。6. 从 GitHub 获取现成 Skill安装方法与避坑指南自己从零写一个 Skill 是基本功但在实际开发中更多时候你会直接复用 GitHub 上的现成技能。GitHub 上的 Skill 项目质量参差不齐有很规范的也有很粗糙的所以这几个判断标准要记住。6.1 识别一个值得安装的 Skill 项目看一个 Skill 项目是否靠谱从三个地方看仓库目录结构是否包含SKILL.md或等价的说明文件。脚本是否有明确的依赖声明例如requirements.txt、package.json。是否在 README 里写清楚了支持的 Agent 类型和运行环境。如果这三个都没有基本可以判断是临时写的脚本不建议直接装进生产环境。6.2 通用安装步骤无论你在 GitHub 上找到什么 Skill安装步骤通常都可以抽象成四步# 1. 克隆仓库到本地 git clone https://github.com/your-name/awesome-skill.git # 2. 进入 Skill 目录查看目录结构 cd awesome-skill ls -la # 3. 将 Skill 目录复制到 Agent 的 skills 目录 mkdir -p ~/.claude/skills cp -r image-generator ~/.claude/skills/ # 4. 如果是 Python 类 Skill安装依赖 pip install -r ~/.claude/skills/image-generator/scripts/requirements.txt如果你使用的是 Codex、OpenCode 等不同工具目录位置会有差异但“复制到技能目录”这个核心动作是不变的。6.3 关于 GitHub 访问不稳定的应对进入 2025 年之后GitHub 部分区域的访问稳定性确实有所波动这已经不是技术圈的秘密。很多开发者第一反应是找各种加速方式但这会引入不必要的安全风险。更稳妥的方案是使用 GitHub 官方提供的镜像站点例如https://github.com.cnpmjs.org这类社区镜像或者https://raw.gitmirror.com用于单个文件下载。当仓库不大时直接在页面上下载 ZIP 压缩包。如果频繁拉取某个仓库可以在 Git 里配置代理但前提是你有合法合规的网络通道。这里不展开重点强调的是不要在来历不明的网站下载所谓的“GitHub 加速器”或压缩包。另外从热点里的gaoshu705/qzonearchive这个项目能看出GitHub 上始终有各种个人开发者维护的实用工具。这类仓库往往体积不大下载时一般不需要走复杂的镜像流程直接看 Releases 页面或者git clone --depth 1就够了。6.4 安装第三方 Skill 后必须做的检查第三方 Skill 安装完成后不要立刻投入生产。你需要检查是否有脚本会自动读取环境变量里的密钥并上传到未知服务器。是否有依赖包存在明显版本兼容风险。是否有调用外部接口且没有声明网络权限。一个不可信的 Skill 脚本本质上就是一段任意代码。它在你的机器上拥有和你相同的权限。所以安装前先通读一遍SKILL.md和入口脚本是最基本的安全底线。7. 运行结果与效果验证完成上面的 Skill 编写后下面的命令可以跑通整个链路。7.1 配置环境变量export IMAGE_API_KEY你的服务商密钥 export IMAGE_API_BASEhttps://api.example.com/v1 export IMAGE_API_MODELimage-gen-model7.2 运行生成脚本cd skills/image-generator python scripts/generate_image.py \ --prompt A clean project cover with cloud native architecture, blue theme \ --aspect-ratio 16:9 \ --filename project-cover7.3 预期输出如果一切正常终端会输出类似下面的内容图片已生成outputs/project-cover.png此时你可以在脚本目录下的outputs文件夹中找到生成的图片文件。用图像查看工具打开确认内容是否符合预期。7.4 验证清单我建议用一个清单来判断本次运行是否真正成功检查项预期结果终端输出显示已生成路径无堆栈异常文件存在性outputs/project-cover.png存在且大小非 0图片宽高比接近 16:9例如 1024x576 或同比例内容相关性图片内容与 prompt 描述匹配无冗余文件目录中没有意外生成的临时文件如果文件生成成功但图片内容不对那说明 prompt 还需要优化这是模型层的问题不是 Skill 的问题。如果文件根本没生成优先看异常信息里的请求报错通常问题出在 API 地址、密钥或模型名。8. 常见问题与排查思路我整理了几个实际使用图片生成 Skill 时最常遇到的问题按概率从高到低列出。问题现象可能原因排查方式解决方案脚本报404 Not FoundIMAGE_API_BASE路径配置错误接口路径不是/images/generations查看服务商 API 文档对比请求 URL修改api_base或脚本中的 URL 拼接逻辑脚本报401 UnauthorizedAPI Key 错误或已过期检查环境变量是否生效用echo $IMAGE_API_KEY验证重新生成密钥或检查环境变量导出语句图片生成成功但尺寸不对服务商不识别size参数强制返回默认尺寸查看返回的图片元数据根据服务商文档修改size字段格式ComfyUI 脚本提交后一直超时Workflow 本身有误或输出节点配置不对手动在 ComfyUI 界面提交同一 workflow 观察报错修正 workflow再调整轮询逻辑输出文件为空或打不开下载了损坏的图片字节流检查 HTTP 响应状态码和响应大小对 URL 下载增加重试和内容校验Agent 不调用这个 Skilldescription描述与实际任务不匹配看 Agent 日志确认是否加载了 Skill改写description增加触发关键词这里的核心经验是先确认请求层是否正常再检查文件层最后再怀疑模型本身。很多问题从表面看是“AI 画得不好”实际是接口参数没对齐。9. 最佳实践与工程建议图片生成 Skill 写起来简单但要在生产环境里长期稳定使用需要建立几个习惯。9.1 Skill 设计规范第一命名要可预测。Skill 目录名用kebab-case比如image-generator、drawio-helper不要用generate_images_final_v2这种名字。Agent 是通过名字和描述来匹配任务的清晰命名能显著提高调用准确率。第二参数要收敛。一个 Skill 的参数控制在 3 到 6 个以内最好。参数越多Agent 的解析就越容易出错。图片生成这个场景里prompt、aspect_ratio、filename三个参数通常已经够用。第三输出要稳定。不要让脚本把图片输出到当前目录而是统一进outputs目录。这样 Agent 能稳定地告诉用户“文件在哪个位置”也方便后续接入 CI/CD 或消息通知。9.2 密钥与权限管理永远不要在SKILL.md或脚本里写死密钥。图片生成 API 的密钥应该通过环境变量注入并且在团队协作时把.env.example作为模板而不是把.env提交进 Git 仓库。如果 Skill 被多个同事使用建议单独建立一个服务账号给这个账号设置调用额度上限。这既是为了安全也是为了避免某个人误操作把团队月配额耗尽。9.3 与合规使用有关的重要边界图片生成领域在 2025 年特别需要强调一个点无论使用在线 API 还是本地模型都不要尝试绕过平台的内容审核机制。热词中出现过一些包含明显绕审核意图的搜索词比如“无审核生成图片”之类这类需求不仅是服务条款明确禁止的而且极容易给自己带来法律风险。更实际的问题在于很多模型服务商对生成内容有使用限制。你在构建图片生成 Skill 时应该在SKILL.md里加入一条备注“本技能只用于合法合规的图片生成场景生成内容不得用于侵权、欺诈、虚假信息传播等用途。”这行文字不只是在程序里加一个保险更是给后续维护者一个明确边界。9.4 版本管理与回滚Skill 也是代码建议纳入 Git 管理。每次改动SKILL.md或脚本建立对应的 commit 记录。如果某个版本的 prompt 处理逻辑导致输出质量下降可以快速回滚到上一个版本。当一个 Skill 在团队内部稳定运行后可以给它打 tag例如v1.0.0。以后其他项目引用时直接指定版本号避免“昨天还能跑今天不知道怎么改坏了”的尴尬。9.5 从图片生成到通用 Skill 方法论图片生成 Skill 只是 Skill 体系里的一个切片。你完全可以把同样思路迁移到其他领域比如根据工程需求生成 Draw.io 流程图。根据项目代码自动生成依赖关系图。根据周报文本生成可视化统计图表。根据测试报告生成 HTML 摘要页面。每个场景都是同样的结构写一个描述文件定义参数写一个负责调用的脚本约定输出位置。这套方法论一旦建立Agent 能做的事就远远超过对话了。10. 写在最后总结一下这次关于图片生成 Skill 的梳理。从 GitHub 一周热点看Skill 生态正在快速膨胀图片生成只是其中最容易被感知的一个应用场景。真正重要的不是“某个 Skill 有多强”而是 Skill 这个机制给了所有开发者一套统一的方法论把完成任务的流程沉淀成文件让 Agent 在需要的时候自动发现、自动调用。如果你是一个普通开发者我建议你接下来做三件事。第一把一个现成的图片生成 Skill 装进你的 Agent 环境跑通一次完整流程。第二试着改成你常用的模型服务体会一下“切换模型提供商”需要改哪里、不需要改哪里。第三找一个你日常重复次数最多的任务尝试用同样的 SKILL.md 脚本结构封装成一个自己的 Skill。图片生成的技术底座还会不断变化但“把能力标准化、可复用、可共享”这个思路在很长一段时间内不会过时。希望这篇文章能帮你省下一点摸索的时间。 图片生成Skill开发实战：从零编写到工程化落地
如果你最近在 GitHub 上翻 AI 项目大概率会产生一个感觉好像一夜之间所有东西都在聊Skill。从workbuddy skill这种工作流管理技能到taste skill这种个人偏好类的技能再到codex skill、claude code skill、opencode skill几乎每个热门 Agent 工具都在用自己的方式支持 Skill。而图片生成恰恰是 Skill 生态里最热闹、也最容易让人误解的领域。很多人以为“图片生成 Skill”就是给 AI 一个提示词然后让它出图。这个理解只对了一半。真正值得关注的是过去你要完成一张可用图片的产出需要经历注册模型服务、调 API、调参数、写提示词、过后处理、再落入项目目录这一整套流程。而 Skill 的出现把这条链路变成了一次“自然语言调用”。这篇文章我想围绕一个点展开Skill 解决的不是“AI 能不能画图”而是“AI 生成图片这个动作是否标准化、可复用、可沉淀到团队”。我会从零写一个图片生成 Skill也会聊一聊如何在 GitHub 上找到、安装、避坑第三方 Skill最后给出一套可以直接套用的工程规范。1. 这篇文章真正要解决的问题先抛一个场景。假设你是一个独立开发者正在给开源项目写 README需要一张简洁的项目架构图。你打开一个绘图工具拖了二十分钟画完发现风格和 README 整体不搭又改了一轮。这种时候你会不会想如果 AI 能帮我把这件事做掉就好了。再换一个场景。你是公司里的算法工程师给业务方做数据可视化图表。每次需求都要写一段 Python 脚本、调中文字体、设置配色、输出 PNG。脚本在不同机器上跑出来的效果还不一样。这时候你需要的不是“再调一次参数”而是一个能反复使用、不会偷偷改你风格的出图流程。这两个场景背后是同一个问题图片生成的技术门槛已经被模型服务商降得很低但“工程化门槛”却一直没人解决。你需要懂 API、懂参数、懂提示词、懂后处理还要把结果保存到正确的位置。Skill 就是冲着这个工程化门槛来的。我把“图片生成 Skill”的定义说清楚它是一个包含说明文件、脚本、依赖清单和元信息的小型技能包能让 Agent 在理解任务之后自动决定调用哪个脚本、传什么参数、把结果放到哪里。换句话说它不是“一个会画画的 AI”而是一个“按规范完成出图任务的自动化单元”。这篇文章适合三类读者第一已经入手 Claude Code、Codex、OpenCode 等 Agent 工具的开发者第二正在做 AI 产品、想给 Agent 增加图像能力的开发者第三被图片生成工具链折腾过、想找一套可复用方案的普通技术用户。读完你至少能写一个自己的图片生成 Skill并能判断 GitHub 上哪些 Skill 值得装、哪些不适合装。2. Skill 是什么与插件、自定义工具的核心区别Agent Skill 的概念这两年迅速兴起但很多人的理解停留在“插件换了个名字”。这个理解不准确。插件通常意味着一个独立的系统组件它运行在自己的进程里提供一组外部可见的能力。而 Skill 更接近“Agent 的说明书 脚本集”。它不是一个独立服务而是一套让 Agent 在面对某类任务时知道“该怎么做”的知识包。它的核心是两样东西说明文件描述这个技能在什么场景下使用、有哪些参数、内部流程是什么。可执行脚本真正干活的部分用 Python、Node.js 或者 Shell 脚本实现。对比表格更能说明问题维度传统插件Agent Skill运行方式独立进程或服务由 Agent 按需调用脚本核心能力对外提供 API 接口指导 Agent 完成任务流程可复制性需要安装到环境中一个目录即可分发维护方式插件框架升级时跟随升级纯脚本 文档基本不依赖框架开发者心智面向框架面向任务为什么选“目录 说明文件 脚本”这种看似简单的结构因为它把“能力”和“流程”解耦了。Agent 本身负责理解需求和拆解任务Skill 只负责提供某个环节的标准化操作。这个设计的直接收益是你可以把任意一个成熟的工作流封装成 Skill共享给团队或者发布到 GitHub 上让别人复用。从 GitHub 热点项目来看目前主流 Agent 都已经支持类似机制。Anthropic 的 Claude Code 有~/.claude/skills目录约定OpenAI 的 Codex 也在引入技能机制OpenCode 等开源命令行工具同样有自己的技能加载方式。这些工具虽然 API 不同但底层思路是高度一致的把能力描述成 Markdown 脚本放进约定目录Agent 自动发现并使用。这就是为什么我用“一个 Skill 搞定图片生成”来概括这次趋势——真正搞定的不是模型而是流程。3. 图片生成 Skill 的核心原理与典型工作流一个图片生成 Skill 内部到底发生了什么我用一个最小流程来拆解。当你在 Agent 里说“帮我生成一张 16:9 的项目封面图主题是云原生架构”时Agent 会经历以下步骤在技能目录中找到图片生成 Skill 的说明文件确认它能否处理这个任务。读取说明文件里的参数定义将“16:9”“云原生架构”映射到生成脚本的参数。执行封装好的脚本脚本负责调用图像生成模型的 API。脚本收到图片结果后按约定格式保存到项目目录或指定位置。将保存路径返回给 AgentAgent 再汇报给你。这个流程里真正关键的设计点是第 3 步。脚本不应该只做一次简单的 API 请求它应该具备参数校验、错误重试、文件命名、格式转换等基础能力。好的图片生成 Skill 和普通脚本的差距往往就体现在这些边界处理上。从模型服务层面看目前图片生成 API 主要分为两大类。一类是服务商提供的在线生成接口优点是开箱即用缺点是依赖网络和配额另一类是本地模型方案例如本地部署的 Stable Diffusion 及 ComfyUI优点是无外部依赖、可控性强缺点是需要 GPU 资源和环境配置。一个成熟的图片生成 Skill应该能通过配置项在这两种方案之间切换而不是写死某一种。网络热词里经常出现“ComfyUI 生成图片时预览窗口看不到图”这其实也属于工程化问题——模型已经把图生成了但前端预览没刷新。这类问题靠调 UI 或者换浏览器不一定根治正确的做法是在自动化脚本里直接轮询输出目录检测到新文件就返回。这也是为什么把图片生成封装成 Skill 之后体验更稳定的原因你不再依赖某个图形界面的状态而是直接和文件系统与 API 交互。4. 环境准备与前置条件实际动手前需要确认环境。我不会把版本号写死因为 Skill 生态变化太快本文演示的是通用思路。4.1 基础环境建议准备以下环境操作系统Linux、macOS 或 WindowsWSL 也可以。Python 3.9 以上包含pip命令。Node.js 18 以上部分 Skill 用 TypeScript 编写时需要。Git。如果你的机器上还没装 Python可以用系统包管理器安装。macOS 可以用brew install python3Ubuntu 可以用apt install python3 python3-pip。4.2 Agent 工具图片生成 Skill 最终要接进某个 Agent。目前推荐先选定一个工具避免同时维护多套配置。如果你已经在用 Claude Code直接使用~/.claude/skills目录。如果你在用 Codex参照官方文档启用技能目录。如果你偏好开源命令行工具OpenCode 等工具也有对应的 skills 目录约定。无论选哪个重点是理解一个原则Skill 的本质是目录、说明文件、脚本不绑定特定 Agent 的内部 API。这意味着同一个图片生成 Skill 理论上可以在多个工具之间复用只是目录位置不同。4.3 图像模型的访问凭证图片生成 Skill 总归要调用模型。准备一个可用的 API Token并配置到环境变量里。我建议使用形如IMAGE_API_KEY、IMAGE_API_BASE、IMAGE_API_MODEL的环境变量名后续脚本也从环境变量读取不要把密钥写进 SKILL.md 或脚本文件。如果你选择本地模型方案那需要确认你的服务已经在本机启动并开放了 HTTP 端口。以 ComfyUI 为例官方提供了 REST API但接口路径和请求格式以你部署版本的文档为准。4.4 目录规划建议我建议在项目根目录建一个skills目录或者用 Agent 约定的全局技能目录。下面所有示例都以本地项目内的skills/image-generator目录来说明路径清晰方便对照。5. 从零写一个图片生成 Skill完整代码实现这一节是本篇文章的核心实操部分。我们按三个文件来组织一个最小可用的图片生成 Skillskills/image-generator/ ├── SKILL.md └── scripts/ ├── generate_image.py └── requirements.txt5.1 编写 SKILL.md 说明文件SKILL.md是 Agent 发现和理解这个技能的入口。YAML frontmatter 中至少要有name和description尽量把触发条件写清楚这样 Agent 才更可能在合适的时候调用它。--- name: image-generator description: 用于生成图片、绘图、制作封面图、生成流程图或根据文本描述创建图像的技能。当用户要求生成图片、制作示意图、创建封面或根据文字描述画图时使用本技能。 --- # 图片生成技能 本技能封装了调用图像生成模型的完整流程负责参数构建、API 请求、文件保存与结果返回。 ## 使用场景 - 根据文本描述生成图片。 - 生成项目封面图、文章配图、海报草图。 - 根据用户指定的宽高比生成图片。 ## 参数说明 | 参数 | 说明 | 是否必填 | | --- | --- | --- | | prompt | 图片内容的自然语言描述 | 是 | | aspect_ratio | 宽高比例如 16:9、1:1 | 否默认 1:1 | | filename | 输出文件名不包含扩展名 | 否默认自动生成 | ## 运行方式 bash python scripts/generate_image.py --prompt 云原生架构图 --aspect-ratio 16:9 --filename cover执行完成后脚本会输出图片的保存路径。注意 SKILL.md 里不应该出现敏感信息、密钥、内部服务地址。它的定位是“给 Agent 看的说明”尽量让内容结构化且无歧义。 ### 5.2 编写生成脚本 scripts/generate_image.py 是真正执行的逻辑。以下示例采用 OpenAI 兼容的图片生成接口这是目前众多服务商普遍遵循的协议。如果你使用的服务不兼容这个协议改造请求函数即可。 python #!/usr/bin/env python3 # 文件路径skills/image-generator/scripts/generate_image.py import argparse import os import time import uuid from pathlib import Path import requests def load_config(): api_key os.environ.get(IMAGE_API_KEY, ) api_base os.environ.get(IMAGE_API_BASE, https://api.example.com/v1) model os.environ.get(IMAGE_API_MODEL, image-gen-default) if not api_key: raise RuntimeError( 未找到 IMAGE_API_KEY 环境变量请先配置模型服务的访问凭证。 ) return api_key, api_base, model def parse_aspect_ratio(aspect_ratio: str): # 简单将 16:9 转为 1024x576若服务商要求不同可自行调整尺寸表 size_map { 1:1: 1024x1024, 16:9: 1024x576, 9:16: 576x1024, 4:3: 1024x768, 3:4: 768x1024, } return size_map.get(aspect_ratio, 1024x1024) def generate_image(prompt, aspect_ratio, filename, output_diroutputs): api_key, api_base, model load_config() size parse_aspect_ratio(aspect_ratio) output_path Path(output_dir) output_path.mkdir(parentsTrue, exist_okTrue) if not filename: filename fimage-{int(time.time())}-{uuid.uuid4().hex[:6]} headers { Authorization: fBearer {api_key}, Content-Type: application/json, } payload { model: model, prompt: prompt, size: size, n: 1, } # 很多服务商将图片生成接口放在 /images/generations具体以官方文档为准 url f{api_base}/images/generations resp requests.post(url, jsonpayload, headersheaders, timeout120) resp.raise_for_status() data resp.json() # 解析返回结果两种常见格式b64_json 或 url if data in data and data[data]: first data[data][0] if b64_json in first: import base64 img_bytes base64.b64decode(first[b64_json]) file_path output_path / f{filename}.png file_path.write_bytes(img_bytes) return str(file_path) if url in first: img_url first[url] file_path output_path / f{filename}.png img_resp requests.get(img_url, timeout60) img_resp.raise_for_status() file_path.write_bytes(img_resp.content) return str(file_path) raise RuntimeError(f无法从响应中解析图片数据{data}) def main(): parser argparse.ArgumentParser(description图片生成 Skill 脚本) parser.add_argument(--prompt, requiredTrue, help图片内容描述) parser.add_argument(--aspect-ratio, default1:1, help宽高比例如 16:9) parser.add_argument(--filename, default, help输出文件名) parser.add_argument(--output-dir, defaultoutputs, help输出目录) args parser.parse_args() try: path generate_image( promptargs.prompt, aspect_ratioargs.aspect_ratio, filenameargs.filename, output_dirargs.output_dir, ) print(f图片已生成{path}) except Exception as exc: # 统一捕获异常方便 Agent 将错误信息返回给用户 print(f生成失败{exc}) raise if __name__ __main__: main()这段代码的关键设计有三点。第一通过环境变量读取模型配置脚本本身不保存任何服务商凭证降低了密钥泄露风险。第二对 API 响应做了两种常见格式的兼容处理b64_json和url。绝大多数在线生成接口至少支持其中一种脚本能自动识别。第三输出文件统一落到outputs目录文件名支持手动指定也支持自动生成。自动生成时加上了时间戳和随机后缀避免重名覆盖。5.3 编写依赖文件scripts/requirements.txt内容如下requests2.31.05.4 在需求中切换本地 ComfyUI 方案如果你的图片生成服务是本地 ComfyUI那么SKILL.md里的运行方式可以做另一套演示示意请求如何提交到本地接口。注意ComfyUI 的接口路径和请求结构不同这里只给思路不绑定某个具体版本# 示例向本地 ComfyUI 提交生成任务 # 文件路径skills/image-generator/scripts/generate_image_comfyui.py import json from pathlib import Path import requests COMFYUI_BASE http://127.0.0.1:8188 def submit_workflow(workflow: dict) - str: # POST /prompt 是 ComfyUI 的常见接口实际以部署版本文档为准 resp requests.post(f{COMFYUI_BASE}/prompt, json{prompt: workflow}) resp.raise_for_status() return resp.json().get(prompt_id) def poll_output(prompt_id: str, output_dir: str, timeout: int 120) - str: # 轮询 /history/{prompt_id} 获取输出文件信息 deadline time.time() timeout while time.time() deadline: history_resp requests.get(f{COMFYUI_BASE}/history/{prompt_id}) history_resp.raise_for_status() history history_resp.json() if prompt_id in history: outputs history[prompt_id].get(outputs, {}) for node_output in outputs.values(): if images in node_output: for image in node_output[images]: return f{output_dir}/{image[filename]} time.sleep(2) raise TimeoutError(等待 ComfyUI 生成超时) if __name__ __main__: # workflow 需要提前设计好这里只给出调用框架 prompt_id submit_workflow({}) print(poll_output(prompt_id, outputs))这个示例的价值在于告诉你即使走本地方案Skill 的封装方式依然不变变的只是脚本内部的请求逻辑。这也是为什么我反复强调“Skill 是流程标准化单元”它和具体模型 API 解耦。6. 从 GitHub 获取现成 Skill安装方法与避坑指南自己从零写一个 Skill 是基本功但在实际开发中更多时候你会直接复用 GitHub 上的现成技能。GitHub 上的 Skill 项目质量参差不齐有很规范的也有很粗糙的所以这几个判断标准要记住。6.1 识别一个值得安装的 Skill 项目看一个 Skill 项目是否靠谱从三个地方看仓库目录结构是否包含SKILL.md或等价的说明文件。脚本是否有明确的依赖声明例如requirements.txt、package.json。是否在 README 里写清楚了支持的 Agent 类型和运行环境。如果这三个都没有基本可以判断是临时写的脚本不建议直接装进生产环境。6.2 通用安装步骤无论你在 GitHub 上找到什么 Skill安装步骤通常都可以抽象成四步# 1. 克隆仓库到本地 git clone https://github.com/your-name/awesome-skill.git # 2. 进入 Skill 目录查看目录结构 cd awesome-skill ls -la # 3. 将 Skill 目录复制到 Agent 的 skills 目录 mkdir -p ~/.claude/skills cp -r image-generator ~/.claude/skills/ # 4. 如果是 Python 类 Skill安装依赖 pip install -r ~/.claude/skills/image-generator/scripts/requirements.txt如果你使用的是 Codex、OpenCode 等不同工具目录位置会有差异但“复制到技能目录”这个核心动作是不变的。6.3 关于 GitHub 访问不稳定的应对进入 2025 年之后GitHub 部分区域的访问稳定性确实有所波动这已经不是技术圈的秘密。很多开发者第一反应是找各种加速方式但这会引入不必要的安全风险。更稳妥的方案是使用 GitHub 官方提供的镜像站点例如https://github.com.cnpmjs.org这类社区镜像或者https://raw.gitmirror.com用于单个文件下载。当仓库不大时直接在页面上下载 ZIP 压缩包。如果频繁拉取某个仓库可以在 Git 里配置代理但前提是你有合法合规的网络通道。这里不展开重点强调的是不要在来历不明的网站下载所谓的“GitHub 加速器”或压缩包。另外从热点里的gaoshu705/qzonearchive这个项目能看出GitHub 上始终有各种个人开发者维护的实用工具。这类仓库往往体积不大下载时一般不需要走复杂的镜像流程直接看 Releases 页面或者git clone --depth 1就够了。6.4 安装第三方 Skill 后必须做的检查第三方 Skill 安装完成后不要立刻投入生产。你需要检查是否有脚本会自动读取环境变量里的密钥并上传到未知服务器。是否有依赖包存在明显版本兼容风险。是否有调用外部接口且没有声明网络权限。一个不可信的 Skill 脚本本质上就是一段任意代码。它在你的机器上拥有和你相同的权限。所以安装前先通读一遍SKILL.md和入口脚本是最基本的安全底线。7. 运行结果与效果验证完成上面的 Skill 编写后下面的命令可以跑通整个链路。7.1 配置环境变量export IMAGE_API_KEY你的服务商密钥 export IMAGE_API_BASEhttps://api.example.com/v1 export IMAGE_API_MODELimage-gen-model7.2 运行生成脚本cd skills/image-generator python scripts/generate_image.py \ --prompt A clean project cover with cloud native architecture, blue theme \ --aspect-ratio 16:9 \ --filename project-cover7.3 预期输出如果一切正常终端会输出类似下面的内容图片已生成outputs/project-cover.png此时你可以在脚本目录下的outputs文件夹中找到生成的图片文件。用图像查看工具打开确认内容是否符合预期。7.4 验证清单我建议用一个清单来判断本次运行是否真正成功检查项预期结果终端输出显示已生成路径无堆栈异常文件存在性outputs/project-cover.png存在且大小非 0图片宽高比接近 16:9例如 1024x576 或同比例内容相关性图片内容与 prompt 描述匹配无冗余文件目录中没有意外生成的临时文件如果文件生成成功但图片内容不对那说明 prompt 还需要优化这是模型层的问题不是 Skill 的问题。如果文件根本没生成优先看异常信息里的请求报错通常问题出在 API 地址、密钥或模型名。8. 常见问题与排查思路我整理了几个实际使用图片生成 Skill 时最常遇到的问题按概率从高到低列出。问题现象可能原因排查方式解决方案脚本报404 Not FoundIMAGE_API_BASE路径配置错误接口路径不是/images/generations查看服务商 API 文档对比请求 URL修改api_base或脚本中的 URL 拼接逻辑脚本报401 UnauthorizedAPI Key 错误或已过期检查环境变量是否生效用echo $IMAGE_API_KEY验证重新生成密钥或检查环境变量导出语句图片生成成功但尺寸不对服务商不识别size参数强制返回默认尺寸查看返回的图片元数据根据服务商文档修改size字段格式ComfyUI 脚本提交后一直超时Workflow 本身有误或输出节点配置不对手动在 ComfyUI 界面提交同一 workflow 观察报错修正 workflow再调整轮询逻辑输出文件为空或打不开下载了损坏的图片字节流检查 HTTP 响应状态码和响应大小对 URL 下载增加重试和内容校验Agent 不调用这个 Skilldescription描述与实际任务不匹配看 Agent 日志确认是否加载了 Skill改写description增加触发关键词这里的核心经验是先确认请求层是否正常再检查文件层最后再怀疑模型本身。很多问题从表面看是“AI 画得不好”实际是接口参数没对齐。9. 最佳实践与工程建议图片生成 Skill 写起来简单但要在生产环境里长期稳定使用需要建立几个习惯。9.1 Skill 设计规范第一命名要可预测。Skill 目录名用kebab-case比如image-generator、drawio-helper不要用generate_images_final_v2这种名字。Agent 是通过名字和描述来匹配任务的清晰命名能显著提高调用准确率。第二参数要收敛。一个 Skill 的参数控制在 3 到 6 个以内最好。参数越多Agent 的解析就越容易出错。图片生成这个场景里prompt、aspect_ratio、filename三个参数通常已经够用。第三输出要稳定。不要让脚本把图片输出到当前目录而是统一进outputs目录。这样 Agent 能稳定地告诉用户“文件在哪个位置”也方便后续接入 CI/CD 或消息通知。9.2 密钥与权限管理永远不要在SKILL.md或脚本里写死密钥。图片生成 API 的密钥应该通过环境变量注入并且在团队协作时把.env.example作为模板而不是把.env提交进 Git 仓库。如果 Skill 被多个同事使用建议单独建立一个服务账号给这个账号设置调用额度上限。这既是为了安全也是为了避免某个人误操作把团队月配额耗尽。9.3 与合规使用有关的重要边界图片生成领域在 2025 年特别需要强调一个点无论使用在线 API 还是本地模型都不要尝试绕过平台的内容审核机制。热词中出现过一些包含明显绕审核意图的搜索词比如“无审核生成图片”之类这类需求不仅是服务条款明确禁止的而且极容易给自己带来法律风险。更实际的问题在于很多模型服务商对生成内容有使用限制。你在构建图片生成 Skill 时应该在SKILL.md里加入一条备注“本技能只用于合法合规的图片生成场景生成内容不得用于侵权、欺诈、虚假信息传播等用途。”这行文字不只是在程序里加一个保险更是给后续维护者一个明确边界。9.4 版本管理与回滚Skill 也是代码建议纳入 Git 管理。每次改动SKILL.md或脚本建立对应的 commit 记录。如果某个版本的 prompt 处理逻辑导致输出质量下降可以快速回滚到上一个版本。当一个 Skill 在团队内部稳定运行后可以给它打 tag例如v1.0.0。以后其他项目引用时直接指定版本号避免“昨天还能跑今天不知道怎么改坏了”的尴尬。9.5 从图片生成到通用 Skill 方法论图片生成 Skill 只是 Skill 体系里的一个切片。你完全可以把同样思路迁移到其他领域比如根据工程需求生成 Draw.io 流程图。根据项目代码自动生成依赖关系图。根据周报文本生成可视化统计图表。根据测试报告生成 HTML 摘要页面。每个场景都是同样的结构写一个描述文件定义参数写一个负责调用的脚本约定输出位置。这套方法论一旦建立Agent 能做的事就远远超过对话了。10. 写在最后总结一下这次关于图片生成 Skill 的梳理。从 GitHub 一周热点看Skill 生态正在快速膨胀图片生成只是其中最容易被感知的一个应用场景。真正重要的不是“某个 Skill 有多强”而是 Skill 这个机制给了所有开发者一套统一的方法论把完成任务的流程沉淀成文件让 Agent 在需要的时候自动发现、自动调用。如果你是一个普通开发者我建议你接下来做三件事。第一把一个现成的图片生成 Skill 装进你的 Agent 环境跑通一次完整流程。第二试着改成你常用的模型服务体会一下“切换模型提供商”需要改哪里、不需要改哪里。第三找一个你日常重复次数最多的任务尝试用同样的 SKILL.md 脚本结构封装成一个自己的 Skill。图片生成的技术底座还会不断变化但“把能力标准化、可复用、可共享”这个思路在很长一段时间内不会过时。希望这篇文章能帮你省下一点摸索的时间。