最近在 GitHub 上刷项目时大家讨论最多的一个词就是Skill。不管是 Claude Code、Codex 还是 OpenCode几乎都在用“Skill”来扩展 Agent 的能力边界。更有意思的是很多开发者把“图片生成”做成一个 Skill 之后原本需要手动写脚本、调参数、到处找工具的活儿现在只需要一句自然语言就能完成。今天这篇文章就来拆解一下如何自己封装一个图片生成类 Skill并让它真正被 AI Agent 调用起来。内容会从 Skill 的原理讲起再到完整代码实战最后给出常见问题排查和工程建议。无论你是刚开始接触 Agent 开发还是已经在用 Claude Code / Codex 等工具都能从里面找到可以直接复用的方案。1. 背景与核心概念1.1 什么是 Skill它和普通脚本有什么区别先聊一个很容易混淆的问题Skill 到底是个什么东西从本质上看Skill 是一种面向 AI Agent 的“能力包”。它通常由一个目录组成目录里包含一个SKILL.md说明文件用来告诉大模型“这个技能能做什么、怎么调用”。一个或多个脚本文件用来真正执行任务。可能还有模板、资源文件、配置文件等。举个例子如果你想让 AI 帮你生成一张带文字的图片最原始的做法是让 AI 直接写一段 Python 脚本然后你来运行。问题在于每次对话时模型都需要重新理解需求、生成代码而且一旦涉及中文字体、图片尺寸、批量生成这些细节很容易翻车。而 Skill 的思路不一样它把“生成图片”这个完整流程预先封装好。模型看到用户需求后只需要读取SKILL.md知道应该运行哪个命令然后把参数填进去即可。这相当于给 AI 配了一个“标准操作手册”。所以Skill 和普通脚本的区别在于普通脚本是给人用的使用者需要知道命令、参数、路径。Skill 是给 Agent 用的模型负责读取文档、拼命令、解释结果。1.2 为什么“Skill 图片生成”会成为 GitHub 热点这段时间 GitHub 上关于 Skill 的热度主要来自 Claude Code、Codex 等编程 Agent 的流行。以前我们让 AI 写代码它只能输出代码片段现在有了 SkillAI 可以直接调用本机脚本完成图片生成、格式转换、文件批处理、数据库操作等实际任务。图片生成恰好是一个高频场景写博客时需要封面图做 PPT 时需要占位图做自动化测试时需要测试图片本地开发时需要生成带中文文字的横幅图批量处理图片时需要统一裁剪、加水印、转换格式。如果每一项功能都做成独立脚本维护成本太高如果全部靠模型临时写代码结果又不稳定。把图片生成能力封装成一个 Skill正好解决了这两个痛点。更关键的是Skill 的目录结构和运行方式是标准化的意味着同一个 Skill 可以同时被多个 Agent 工具使用。这种“一次封装、多处复用”的特性正是它走红的核心原因。1.3 Skill 的典型工作流程为了后面实战不迷路这里先用一条流程来说明 Skill 是如何工作的用户输入自然语言请求 ↓ Agent 识别到请求与某个 Skill 匹配 ↓ Agent 读取该 Skill 目录下的 SKILL.md ↓ SKILL.md 中说明了执行脚本的命令和参数 ↓ Agent 根据用户需求生成具体命令并执行 ↓ 脚本运行生成图片文件 ↓ Agent 返回结果给用户这个流程看起来简单但在实际落地时有几个地方非常容易出问题SKILL.md写得不清楚导致模型不知道什么时候调用脚本依赖环境不完整导致运行失败中文字体路径不一致导致乱码。后面我们会逐个解决。2. 图片生成类 Skill 的原理与目录设计2.1 一个最小 Skill 工程长什么样我们以“通用图片生成”为目标设计一个最小可用的 Skill 目录image-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_image.py # 文字转图片、生成基础图片 │ ├── process_image.py # 裁剪、缩放、加水印、格式转换 │ └── batch_generate.py # 批量生成图片 ├── templates/ │ └── cover_template.png # 预留的模板图片目录 ├── fonts/ │ └── README.md # 说明字体文件如何放置 └── output/ └── .gitkeep # 输出目录用于存放生成结果这里每个文件的职责都很清晰SKILL.md是整个 Skill 的入口也是 Agent 最先读取的文件。scripts/存放所有可执行脚本脚本之间尽量保持功能独立。templates/用来放图片模板例如海报底图、封面背景。fonts/用来放中文字体文件解决 Pillow 默认字体不支持中文的问题。output/是输出目录所有生成结果统一放在这里方便后续清理和归档。2.2 SKILL.md 到底怎么写给 Agent 看SKILL.md不是给人写的文档而是给大模型看的“操作手册”。大模型本身不具备执行能力它需要通过阅读这个文件来理解什么情况下应该调用这个 Skill有哪些脚本可用每个脚本支持什么参数典型的调用示例是什么。一个标准的SKILL.md开头通常包含 YAML 格式的 frontmatter例如--- name: image-skill description: 用于生成图片、处理图片、批量生成图片。当用户需要把文字转成图片、生成海报、处理或转换图片时使用这个 Skill。 ---这里的name是 Skill 的唯一标识description则决定了模型能否正确匹配用户需求。建议在描述里写清楚“什么时候用”而不是只写“能做什么”。例如“当用户需要把文字转成图片”就比“图片生成工具”更容易被模型理解。正文部分应当按“能力分类 命令示例 参数说明”组织。模型会通过示例来猜测你的意图所以示例越完整模型调用越准确。2.3 为什么选择 Python Pillow 作为底层实现图片生成类 Skill 的底层实现有很多选择Python 的 PillowPIL库轻量、跨平台、适合文字绘制和基础图片处理OpenCV适合复杂的图像处理但依赖较重sdwebui / ComfyUI适合 AI 绘画但需要 GPU 和模型文件ImageMagick 命令行工具适合批处理但参数风格特殊。对于“一个 Skill 搞定所有图片生成的问题”这个目标Pillow 是最稳妥的起点。理由有三点安装简单pip install Pillow一条命令搞定。够用文字转图片、缩放、裁剪、加水印、格式转换都能做。便于调试脚本逻辑直观普通开发者可以快速上手修改。如果你的需求已经上升到“AI 绘画出图”那就不应该自己写脚本而是去封装 ComfyUI 或 Stable Diffusion WebUI 的 API。这个方向可以之后单独写一篇今天聚焦在轻量级图片生成 Skill 上。2.4 Skill 是如何被 Agent 识别的不同 Agent 工具对 Skill 的目录位置要求略有不同但原理基本一致。以常见的编程 Agent 为例通常只需要将 Skill 目录放入约定的skills文件夹Agent 启动时会自动扫描。例如project/ ├── skills/ │ └── image-skill/ │ ├── SKILL.md │ └── scripts/ ├── src/ └── README.md把image-skill放到skills目录下重启 Agent再向它提问“帮我把这句话做成一张封面图”Agent 就会自己去读SKILL.md然后调用脚本完成任务。这就是整个 Skill 玩法的核心体验。3. 环境准备与版本说明3.1 运行环境在开始写代码之前先确认你的环境。本文的示例以常见环境为例操作系统Windows 10/11、macOS、Linux 均可。Python 版本建议 Python 3.10 或更高版本。Pillow 版本建议使用 10.x 或更新的稳定版。Agent 工具Claude Code、Codex CLI、OpenCode 等选一种即可。版本需要根据你的项目实际情况调整本文重点演示配置思路和代码实现。如果你的 Python 环境比较老建议先升级到 3.10 以上避免语法不兼容。3.2 创建项目目录与虚拟环境首先创建一个项目目录并进入目录mkdir image-skill-project cd image-skill-project然后创建并激活虚拟环境。Python 虚拟环境可以避免依赖冲突是工程化开发的基本习惯。python -m venv venvWindows 激活命令venv\Scripts\activatemacOS / Linux 激活命令source venv/bin/activate激活后命令行提示符前缀会变成(venv)说明当前正在使用虚拟环境。3.3 安装 Pillow接着安装 Pillowpip install Pillow安装完成后可以检查版本python -c import PIL; print(PIL.__version__)如果能够正常输出版本号说明 Pillow 安装成功。后面所有脚本都会依赖这个库。3.4 准备中文字体文件这是一个非常容易被忽略的坑Pillow 默认字体是英文直接绘制中文会变成方框或乱码。解决方案是手动指定一个中文字体文件。不同系统的常见字体路径如下WindowsC:/Windows/Fonts/msyh.ttc微软雅黑、C:/Windows/Fonts/simhei.ttf黑体macOS/System/Library/Fonts/PingFang.ttc苹方Linux/usr/share/fonts/truetype/wqy/wqy-microhei.ttc文泉驿微米黑在脚本中我们会设计一个“自动查找字体 手动指定字体”的兼容方案确保不同平台都能运行。4. 完整实战封装一个图片生成 Skill4.1 创建目录结构在项目目录下创建完整目录结构mkdir -p image-skill/scripts mkdir -p image-skill/templates mkdir -p image-skill/fonts mkdir -p image-skill/output创建完成后用tree命令Windows 下可用tree /F查看image-skill/ ├── scripts/ ├── templates/ ├── fonts/ └── output/接下来把三个 Python 脚本和SKILL.md依次加入。4.2 编写 SKILL.md在image-skill/SKILL.md中写入以下内容--- name: image-skill description: 用于生成图片、处理图片、批量生成图片。当用户需要把文字转成图片、生成海报、制作封面、处理或转换图片时使用这个 Skill。 --- # 图片生成 Skill 这是一个基于 Python Pillow 的图片生成与处理工具。 ## 能力列表 1. 文字转图片将指定文字渲染到一张纯色背景图片上。 2. 图片处理支持缩放、裁剪、加水印、格式转换。 3. 批量生成根据 JSON 配置文件批量生成多张图片。 ## 使用方式 ### 1. 文字转图片 运行命令 bash python scripts/generate_image.py --text 你好CSDN --output output/demo.png常用参数说明参数说明默认值--text要绘制的文字必填--output输出图片路径output/image.png--width图片宽度800--height图片高度400--bg背景颜色十六进制格式#2c3e50--color文字颜色十六进制格式#ffffff--font中文字体路径自动查找2. 图片处理运行命令python scripts/process_image.py --input input.png --output output/result.png --width 600 --format JPEG --watermark Copyright3. 批量生成运行命令python scripts/batch_generate.py --config config.json配置文件格式[ { text: 封面图, output: output/001.png, width: 1200, height: 630, bg: #1abc9c, color: #ffffff } ]注意事项如果出现中文乱码必须通过 --font 参数指定中文字体。所有脚本都依赖 Pillow运行前请确认安装pip install Pillow。这样一份 SKILL.md已经把时机、命令、参数、常见坑都交代清楚了。Agent 拿到之后基本不会出现“不知道用什么命令”的问题。 ### 4.3 编写文字转图片脚本 在 image-skill/scripts/generate_image.py 中写入 python # 文件路径image-skill/scripts/generate_image.py # 功能将指定文字渲染到一张纯色背景图片上 import argparse import os from PIL import Image, ImageDraw, ImageFont def find_font(): 根据当前系统查找可用的中文字体找不到返回 None font_candidates [ # Windows C:/Windows/Fonts/msyh.ttc, C:/Windows/Fonts/simhei.ttf, # macOS /System/Library/Fonts/PingFang.ttc, # Linux /usr/share/fonts/truetype/wqy/wqy-microhei.ttc, ] for font_path in font_candidates: if os.path.exists(font_path): return font_path return None def main(): parser argparse.ArgumentParser(description文字转图片生成器) parser.add_argument(--text, requiredTrue, help要绘制的文字) parser.add_argument(--output, defaultoutput/image.png, help输出图片路径) parser.add_argument(--width, typeint, default800, help图片宽度) parser.add_argument(--height, typeint, default400, help图片高度) parser.add_argument(--bg, default#2c3e50, help背景颜色如 #2c3e50) parser.add_argument(--color, default#ffffff, help文字颜色如 #ffffff) parser.add_argument(--font, defaultNone, help中文字体路径默认自动查找) args parser.parse_args() # 字体处理优先使用手动指定的字体其次自动查找 font_path args.font or find_font() if not font_path: print([ERROR] 未找到可用中文字体请使用 --font 参数指定字体文件路径) return # 确保输出目录存在 output_dir os.path.dirname(args.output) if output_dir: os.makedirs(output_dir, exist_okTrue) # 创建画布 image Image.new(RGB, (args.width, args.height), colorargs.bg) draw ImageDraw.Draw(image) # 根据图片尺寸动态计算字体大小 font_size min(args.width, args.height) // 8 try: font ImageFont.truetype(font_path, font_size) except Exception as e: print(f[ERROR] 字体加载失败: {e}) return # 计算文字居中位置 bbox draw.textbbox((0, 0), args.text, fontfont) text_width bbox[2] - bbox[0] text_height bbox[3] - bbox[1] x (args.width - text_width) / 2 - bbox[0] y (args.height - text_height) / 2 - bbox[1] # 绘制文字并保存 draw.text((x, y), args.text, fontfont, fillargs.color) image.save(args.output) print(f[OK] 图片已生成: {args.output}) if __name__ __main__: main()这段代码的关键点有三个字体自动查找不同系统字体路径差异很大自动查找机制可以避免用户每次手动指定。文字居中算法使用textbbox计算文字的实际像素宽高再做偏移确保中文居中也准确。目录自动创建如果output目录不存在脚本会自动创建避免保存时报错。4.4 编写图片处理脚本在image-skill/scripts/process_image.py中写入# 文件路径image-skill/scripts/process_image.py # 功能对图片进行缩放、裁剪、加水印、格式转换 import argparse import os from PIL import Image, ImageDraw, ImageFont def add_watermark(image, text, font_pathNone): 给图片添加简单的文字水印 watermark image.convert(RGBA) layer Image.new(RGBA, watermark.size, (0, 0, 0, 0)) draw ImageDraw.Draw(layer) font_size watermark.size[0] // 20 font_path font_path or C:/Windows/Fonts/arial.ttf try: font ImageFont.truetype(font_path, font_size) except Exception: font ImageFont.load_default() # 水印位置右下角带一点边距 bbox draw.textbbox((0, 0), text, fontfont) text_width bbox[2] - bbox[0] text_height bbox[3] - bbox[1] x watermark.size[0] - text_width - 20 y watermark.size[1] - text_height - 20 draw.text((x, y), text, fontfont, fill(255, 255, 255, 180)) return Image.alpha_composite(watermark, layer).convert(RGB) def main(): parser argparse.ArgumentParser(description图片处理工具缩放、裁剪、水印、格式转换) parser.add_argument(--input, requiredTrue, help输入图片路径) parser.add_argument(--output, requiredTrue, help输出图片路径) parser.add_argument(--width, typeint, defaultNone, help目标宽度) parser.add_argument(--height, typeint, defaultNone, help目标高度) parser.add_argument(--watermark, defaultNone, help水印文字) parser.add_argument(--format, defaultNone, help输出格式如 JPEG、PNG、WEBP) args parser.parse_args() if not os.path.exists(args.input): print(f[ERROR] 输入图片不存在: {args.input}) return # 打开图片并转换为 RGB 模式避免部分格式出现通道问题 image Image.open(args.input).convert(RGB) # 缩放保持比例的情况下调整尺寸 if args.width and args.height: image image.resize((args.width, args.height), Image.LANCZOS) elif args.width: ratio args.width / image.size[0] image image.resize((args.width, int(image.size[1] * ratio)), Image.LANCZOS) elif args.height: ratio args.height / image.size[1] image image.resize((int(image.size[0] * ratio), args.height), Image.LANCZOS) # 添加水印 if args.watermark: image add_watermark(image, args.watermark) # 保存输出 output_dir os.path.dirname(args.output) if output_dir: os.makedirs(output_dir, exist_okTrue) if args.format: save_format args.format.upper() else: ext os.path.splitext(args.output)[1].lower().replace(., ) save_format ext if ext in [JPEG, PNG, WEBP, BMP] else PNG image.save(args.output, formatsave_format) print(f[OK] 图片处理完成: {args.output}) if __name__ __main__: main()这个脚本提供了三个实用能力按宽或高等比缩放不会把图片拉变形。右下角添加水印适合自动化打码场景。格式转换输出时会根据文件后缀或--format参数自动判断格式。这里使用了Image.LANCZOS作为缩放算法比默认的最近邻插值效果更好适合图片从大图缩小到小图的场景。4.5 编写批量生成脚本在image-skill/scripts/batch_generate.py中写入# 文件路径image-skill/scripts/batch_generate.py # 功能根据 JSON 配置文件批量生成图片 import argparse import json import os from generate_image import main as generate_main def load_config(config_path): 读取 JSON 配置文件 if not os.path.exists(config_path): raise FileNotFoundError(f配置文件不存在: {config_path}) with open(config_path, r, encodingutf-8) as f: return json.load(f) def main(): parser argparse.ArgumentParser(description批量生成图片) parser.add_argument(--config, requiredTrue, helpJSON 配置文件路径) args parser.parse_args() try: tasks load_config(args.config) except Exception as e: print(f[ERROR] 读取配置文件失败: {e}) return if not isinstance(tasks, list): print([ERROR] 配置文件格式应为数组例如 [{...}, {...}]) return total len(tasks) for index, task in enumerate(tasks, start1): print(f[INFO] 正在生成第 {index}/{total} 张图片: {task.get(text, )}) try: # 复用 generate_image.py 的命令行解析逻辑 import sys argv [ generate_image.py, --text, task.get(text, ), --output, task.get(output, output/image.png), --width, str(task.get(width, 800)), --height, str(task.get(height, 400)), --bg, task.get(bg, #2c3e50), --color, task.get(color, #ffffff), ] if task.get(font): argv [--font, task[font]] # 备份并替换 sys.argv old_argv sys.argv sys.argv argv generate_main() sys.argv old_argv except Exception as e: print(f[ERROR] 第 {index} 张图片生成失败: {e}) print(f[OK] 批量生成完成共 {total} 张图片) if __name__ __main__: main()这个脚本通过复用generate_image.py的入口函数减少重复代码。配置文件中的每一个对象就是一张待生成图片的完整参数。需要注意一点脚本内部直接修改了sys.argv来复用命令行函数这种写法在独立脚本中是可行的但如果你后续把功能做复杂了更推荐把核心绘制逻辑抽成独立的工具函数而不是通过命令行参数互相调用。4.6 在 Agent 中加载 Skill代码写完之后最后一步是把整个image-skill目录放到 Agent 能扫描到的位置。不同工具差异较大具体操作请以你使用的工具文档为准。以常见的项目本地 Skill 目录为例你的项目结构应该是这样image-skill-project/ ├── skills/ │ └── image-skill/ │ ├── SKILL.md │ ├── scripts/ │ │ ├── generate_image.py │ │ ├── process_image.py │ │ └── batch_generate.py │ ├── templates/ │ └── output/ ├── venv/ └── config.json启动 Agent 后直接提问帮我把“CSDN 技术博客封面”这几个字生成一张宽 1200、高 630 的封面图背景用蓝色文字用白色。如果 Skill 配置正确Agent 会自动读取SKILL.md然后执行类似下面的命令python scripts/generate_image.py --text CSDN 技术博客封面 --output output/cover.png --width 1200 --height 630 --bg #2980b9 --color #ffffff整个过程用户只需要描述需求不需要关心脚本参数这就是 Skill 带来的体验提升。5. 运行与验证5.1 直接运行脚本验证在进入 Agent 环节之前建议先手动跑一遍脚本确保环境没问题。生成一张基础图片python image-skill/scripts/generate_image.py --text Hello Skill --output output/demo.png预期输出[OK] 图片已生成: output/demo.png然后去output目录下查看demo.png图片内容为深蓝背景上的白色文字 Hello Skill。测试中文python image-skill/scripts/generate_image.py --text 你好CSDN --output output/demo_cn.png如果输出正常说明字体查找逻辑生效了。如果出现中文乱码说明系统没有匹配到中文字体需要手动指定python image-skill/scripts/generate_image.py --text 你好CSDN --output output/demo_cn.png --font C:/Windows/Fonts/msyh.ttc测试图片处理python image-skill/scripts/process_image.py --input output/demo.png --output output/processed.jpg --width 600 --watermark CSDN预期得到一张宽度为 600、右下角带水印的 JPEG 图片。5.2 通过 Agent 自然语言调用验证确保虚拟环境已激活然后启动你使用的 Agent 工具。提问例句请使用 image-skill 把“GitHub 一周热点”生成一张 800x400 的图片放到 output 目录。观察 Agent 的行为是否识别到需要调用 image-skill是否读取了 SKILL.md是否执行了正确的 Python 命令是否返回了图片路径。如果 Agent 没有调用 Skill优先检查SKILL.md的description是否写清楚了触发条件同时确认 Skill 目录是否被正确扫描。5.3 预期结果说明一个配置良好的 Skill在使用时应该具备以下特征用户不需要知道脚本参数只需描述图片内容Agent 能主动维护输出目录生成失败时Agent 能根据错误信息尝试更换字体或调整参数用户最终能得到一个可访问的图片文件路径。如果以上目标都实现了说明你已经拥有一个可复用的图片生成 Skill。6. 常见问题与排查思路问题现象常见原因解决思路Skill 没有被 Agent 识别目录位置不对或 description 不清晰检查 skills 目录配置优化 SKILL.md 描述生成的中文变成方框未指定中文字体使用 --font 指定系统字体路径找不到字体文件字体路径写死或系统字体缺失在脚本中增加多系统候选路径图片太模糊直接使用小尺寸图放大或用了低质量缩放算法生成时调大 width/height使用 LANCZOS执行报错 FileNotFoundError输入图片路径不存在先检查文件是否真实存在再执行脚本batch 批量生成中断单张图片参数错误导致脚本退出代码中捕获单张任务的异常继续执行后续任务GitHub 项目下载慢或无法访问国内网络环境下访问 GitHub 不稳定使用 SSH 方式克隆或通过 Gitee 导入项目后下载ComfyUI 预览窗口不显示但图片已生成工作流中缺少 Preview Image 节点或只用了 Save Image 节点在保存节点后接入 Preview Image 节点或直接去 output 目录查看文件下面重点说几个高频问题。6.1 Skill 没有被 Agent 自动识别这是新手最常遇到的问题。可能原因有两类一是目录位置不对。很多 Agent 只扫描项目的skills目录如果你把 Skill 放在别的地方它自然找不到。解决办法是把image-skill目录移到项目根目录下的skills文件夹中并重启 Agent。二是SKILL.md的description描述太泛。比如只写“图片生成工具”模型无法准确判断什么时候用它。建议写成“当用户需要把文字转成图片、生成海报、制作封面、处理或转换图片时使用这个 Skill”这样触发准确率会明显提升。6.2 中文乱码问题Pillow 默认字体是英文位图字体直接绘制中文会显示方框。解决思路有两个在脚本里维护一个“多系统候选字体”列表运行时自动查找第一个存在的字体如果自动查找失败就通过--font参数手动指定。这个逻辑在generate_image.py里已经实现了如果你在使用过程中仍出现乱码请先确认系统里确实存在对应路径的字体文件。6.3 GitHub 项目下载慢或无法访问GitHub 热点项目通常是 Skill、Agent 或开源工具。很多人在安装时会遇到 GitHub 下载慢、打不开的问题。这里说几个安全且常用的方法使用 SSH 方式克隆在 GitHub 仓库页面复制 SSH 地址例如gitgithub.com:user/repo.git然后执行git clone gitgithub.com:user/repo.git。SSH 方式在部分网络环境中比 HTTPS 更稳定。通过 Gitee 导入项目如果 GitHub 实在访问不了可以把仓库导入到 Gitee再从 Gitee 克隆速度通常会快很多。合理使用镜像站部分 GitHub 开源镜像站可以下载单个文件或仓库压缩包但要注意选择信誉良好的站点避免下载到被篡改的脚本。这里特别提醒不要从非官方渠道获取所谓“原版”“无删减版”资源安全风险极高而且很可能夹带恶意脚本。6.4 生成出来的图片太小、不够清晰Skill 脚本本身是按参数生成图片的如果用户没有指定尺寸默认只有 800x400打印或做封面时会觉得模糊。解决办法是生成时明确要求大尺寸例如宽度 1920、高度 1080脚本中创建图片时使用目标尺寸缩放时使用Image.LANCZOS算法它比默认算法更平滑。如果你已经有了一张小图想放大而不明显失真单纯用 Pillow 效果有限。工程上可以接入 Real-ESRGAN 等超分工具但那是另一个话题了。6.5 ComfyUI 预览窗口不显示但图片已生成这个话题在热词里也出现了ConfyUI 在生成图片时预览窗口看不到预览图但图片实际上已经生成了。这通常和工作流节点的连接方式有关。ComfyUI 中有一个Preview Image节点专门用于在界面上预览图片而Save Image节点只负责保存文件。如果你只用了Save Image节点预览窗口自然没有内容。解决方法是检查工作流里是否拖入了Preview Image节点确认节点连接是否正确预览图生成后去 ComfyUI 的output目录查找文件。另外如果是在 headless无图形界面模式或远程环境下运行预览窗口可能因为网络原因无法回传图片这时候服务端日志里通常会有输出路径直接去看文件即可。7. 最佳实践与工程建议7.1 SKILL.md 的 description 要写“触发条件”而不是“功能清单”大模型不是搜索引擎它不会去解析你文件里的每个函数。它主要通过description来判断要不要调用这个 Skill。所以描述应该写成当用户需要把文字转成图片、生成海报、制作封面、处理或转换图片时使用这个 Skill。而不是这是一个基于 Pillow 的图片处理工具包含三个 Python 脚本。后者功能上没错但对模型来说信息量不足很容易导致误用或漏用。7.2 路径处理要统一在 Skill 脚本中路径问题几乎是必踩的坑。建议遵守以下几条脚本内部统一使用相对于 Skill 根目录的路径而不是相对于“当前执行目录”的路径所有输出统一写入output/目录运行前判断输入文件是否存在如果脚本需要被 Agent 从不同路径调用建议用os.path.dirname(__file__)获取脚本所在目录再拼接其他资源路径。例如import os SCRIPT_DIR os.path.dirname(os.path.abspath(__file__)) PROJECT_DIR os.path.dirname(SCRIPT_DIR) FONT_DIR os.path.join(PROJECT_DIR, fonts) OUTPUT_DIR os.path.join(PROJECT_DIR, output)这样无论从哪里执行脚本资源路径都是稳定的。7.3 环境依赖要显式声明Skill 运行在 Agent 的工作环境中但这个环境不一定和你本地开发环境一致。建议在 Skill 目录里放一个requirements.txtPillow10.0.0并在SKILL.md里写明首次使用前请执行pip install -r requirements.txt这样做的好处是即使换了一台机器Agent 也能根据文档完成依赖安装。7.4 日志输出要规范Agent 无法“看到”图片它只能通过命令行输出来判断脚本是否成功。所以脚本的日志要设计得对 Agent 友好成功时输出[OK] 图片已生成: 具体路径失败时输出[ERROR] 失败原因不要只输出一大段堆栈信息因为模型很难从中提取关键信息。如果脚本有多个步骤尽量加上[INFO] 正在执行...的提示这样 Agent 中途出问题也能及时发现。7.5 安全与合规边界图片生成能力本身是中性的但接入 Skill 后它可能会被 Agent 自动调用所以必须注意边界问题。第一不要生成违法、侵权、暴力、色情等不良内容。Skill 在SKILL.md中可以写清楚使用边界Agent 在调用时也会被底层模型的安全策略限制。作为开发者不要在脚本里加入“绕过审核”“无限制生成”之类的功能这对项目和用户都是风险。第二涉及用户上传的图片时不要轻易把图片发送到第三方 API。优先在本机完成处理保护隐私数据。第三如果用到了外部模型或在线服务一定要确认数据合规和调用权限。不要使用来源不明的接口避免账号泄漏或法律风险。7.6 Skill 与 Agent 工具的版本适配不同 Agent 工具对 Skill 的识别方式还在快速迭代。例如 Claude Code、Codex、OpenCode 等虽然都借鉴了类似的概念但目录约定、加载机制、配置文件名可能不同。因此在一个工具上调试通过的 Skill换到另一个工具时不一定能直接使用。建议以你正在使用的 Agent 官方文档为准保持SKILL.md的 frontmatter 字段尽量标准实际项目中把 Skill 放在一个独立仓库里管理按需复制到不同项目关注 Agent 版本更新日志及时适配新机制。8. 总结与下一步这篇文章从一个 GitHub 热点话题切入完整拆解了“Skill 图片生成”的原理与落地方式。现在你已经掌握了Skill 的本质面向 Agent 的能力包包含SKILL.md、脚本和资源文件图片生成 Skill 的完整目录结构三个核心脚本文字转图片、图片处理、批量生成如何编写一份能被 Agent 正确识别的SKILL.md常见问题的排查方法包括中文乱码、路径问题、GitHub 下载慢和 ComfyUI 预览问题。下一步可以往两个方向继续深入。如果你对 Agent 本身感兴趣可以去研究 Claude Code、Codex、OpenCode 等工具的 Skill 加载机制尝试为不同工具编写可复用的通用 Skill。图片生成只是其中一个例子你还可以扩展出数据库操作 Skill、文件批处理 Skill、爬虫 Skill 等。如果你更关注图片生成效果则可以继续学习 ComfyUI API 封装、Stable Diffusion 模型调用、超分辨率工具集成等。把这些能力也封装成 Skill 后你就能做到“一个入口完成从提示词到高质量图片的完整闭环”。最后如果你在配置 Skill 时遇到问题可以先用最简单的脚本跑通再逐步加功能。Skill 的价值在于让复杂事情变得可复用前提是它足够稳定。希望这篇实战教程能帮你省下一些折腾的时间。 如何封装图片生成Skill，让AI Agent真正调用起来
最近在 GitHub 上刷项目时大家讨论最多的一个词就是Skill。不管是 Claude Code、Codex 还是 OpenCode几乎都在用“Skill”来扩展 Agent 的能力边界。更有意思的是很多开发者把“图片生成”做成一个 Skill 之后原本需要手动写脚本、调参数、到处找工具的活儿现在只需要一句自然语言就能完成。今天这篇文章就来拆解一下如何自己封装一个图片生成类 Skill并让它真正被 AI Agent 调用起来。内容会从 Skill 的原理讲起再到完整代码实战最后给出常见问题排查和工程建议。无论你是刚开始接触 Agent 开发还是已经在用 Claude Code / Codex 等工具都能从里面找到可以直接复用的方案。1. 背景与核心概念1.1 什么是 Skill它和普通脚本有什么区别先聊一个很容易混淆的问题Skill 到底是个什么东西从本质上看Skill 是一种面向 AI Agent 的“能力包”。它通常由一个目录组成目录里包含一个SKILL.md说明文件用来告诉大模型“这个技能能做什么、怎么调用”。一个或多个脚本文件用来真正执行任务。可能还有模板、资源文件、配置文件等。举个例子如果你想让 AI 帮你生成一张带文字的图片最原始的做法是让 AI 直接写一段 Python 脚本然后你来运行。问题在于每次对话时模型都需要重新理解需求、生成代码而且一旦涉及中文字体、图片尺寸、批量生成这些细节很容易翻车。而 Skill 的思路不一样它把“生成图片”这个完整流程预先封装好。模型看到用户需求后只需要读取SKILL.md知道应该运行哪个命令然后把参数填进去即可。这相当于给 AI 配了一个“标准操作手册”。所以Skill 和普通脚本的区别在于普通脚本是给人用的使用者需要知道命令、参数、路径。Skill 是给 Agent 用的模型负责读取文档、拼命令、解释结果。1.2 为什么“Skill 图片生成”会成为 GitHub 热点这段时间 GitHub 上关于 Skill 的热度主要来自 Claude Code、Codex 等编程 Agent 的流行。以前我们让 AI 写代码它只能输出代码片段现在有了 SkillAI 可以直接调用本机脚本完成图片生成、格式转换、文件批处理、数据库操作等实际任务。图片生成恰好是一个高频场景写博客时需要封面图做 PPT 时需要占位图做自动化测试时需要测试图片本地开发时需要生成带中文文字的横幅图批量处理图片时需要统一裁剪、加水印、转换格式。如果每一项功能都做成独立脚本维护成本太高如果全部靠模型临时写代码结果又不稳定。把图片生成能力封装成一个 Skill正好解决了这两个痛点。更关键的是Skill 的目录结构和运行方式是标准化的意味着同一个 Skill 可以同时被多个 Agent 工具使用。这种“一次封装、多处复用”的特性正是它走红的核心原因。1.3 Skill 的典型工作流程为了后面实战不迷路这里先用一条流程来说明 Skill 是如何工作的用户输入自然语言请求 ↓ Agent 识别到请求与某个 Skill 匹配 ↓ Agent 读取该 Skill 目录下的 SKILL.md ↓ SKILL.md 中说明了执行脚本的命令和参数 ↓ Agent 根据用户需求生成具体命令并执行 ↓ 脚本运行生成图片文件 ↓ Agent 返回结果给用户这个流程看起来简单但在实际落地时有几个地方非常容易出问题SKILL.md写得不清楚导致模型不知道什么时候调用脚本依赖环境不完整导致运行失败中文字体路径不一致导致乱码。后面我们会逐个解决。2. 图片生成类 Skill 的原理与目录设计2.1 一个最小 Skill 工程长什么样我们以“通用图片生成”为目标设计一个最小可用的 Skill 目录image-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_image.py # 文字转图片、生成基础图片 │ ├── process_image.py # 裁剪、缩放、加水印、格式转换 │ └── batch_generate.py # 批量生成图片 ├── templates/ │ └── cover_template.png # 预留的模板图片目录 ├── fonts/ │ └── README.md # 说明字体文件如何放置 └── output/ └── .gitkeep # 输出目录用于存放生成结果这里每个文件的职责都很清晰SKILL.md是整个 Skill 的入口也是 Agent 最先读取的文件。scripts/存放所有可执行脚本脚本之间尽量保持功能独立。templates/用来放图片模板例如海报底图、封面背景。fonts/用来放中文字体文件解决 Pillow 默认字体不支持中文的问题。output/是输出目录所有生成结果统一放在这里方便后续清理和归档。2.2 SKILL.md 到底怎么写给 Agent 看SKILL.md不是给人写的文档而是给大模型看的“操作手册”。大模型本身不具备执行能力它需要通过阅读这个文件来理解什么情况下应该调用这个 Skill有哪些脚本可用每个脚本支持什么参数典型的调用示例是什么。一个标准的SKILL.md开头通常包含 YAML 格式的 frontmatter例如--- name: image-skill description: 用于生成图片、处理图片、批量生成图片。当用户需要把文字转成图片、生成海报、处理或转换图片时使用这个 Skill。 ---这里的name是 Skill 的唯一标识description则决定了模型能否正确匹配用户需求。建议在描述里写清楚“什么时候用”而不是只写“能做什么”。例如“当用户需要把文字转成图片”就比“图片生成工具”更容易被模型理解。正文部分应当按“能力分类 命令示例 参数说明”组织。模型会通过示例来猜测你的意图所以示例越完整模型调用越准确。2.3 为什么选择 Python Pillow 作为底层实现图片生成类 Skill 的底层实现有很多选择Python 的 PillowPIL库轻量、跨平台、适合文字绘制和基础图片处理OpenCV适合复杂的图像处理但依赖较重sdwebui / ComfyUI适合 AI 绘画但需要 GPU 和模型文件ImageMagick 命令行工具适合批处理但参数风格特殊。对于“一个 Skill 搞定所有图片生成的问题”这个目标Pillow 是最稳妥的起点。理由有三点安装简单pip install Pillow一条命令搞定。够用文字转图片、缩放、裁剪、加水印、格式转换都能做。便于调试脚本逻辑直观普通开发者可以快速上手修改。如果你的需求已经上升到“AI 绘画出图”那就不应该自己写脚本而是去封装 ComfyUI 或 Stable Diffusion WebUI 的 API。这个方向可以之后单独写一篇今天聚焦在轻量级图片生成 Skill 上。2.4 Skill 是如何被 Agent 识别的不同 Agent 工具对 Skill 的目录位置要求略有不同但原理基本一致。以常见的编程 Agent 为例通常只需要将 Skill 目录放入约定的skills文件夹Agent 启动时会自动扫描。例如project/ ├── skills/ │ └── image-skill/ │ ├── SKILL.md │ └── scripts/ ├── src/ └── README.md把image-skill放到skills目录下重启 Agent再向它提问“帮我把这句话做成一张封面图”Agent 就会自己去读SKILL.md然后调用脚本完成任务。这就是整个 Skill 玩法的核心体验。3. 环境准备与版本说明3.1 运行环境在开始写代码之前先确认你的环境。本文的示例以常见环境为例操作系统Windows 10/11、macOS、Linux 均可。Python 版本建议 Python 3.10 或更高版本。Pillow 版本建议使用 10.x 或更新的稳定版。Agent 工具Claude Code、Codex CLI、OpenCode 等选一种即可。版本需要根据你的项目实际情况调整本文重点演示配置思路和代码实现。如果你的 Python 环境比较老建议先升级到 3.10 以上避免语法不兼容。3.2 创建项目目录与虚拟环境首先创建一个项目目录并进入目录mkdir image-skill-project cd image-skill-project然后创建并激活虚拟环境。Python 虚拟环境可以避免依赖冲突是工程化开发的基本习惯。python -m venv venvWindows 激活命令venv\Scripts\activatemacOS / Linux 激活命令source venv/bin/activate激活后命令行提示符前缀会变成(venv)说明当前正在使用虚拟环境。3.3 安装 Pillow接着安装 Pillowpip install Pillow安装完成后可以检查版本python -c import PIL; print(PIL.__version__)如果能够正常输出版本号说明 Pillow 安装成功。后面所有脚本都会依赖这个库。3.4 准备中文字体文件这是一个非常容易被忽略的坑Pillow 默认字体是英文直接绘制中文会变成方框或乱码。解决方案是手动指定一个中文字体文件。不同系统的常见字体路径如下WindowsC:/Windows/Fonts/msyh.ttc微软雅黑、C:/Windows/Fonts/simhei.ttf黑体macOS/System/Library/Fonts/PingFang.ttc苹方Linux/usr/share/fonts/truetype/wqy/wqy-microhei.ttc文泉驿微米黑在脚本中我们会设计一个“自动查找字体 手动指定字体”的兼容方案确保不同平台都能运行。4. 完整实战封装一个图片生成 Skill4.1 创建目录结构在项目目录下创建完整目录结构mkdir -p image-skill/scripts mkdir -p image-skill/templates mkdir -p image-skill/fonts mkdir -p image-skill/output创建完成后用tree命令Windows 下可用tree /F查看image-skill/ ├── scripts/ ├── templates/ ├── fonts/ └── output/接下来把三个 Python 脚本和SKILL.md依次加入。4.2 编写 SKILL.md在image-skill/SKILL.md中写入以下内容--- name: image-skill description: 用于生成图片、处理图片、批量生成图片。当用户需要把文字转成图片、生成海报、制作封面、处理或转换图片时使用这个 Skill。 --- # 图片生成 Skill 这是一个基于 Python Pillow 的图片生成与处理工具。 ## 能力列表 1. 文字转图片将指定文字渲染到一张纯色背景图片上。 2. 图片处理支持缩放、裁剪、加水印、格式转换。 3. 批量生成根据 JSON 配置文件批量生成多张图片。 ## 使用方式 ### 1. 文字转图片 运行命令 bash python scripts/generate_image.py --text 你好CSDN --output output/demo.png常用参数说明参数说明默认值--text要绘制的文字必填--output输出图片路径output/image.png--width图片宽度800--height图片高度400--bg背景颜色十六进制格式#2c3e50--color文字颜色十六进制格式#ffffff--font中文字体路径自动查找2. 图片处理运行命令python scripts/process_image.py --input input.png --output output/result.png --width 600 --format JPEG --watermark Copyright3. 批量生成运行命令python scripts/batch_generate.py --config config.json配置文件格式[ { text: 封面图, output: output/001.png, width: 1200, height: 630, bg: #1abc9c, color: #ffffff } ]注意事项如果出现中文乱码必须通过 --font 参数指定中文字体。所有脚本都依赖 Pillow运行前请确认安装pip install Pillow。这样一份 SKILL.md已经把时机、命令、参数、常见坑都交代清楚了。Agent 拿到之后基本不会出现“不知道用什么命令”的问题。 ### 4.3 编写文字转图片脚本 在 image-skill/scripts/generate_image.py 中写入 python # 文件路径image-skill/scripts/generate_image.py # 功能将指定文字渲染到一张纯色背景图片上 import argparse import os from PIL import Image, ImageDraw, ImageFont def find_font(): 根据当前系统查找可用的中文字体找不到返回 None font_candidates [ # Windows C:/Windows/Fonts/msyh.ttc, C:/Windows/Fonts/simhei.ttf, # macOS /System/Library/Fonts/PingFang.ttc, # Linux /usr/share/fonts/truetype/wqy/wqy-microhei.ttc, ] for font_path in font_candidates: if os.path.exists(font_path): return font_path return None def main(): parser argparse.ArgumentParser(description文字转图片生成器) parser.add_argument(--text, requiredTrue, help要绘制的文字) parser.add_argument(--output, defaultoutput/image.png, help输出图片路径) parser.add_argument(--width, typeint, default800, help图片宽度) parser.add_argument(--height, typeint, default400, help图片高度) parser.add_argument(--bg, default#2c3e50, help背景颜色如 #2c3e50) parser.add_argument(--color, default#ffffff, help文字颜色如 #ffffff) parser.add_argument(--font, defaultNone, help中文字体路径默认自动查找) args parser.parse_args() # 字体处理优先使用手动指定的字体其次自动查找 font_path args.font or find_font() if not font_path: print([ERROR] 未找到可用中文字体请使用 --font 参数指定字体文件路径) return # 确保输出目录存在 output_dir os.path.dirname(args.output) if output_dir: os.makedirs(output_dir, exist_okTrue) # 创建画布 image Image.new(RGB, (args.width, args.height), colorargs.bg) draw ImageDraw.Draw(image) # 根据图片尺寸动态计算字体大小 font_size min(args.width, args.height) // 8 try: font ImageFont.truetype(font_path, font_size) except Exception as e: print(f[ERROR] 字体加载失败: {e}) return # 计算文字居中位置 bbox draw.textbbox((0, 0), args.text, fontfont) text_width bbox[2] - bbox[0] text_height bbox[3] - bbox[1] x (args.width - text_width) / 2 - bbox[0] y (args.height - text_height) / 2 - bbox[1] # 绘制文字并保存 draw.text((x, y), args.text, fontfont, fillargs.color) image.save(args.output) print(f[OK] 图片已生成: {args.output}) if __name__ __main__: main()这段代码的关键点有三个字体自动查找不同系统字体路径差异很大自动查找机制可以避免用户每次手动指定。文字居中算法使用textbbox计算文字的实际像素宽高再做偏移确保中文居中也准确。目录自动创建如果output目录不存在脚本会自动创建避免保存时报错。4.4 编写图片处理脚本在image-skill/scripts/process_image.py中写入# 文件路径image-skill/scripts/process_image.py # 功能对图片进行缩放、裁剪、加水印、格式转换 import argparse import os from PIL import Image, ImageDraw, ImageFont def add_watermark(image, text, font_pathNone): 给图片添加简单的文字水印 watermark image.convert(RGBA) layer Image.new(RGBA, watermark.size, (0, 0, 0, 0)) draw ImageDraw.Draw(layer) font_size watermark.size[0] // 20 font_path font_path or C:/Windows/Fonts/arial.ttf try: font ImageFont.truetype(font_path, font_size) except Exception: font ImageFont.load_default() # 水印位置右下角带一点边距 bbox draw.textbbox((0, 0), text, fontfont) text_width bbox[2] - bbox[0] text_height bbox[3] - bbox[1] x watermark.size[0] - text_width - 20 y watermark.size[1] - text_height - 20 draw.text((x, y), text, fontfont, fill(255, 255, 255, 180)) return Image.alpha_composite(watermark, layer).convert(RGB) def main(): parser argparse.ArgumentParser(description图片处理工具缩放、裁剪、水印、格式转换) parser.add_argument(--input, requiredTrue, help输入图片路径) parser.add_argument(--output, requiredTrue, help输出图片路径) parser.add_argument(--width, typeint, defaultNone, help目标宽度) parser.add_argument(--height, typeint, defaultNone, help目标高度) parser.add_argument(--watermark, defaultNone, help水印文字) parser.add_argument(--format, defaultNone, help输出格式如 JPEG、PNG、WEBP) args parser.parse_args() if not os.path.exists(args.input): print(f[ERROR] 输入图片不存在: {args.input}) return # 打开图片并转换为 RGB 模式避免部分格式出现通道问题 image Image.open(args.input).convert(RGB) # 缩放保持比例的情况下调整尺寸 if args.width and args.height: image image.resize((args.width, args.height), Image.LANCZOS) elif args.width: ratio args.width / image.size[0] image image.resize((args.width, int(image.size[1] * ratio)), Image.LANCZOS) elif args.height: ratio args.height / image.size[1] image image.resize((int(image.size[0] * ratio), args.height), Image.LANCZOS) # 添加水印 if args.watermark: image add_watermark(image, args.watermark) # 保存输出 output_dir os.path.dirname(args.output) if output_dir: os.makedirs(output_dir, exist_okTrue) if args.format: save_format args.format.upper() else: ext os.path.splitext(args.output)[1].lower().replace(., ) save_format ext if ext in [JPEG, PNG, WEBP, BMP] else PNG image.save(args.output, formatsave_format) print(f[OK] 图片处理完成: {args.output}) if __name__ __main__: main()这个脚本提供了三个实用能力按宽或高等比缩放不会把图片拉变形。右下角添加水印适合自动化打码场景。格式转换输出时会根据文件后缀或--format参数自动判断格式。这里使用了Image.LANCZOS作为缩放算法比默认的最近邻插值效果更好适合图片从大图缩小到小图的场景。4.5 编写批量生成脚本在image-skill/scripts/batch_generate.py中写入# 文件路径image-skill/scripts/batch_generate.py # 功能根据 JSON 配置文件批量生成图片 import argparse import json import os from generate_image import main as generate_main def load_config(config_path): 读取 JSON 配置文件 if not os.path.exists(config_path): raise FileNotFoundError(f配置文件不存在: {config_path}) with open(config_path, r, encodingutf-8) as f: return json.load(f) def main(): parser argparse.ArgumentParser(description批量生成图片) parser.add_argument(--config, requiredTrue, helpJSON 配置文件路径) args parser.parse_args() try: tasks load_config(args.config) except Exception as e: print(f[ERROR] 读取配置文件失败: {e}) return if not isinstance(tasks, list): print([ERROR] 配置文件格式应为数组例如 [{...}, {...}]) return total len(tasks) for index, task in enumerate(tasks, start1): print(f[INFO] 正在生成第 {index}/{total} 张图片: {task.get(text, )}) try: # 复用 generate_image.py 的命令行解析逻辑 import sys argv [ generate_image.py, --text, task.get(text, ), --output, task.get(output, output/image.png), --width, str(task.get(width, 800)), --height, str(task.get(height, 400)), --bg, task.get(bg, #2c3e50), --color, task.get(color, #ffffff), ] if task.get(font): argv [--font, task[font]] # 备份并替换 sys.argv old_argv sys.argv sys.argv argv generate_main() sys.argv old_argv except Exception as e: print(f[ERROR] 第 {index} 张图片生成失败: {e}) print(f[OK] 批量生成完成共 {total} 张图片) if __name__ __main__: main()这个脚本通过复用generate_image.py的入口函数减少重复代码。配置文件中的每一个对象就是一张待生成图片的完整参数。需要注意一点脚本内部直接修改了sys.argv来复用命令行函数这种写法在独立脚本中是可行的但如果你后续把功能做复杂了更推荐把核心绘制逻辑抽成独立的工具函数而不是通过命令行参数互相调用。4.6 在 Agent 中加载 Skill代码写完之后最后一步是把整个image-skill目录放到 Agent 能扫描到的位置。不同工具差异较大具体操作请以你使用的工具文档为准。以常见的项目本地 Skill 目录为例你的项目结构应该是这样image-skill-project/ ├── skills/ │ └── image-skill/ │ ├── SKILL.md │ ├── scripts/ │ │ ├── generate_image.py │ │ ├── process_image.py │ │ └── batch_generate.py │ ├── templates/ │ └── output/ ├── venv/ └── config.json启动 Agent 后直接提问帮我把“CSDN 技术博客封面”这几个字生成一张宽 1200、高 630 的封面图背景用蓝色文字用白色。如果 Skill 配置正确Agent 会自动读取SKILL.md然后执行类似下面的命令python scripts/generate_image.py --text CSDN 技术博客封面 --output output/cover.png --width 1200 --height 630 --bg #2980b9 --color #ffffff整个过程用户只需要描述需求不需要关心脚本参数这就是 Skill 带来的体验提升。5. 运行与验证5.1 直接运行脚本验证在进入 Agent 环节之前建议先手动跑一遍脚本确保环境没问题。生成一张基础图片python image-skill/scripts/generate_image.py --text Hello Skill --output output/demo.png预期输出[OK] 图片已生成: output/demo.png然后去output目录下查看demo.png图片内容为深蓝背景上的白色文字 Hello Skill。测试中文python image-skill/scripts/generate_image.py --text 你好CSDN --output output/demo_cn.png如果输出正常说明字体查找逻辑生效了。如果出现中文乱码说明系统没有匹配到中文字体需要手动指定python image-skill/scripts/generate_image.py --text 你好CSDN --output output/demo_cn.png --font C:/Windows/Fonts/msyh.ttc测试图片处理python image-skill/scripts/process_image.py --input output/demo.png --output output/processed.jpg --width 600 --watermark CSDN预期得到一张宽度为 600、右下角带水印的 JPEG 图片。5.2 通过 Agent 自然语言调用验证确保虚拟环境已激活然后启动你使用的 Agent 工具。提问例句请使用 image-skill 把“GitHub 一周热点”生成一张 800x400 的图片放到 output 目录。观察 Agent 的行为是否识别到需要调用 image-skill是否读取了 SKILL.md是否执行了正确的 Python 命令是否返回了图片路径。如果 Agent 没有调用 Skill优先检查SKILL.md的description是否写清楚了触发条件同时确认 Skill 目录是否被正确扫描。5.3 预期结果说明一个配置良好的 Skill在使用时应该具备以下特征用户不需要知道脚本参数只需描述图片内容Agent 能主动维护输出目录生成失败时Agent 能根据错误信息尝试更换字体或调整参数用户最终能得到一个可访问的图片文件路径。如果以上目标都实现了说明你已经拥有一个可复用的图片生成 Skill。6. 常见问题与排查思路问题现象常见原因解决思路Skill 没有被 Agent 识别目录位置不对或 description 不清晰检查 skills 目录配置优化 SKILL.md 描述生成的中文变成方框未指定中文字体使用 --font 指定系统字体路径找不到字体文件字体路径写死或系统字体缺失在脚本中增加多系统候选路径图片太模糊直接使用小尺寸图放大或用了低质量缩放算法生成时调大 width/height使用 LANCZOS执行报错 FileNotFoundError输入图片路径不存在先检查文件是否真实存在再执行脚本batch 批量生成中断单张图片参数错误导致脚本退出代码中捕获单张任务的异常继续执行后续任务GitHub 项目下载慢或无法访问国内网络环境下访问 GitHub 不稳定使用 SSH 方式克隆或通过 Gitee 导入项目后下载ComfyUI 预览窗口不显示但图片已生成工作流中缺少 Preview Image 节点或只用了 Save Image 节点在保存节点后接入 Preview Image 节点或直接去 output 目录查看文件下面重点说几个高频问题。6.1 Skill 没有被 Agent 自动识别这是新手最常遇到的问题。可能原因有两类一是目录位置不对。很多 Agent 只扫描项目的skills目录如果你把 Skill 放在别的地方它自然找不到。解决办法是把image-skill目录移到项目根目录下的skills文件夹中并重启 Agent。二是SKILL.md的description描述太泛。比如只写“图片生成工具”模型无法准确判断什么时候用它。建议写成“当用户需要把文字转成图片、生成海报、制作封面、处理或转换图片时使用这个 Skill”这样触发准确率会明显提升。6.2 中文乱码问题Pillow 默认字体是英文位图字体直接绘制中文会显示方框。解决思路有两个在脚本里维护一个“多系统候选字体”列表运行时自动查找第一个存在的字体如果自动查找失败就通过--font参数手动指定。这个逻辑在generate_image.py里已经实现了如果你在使用过程中仍出现乱码请先确认系统里确实存在对应路径的字体文件。6.3 GitHub 项目下载慢或无法访问GitHub 热点项目通常是 Skill、Agent 或开源工具。很多人在安装时会遇到 GitHub 下载慢、打不开的问题。这里说几个安全且常用的方法使用 SSH 方式克隆在 GitHub 仓库页面复制 SSH 地址例如gitgithub.com:user/repo.git然后执行git clone gitgithub.com:user/repo.git。SSH 方式在部分网络环境中比 HTTPS 更稳定。通过 Gitee 导入项目如果 GitHub 实在访问不了可以把仓库导入到 Gitee再从 Gitee 克隆速度通常会快很多。合理使用镜像站部分 GitHub 开源镜像站可以下载单个文件或仓库压缩包但要注意选择信誉良好的站点避免下载到被篡改的脚本。这里特别提醒不要从非官方渠道获取所谓“原版”“无删减版”资源安全风险极高而且很可能夹带恶意脚本。6.4 生成出来的图片太小、不够清晰Skill 脚本本身是按参数生成图片的如果用户没有指定尺寸默认只有 800x400打印或做封面时会觉得模糊。解决办法是生成时明确要求大尺寸例如宽度 1920、高度 1080脚本中创建图片时使用目标尺寸缩放时使用Image.LANCZOS算法它比默认算法更平滑。如果你已经有了一张小图想放大而不明显失真单纯用 Pillow 效果有限。工程上可以接入 Real-ESRGAN 等超分工具但那是另一个话题了。6.5 ComfyUI 预览窗口不显示但图片已生成这个话题在热词里也出现了ConfyUI 在生成图片时预览窗口看不到预览图但图片实际上已经生成了。这通常和工作流节点的连接方式有关。ComfyUI 中有一个Preview Image节点专门用于在界面上预览图片而Save Image节点只负责保存文件。如果你只用了Save Image节点预览窗口自然没有内容。解决方法是检查工作流里是否拖入了Preview Image节点确认节点连接是否正确预览图生成后去 ComfyUI 的output目录查找文件。另外如果是在 headless无图形界面模式或远程环境下运行预览窗口可能因为网络原因无法回传图片这时候服务端日志里通常会有输出路径直接去看文件即可。7. 最佳实践与工程建议7.1 SKILL.md 的 description 要写“触发条件”而不是“功能清单”大模型不是搜索引擎它不会去解析你文件里的每个函数。它主要通过description来判断要不要调用这个 Skill。所以描述应该写成当用户需要把文字转成图片、生成海报、制作封面、处理或转换图片时使用这个 Skill。而不是这是一个基于 Pillow 的图片处理工具包含三个 Python 脚本。后者功能上没错但对模型来说信息量不足很容易导致误用或漏用。7.2 路径处理要统一在 Skill 脚本中路径问题几乎是必踩的坑。建议遵守以下几条脚本内部统一使用相对于 Skill 根目录的路径而不是相对于“当前执行目录”的路径所有输出统一写入output/目录运行前判断输入文件是否存在如果脚本需要被 Agent 从不同路径调用建议用os.path.dirname(__file__)获取脚本所在目录再拼接其他资源路径。例如import os SCRIPT_DIR os.path.dirname(os.path.abspath(__file__)) PROJECT_DIR os.path.dirname(SCRIPT_DIR) FONT_DIR os.path.join(PROJECT_DIR, fonts) OUTPUT_DIR os.path.join(PROJECT_DIR, output)这样无论从哪里执行脚本资源路径都是稳定的。7.3 环境依赖要显式声明Skill 运行在 Agent 的工作环境中但这个环境不一定和你本地开发环境一致。建议在 Skill 目录里放一个requirements.txtPillow10.0.0并在SKILL.md里写明首次使用前请执行pip install -r requirements.txt这样做的好处是即使换了一台机器Agent 也能根据文档完成依赖安装。7.4 日志输出要规范Agent 无法“看到”图片它只能通过命令行输出来判断脚本是否成功。所以脚本的日志要设计得对 Agent 友好成功时输出[OK] 图片已生成: 具体路径失败时输出[ERROR] 失败原因不要只输出一大段堆栈信息因为模型很难从中提取关键信息。如果脚本有多个步骤尽量加上[INFO] 正在执行...的提示这样 Agent 中途出问题也能及时发现。7.5 安全与合规边界图片生成能力本身是中性的但接入 Skill 后它可能会被 Agent 自动调用所以必须注意边界问题。第一不要生成违法、侵权、暴力、色情等不良内容。Skill 在SKILL.md中可以写清楚使用边界Agent 在调用时也会被底层模型的安全策略限制。作为开发者不要在脚本里加入“绕过审核”“无限制生成”之类的功能这对项目和用户都是风险。第二涉及用户上传的图片时不要轻易把图片发送到第三方 API。优先在本机完成处理保护隐私数据。第三如果用到了外部模型或在线服务一定要确认数据合规和调用权限。不要使用来源不明的接口避免账号泄漏或法律风险。7.6 Skill 与 Agent 工具的版本适配不同 Agent 工具对 Skill 的识别方式还在快速迭代。例如 Claude Code、Codex、OpenCode 等虽然都借鉴了类似的概念但目录约定、加载机制、配置文件名可能不同。因此在一个工具上调试通过的 Skill换到另一个工具时不一定能直接使用。建议以你正在使用的 Agent 官方文档为准保持SKILL.md的 frontmatter 字段尽量标准实际项目中把 Skill 放在一个独立仓库里管理按需复制到不同项目关注 Agent 版本更新日志及时适配新机制。8. 总结与下一步这篇文章从一个 GitHub 热点话题切入完整拆解了“Skill 图片生成”的原理与落地方式。现在你已经掌握了Skill 的本质面向 Agent 的能力包包含SKILL.md、脚本和资源文件图片生成 Skill 的完整目录结构三个核心脚本文字转图片、图片处理、批量生成如何编写一份能被 Agent 正确识别的SKILL.md常见问题的排查方法包括中文乱码、路径问题、GitHub 下载慢和 ComfyUI 预览问题。下一步可以往两个方向继续深入。如果你对 Agent 本身感兴趣可以去研究 Claude Code、Codex、OpenCode 等工具的 Skill 加载机制尝试为不同工具编写可复用的通用 Skill。图片生成只是其中一个例子你还可以扩展出数据库操作 Skill、文件批处理 Skill、爬虫 Skill 等。如果你更关注图片生成效果则可以继续学习 ComfyUI API 封装、Stable Diffusion 模型调用、超分辨率工具集成等。把这些能力也封装成 Skill 后你就能做到“一个入口完成从提示词到高质量图片的完整闭环”。最后如果你在配置 Skill 时遇到问题可以先用最简单的脚本跑通再逐步加功能。Skill 的价值在于让复杂事情变得可复用前提是它足够稳定。希望这篇实战教程能帮你省下一些折腾的时间。