最近 GitHub 热榜上Skill 成了绕不开的关键词。起因是 Claude Code、Codex CLI、opencode 这类 AI 编程助手陆续推出 Skills 机制让开发者可以把一套固定的操作流程打包成“指令 脚本”交给 AI 在合适的场景下自动执行。相比传统插件Skill 更轻、更灵活尤其适合图片生成这种流程固定、参数繁多的场景。这篇文章会从 Skill 的原理讲起然后手把手实现一个图片生成 Skill覆盖云端 API 接入、本地 ComfyUI、高清放大、常见报错排查等完整链路读完就能在自己的环境里直接复刻。1. 背景GitHub 热榜上的 Skill 到底是什么1.1 Skill 不是插件而是一套“指令 脚本”的打包体很多人第一次看到 Skill会拿它和 IDE 插件、浏览器插件做类比。插件通常是一套完整的运行时程序有独立的 UI、权限模型和生命周期Skill 则要轻得多。一个最小可用的 Skill 就是一个文件夹里面放一个 SKILL.md 文件。SKILL.md 用 Markdown 写成头部有一段 YAML 格式的 frontmatter记录 name 和 description正文是一段面向 AI 的操作指令。当你在 AI 编程助手里输入“帮我画一张图”时模型会先扫描已安装 Skill 的 description判断哪个 Skill 和当前任务匹配匹配成功后它会读取对应的 SKILL.md然后按照指示去执行脚本、生成文件、返回结果。这种设计的好处很直接不需要重新训练模型也不需要维护复杂的插件 API只要会写 Markdown 和脚本就能扩展 AI 的能力。GitHub 上大量 Skill 仓库正是靠这个低成本门槛快速积累起来的从数学建模、drawio 绘图到前端 Vue 开发各种方向都有人在做封装图片生成则是其中最典型、也最能直接看到效果的方向之一。1.2 Skill 的通用目录结构大部分支持 Skills 的工具都遵循相近的目录约定下面是一个标准示例image-gen.skill/ ├── SKILL.md # Skill 元信息与执行指令 ├── scripts/ # 可执行脚本 │ ├── generate.py # 图片生成入口 │ └── upscale.py # 高清放大脚本 └── references/ # 参考资料、提示词模板 └── prompts.mdSKILL.md 是唯一必须存在的文件scripts 和 references 都不是强制要求。是否带脚本取决于你要封装的任务复杂度。如果只是告诉 AI“遇到某个场景按某种措辞回答”一个 SKILL.md 就够了但如果涉及调用接口、读写文件、批量处理那就需要通过脚本把不稳定的推理过程变成稳定可复现的代码。1.3 为什么图片生成特别适合做成 Skill图片生成看起来只是“输入一句话、输出一张图”实际落地时远远没那么简单。引擎不统一有人用云端 API有人用本地 Stable Diffusion还有人用 ComfyUI每次都要切换命令和参数。尺寸和比例难控制头像要 1:1海报要 3:4壁纸要 16:9不同平台对尺寸的接受范围不同。清晰度不达标云端生成的 1024×1024 图片在印刷或大屏场景下经常不够用必须做高清放大。提示词质量波动大同样的需求不同措辞出来的效果天差地别需要沉淀一套可复用的提示词模板。把上述流程封装成 Skill 后AI 只需要按 SKILL.md 里的步骤执行先理解需求再调用统一脚本最后检查输出。这个思路比“每次临时敲命令”稳定得多也比“自己写一套完整应用”轻量得多。2. 环境准备与版本说明在动手之前先确认环境。以下只是一个常见示例环境不是唯一选择版本请根据你的实际项目情况调整重点是理解配置思路。组件版本建议用途Python3.9运行图片生成与放大脚本Pillow10.0图片读取、缩放、保存Node.js18部分 AI 编程助手 CLI 依赖ComfyUI最新版本地 Stable Diffusion 生图引擎可选AI 编程助手Claude Code / Codex CLI / opencode加载 Skill 并执行流程如果你是第一次使用 Claude Code 或 Codex CLI建议先完成官方安装流程并确认命令行里能正常启动。Skill 的安装目录会因工具而异本文以 Claude Code 的~/.claude/skills/目录为例其他工具的路径需要查对应官方文档。图片生成脚本用 Python 编写安装 Pillow 即可运行pip install Pillow云端生图需要准备一个 API Key常见做法是设置IMAGE_API_KEY环境变量。如果你只用本地 ComfyUI这一步可以跳过。3. Skill 的核心原理拆解3.1 SKILL.md 的关键字段先看一个最精简的 SKILL.md--- name: image-gen description: 当用户要求生成、绘制、制作图片、头像、海报、封面或者需要把图片放大、调整比例时使用。 --- # 图片生成 Skill 按照本文指令逐步执行图片生成任务。frontmatter 中最重要的字段是description。模型不会在每个对话里都读取所有 SKILL.md 的正文它通常只根据 description 判断“当前任务是否匹配这个 Skill”。所以 description 要尽量写清楚触发场景最好把用户可能表达的关键词都列进去比如“生成”“绘制”“画”“配图”“头像”“海报”。反过来如果 description 写得太泛比如“处理图片相关任务”模型就很容易在不需要的时候误触发。3.2 Skill 是如何被“触发”的整个触发过程可以这样理解用户输入请求。编程助手扫描当前环境中的所有 Skill取到每个 Skill 的名称和 description。模型根据用户意图与 description 做匹配选出最合适的一个或多个 Skill。助手读取选中的 SKILL.md 正文把其中的指令注入当前对话的上下文。助手按指令调用脚本、解析输出最后把结果返回给用户。匹配是否准确取决于 description 写得好不好。这也是为什么 GitHub 上很多 Skill 项目会把 description 写成一段长句子甚至带使用案例本质上就是在帮模型降低“判断错误”的概率。3.3 脚本与参考资料的使用边界Skill 里的脚本应该尽量“小而专”。一个脚本只做一件事参数要完整错误信息要明确。这样 AI 调用时不容易出错即使出错也能根据报错信息自行修正。另外可以把常见的提示词模板、负面词表、缩放参数参考文档放在 references 目录中并在 SKILL.md 里写明“遇到不确定的风格时先查阅 references/prompts.md”。这会显著减少模型自由发挥带来的随机性。本质上Skill 不是把业务逻辑写进 Markdown而是用 Markdown 告诉 AI“什么时候该做什么、调用什么工具、遇到问题怎么处理”。4. 完整实战实现一个图片生成 Skill下面开始完整实战。目标是实现一个同时支持云端 API 和本地 ComfyUI 的图片生成 Skill并附带高清放大能力。4.1 创建 Skill 目录结构打开终端执行以下命令mkdir -p ~/.claude/skills/image-gen/scripts mkdir -p ~/.claude/skills/image-gen/references cd ~/.claude/skills/image-gen如果你用的是 Codex CLI可以把~/.claude/skills换成对应的~/.codex/skills如果使用 opencode则可能放在项目目录下的.opencode/skill/中。路径以你选择的工具官方文档为准本文其余示例中的文件路径保持相对路径即可。4.2 编写 SKILL.md创建/Users/你的用户名/.claude/skills/image-gen/SKILL.mdWindows 下面是对应用户目录内容如下--- name: image-gen description: 当用户要求生成图片、绘制插画、制作头像/海报/封面/配图或者需要调整图片尺寸、比例、清晰度时使用。适合把一句话需求转换成完整生图流程。 --- # 图片生成 Skill ## 任务理解阶段 先确认以下信息如果用户没有明确给出使用合理默认值 - 主体内容画面里有什么 - 风格写实 / 插画 / 3D / 像素 / 水墨等 - 尺寸默认 1024x1024头像用 768x768海报用 768x1024 - 引擎默认 cloud如果用户要求本地生成则使用 comfyui - 输出目录默认 ./output ## 执行步骤 1. 把用户需求整理成完整、清晰的 prompt。 2. 执行生成命令 python scripts/generate.py \ --prompt 图片内容描述 \ --engine cloud \ --width 1024 \ --height 1024 \ --output output/demo.png 3. 生成成功后检查输出文件是否存在、大小是否异常。 4. 如果需要高清放大执行 python scripts/upscale.py \ --input output/demo.png \ --output output/demo_hd.png \ --scale 2 5. 最后把生成文件的绝对路径返回给用户并简述图片内容。 ## 注意事项 - 执行脚本前先确认 Python 和 Pillow 已安装python --version - 云端接口需要 IMAGE_API_KEY 环境变量。 - 本地引擎需要先启动 ComfyUI默认地址 http://127.0.0.1:8188 - 遵守内容安全规定不生成违规敏感图片遇到此类需求直接拒绝。这里把“理解需求、执行脚本、检查结果、返回路径”写成一整套流程AI 执行时不会漏步骤。4.3 编写图片生成脚本创建scripts/generate.py这是核心脚本负责调用云端 API 或 ComfyUI#!/usr/bin/env python3 统一图片生成脚本。 用法 python generate.py --prompt 一只橘猫坐在书桌前 \ --engine cloud --width 1024 --height 1024 \ --output output/test.png import argparse import base64 import json import os import sys import urllib.request def call_cloud(prompt, width, height, output_path): 调用云端图像生成 API示例兼容 OpenAI Images API 格式。 api_key os.environ.get(IMAGE_API_KEY) if not api_key: sys.exit(错误缺少 IMAGE_API_KEY 环境变量) api_url os.environ.get(IMAGE_API_URL, https://api.openai.com/v1/images/generations) model os.environ.get(IMAGE_MODEL, gpt-image-1) body json.dumps({ model: model, prompt: prompt, size: f{width}x{height}, n: 1, response_format: b64_json, }).encode(utf-8) req urllib.request.Request( api_url, databody, headers{ Authorization: fBearer {api_key}, Content-Type: application/json, }, methodPOST, ) with urllib.request.urlopen(req, timeout60) as resp: result json.loads(resp.read().decode(utf-8)) b64 result[data][0].get(b64_json) if not b64: sys.exit(错误接口返回内容中没有 b64_json 字段) with open(output_path, wb) as f: f.write(base64.b64decode(b64)) print(f[OK] 图片已保存: {output_path}) def call_comfyui(prompt, negative, width, height): 通过 ComfyUI HTTP API 提交文生图工作流。 实际项目建议先在 ComfyUI 界面调试好工作流 再通过菜单 Save (API Format) 导出 JSON然后替换提示词节点。 comfy_url os.environ.get(COMFYUI_URL, http://127.0.0.1:8188) workflow { 3: { class_type: KSampler, inputs: { seed: 42, steps: 20, cfg: 7.0, sampler_name: euler, scheduler: normal, denoise: 1.0, model: [4, 0], positive: [6, 0], negative: [7, 0], latent_image: [5, 0], }, }, 4: { class_type: CheckpointLoaderSimple, inputs: {ckpt_name: v1-5-pruned-emaonly.safetensors}, }, 5: { class_type: EmptyLatentImage, inputs: {width: width, height: height, batch_size: 1}, }, 6: { class_type: CLIPTextEncode, inputs: {text: prompt, clip: [4, 1]}, }, 7: { class_type: CLIPTextEncode, inputs: {text: negative, clip: [4, 1]}, }, 8: { class_type: VAEDecode, inputs: {samples: [3, 0], vae: [4, 2]}, }, 9: { class_type: SaveImage, inputs: {filename_prefix: skill_output, images: [8, 0]}, }, } payload json.dumps({prompt: workflow}).encode(utf-8) req urllib.request.Request( f{comfy_url}/prompt, datapayload, headers{Content-Type: application/json}, methodPOST, ) with urllib.request.urlopen(req, timeout30) as resp: result json.loads(resp.read().decode(utf-8)) prompt_id result.get(prompt_id) if prompt_id: print(f[OK] 已提交 ComfyUI 工作流prompt_id{prompt_id}) print(提示ComfyUI 输出图片保存在它的 output 目录可打开界面查看。) def main(): parser argparse.ArgumentParser(description图片生成统一入口) parser.add_argument(--prompt, requiredTrue, help正向描述) parser.add_argument(--negative, defaultblurry, low quality, help负向描述) parser.add_argument(--engine, defaultcloud, choices[cloud, comfyui]) parser.add_argument(--width, typeint, default1024) parser.add_argument(--height, typeint, default1024) parser.add_argument(--output, defaultoutput.png) args parser.parse_args() os.makedirs(os.path.dirname(os.path.abspath(args.output)), exist_okTrue) if args.engine cloud: call_cloud(args.prompt, args.width, args.height, args.output) elif args.engine comfyui: call_comfyui(args.prompt, args.negative, args.width, args.height) if __name__ __main__: main()这段代码里有两个值得注意的细节。第一response_format设置为b64_json这样接口会返回图片的 base64 字符串脚本再转成文件避免额外处理 URL 重定向。第二ComfyUI 的工作流本质上是一个带节点 ID 的 JSON节点之间的连线通过类似[4, 0]的引用实现4是节点 ID0是第几个输出。如果你换了底模需要同时修改ckpt_name为你本机实际存在的模型文件名。4.4 编写高清放大脚本创建scripts/upscale.py#!/usr/bin/env python3 图片高清放大脚本基于 Pillow 的 LANCZOS 重采样。 import argparse from PIL import Image def main(): parser argparse.ArgumentParser(description图片高清放大) parser.add_argument(--input, requiredTrue, help输入图片路径) parser.add_argument(--output, requiredTrue, help输出图片路径) parser.add_argument(--scale, typeint, default2, help放大倍数默认 2 倍) args parser.parse_args() img Image.open(args.input) width, height img.size new_size (width * args.scale, height * args.scale) upscaled img.resize(new_size, Image.LANCZOS) upscaled.save(args.output) print(f[OK] {args.input} - {args.output}) print(f尺寸: {width}x{height} - {new_size[0]}x{new_size[1]}) if __name__ __main__: main()Pillow 的 LANCZOS 适合简单的倍数放大但对真实照片的细节恢复有限。追求更好效果时可以接入 Real-ESRGAN 这类超分辨率模型命令思路如下具体参数以对应工具版本为准realesrgan-ncnn-vulkan -i input.png -o output.png -n realesrgan-x4plus -s 44.5 安装并验证 Skill把image-gen目录放到~/.claude/skills/下重启 Claude Code 即可被识别。然后输入测试指令请帮我生成一张 1024x102
