外部 Agent Skill 书写指南一、什么是 SkillSkill 是一份给其他 Agent 使用的「说明书」告诉它什么时候该调用触发场景怎么调用执行方式预期产出输出格式Skill 不是给人类用户的教程也不是 Agent 的内部提示词而是Agent 与 Agent 之间的接口契约。二、Skill 的标准结构skill-name/ ├── SKILL.md ← 唯一必需文件说明书 └── scripts/ ← 可选脚本实现目录 └── main.py命名规则skill 目录名同时也是 frontmattername字段必须匹配^[a-z0-9][a-z0-9-]{0,62}$- 仅小写字母 数字 连字符- 必须以字母或数字开头- 不以连字符开头/结尾- 长度 ≤ 63 字符- 这是 Trae / Claude / Qoder 等主流平台共用的安全约束示例invoice-extractor、skill-reviewer、pdf-mergerSKILL.md 由两部分组成| 部分 | 位置 | 作用 ||—|—|—||FrontmatterYAML | 文件头部---块内 | 触发元数据Agent 据此判断要不要加载正文 ||正文Markdown | Frontmatter 之后 | 详细的输出列、依赖、运行方式、注意事项 |脚本放在哪里推荐放scripts/目录与 SKILL.md 同级invoice-extractor/ ├── SKILL.md └── scripts/ └── invoice_to_excel.py不要把完整脚本内嵌在 SKILL.md 的代码块里。原因SKILL.md 会变得臃肿一个中等脚本 10 KBAgent 加载慢同一份代码在两处维护容易不同步别人拿到 SKILL.md scripts/ 目录即可直接使用无需先复制代码三、Frontmatter 怎么写---name:skill-namedescription:功能描述一句话 触发场景什么情况下调用。要短控制在 200 字以内。version:1.0.0---字段说明| 字段 | 必填 | 说明 ||—|—|—||name| ✅ | 见上文命名规则同时也用作目录名 ||description| ✅ | 触发关键词描述 200 字 ||version| 推荐 | Semver 格式MAJOR.MINOR.PATCH便于版本管理与升级判断 ||dependencies| 可选 | 显式声明依赖包及版本如pypdf3.0,6.0避免环境差异导致失败 |description 怎么写关键点description是 Agent 唯一会扫到的元数据必须同时回答做什么和何时用。不要写长句子解释工作原理Agent 只看它来判断要不要加载正文。正面例子description: 从电子发票 PDF 提取字段并导出 Excel。当用户提供 PDF 路径或含电子发票的目录并要求报销登记时调用。反面例子description: 这是一个发票处理工具 ← 没说明何时用 description: 用 Python 解析 PDF 然后写入 Excel ← 太技术version 怎么用调用 Agent 拿到 skill 后可通过version判断是否需要更新破坏性变更 → 升级 MAJOR新增功能/字段 → 升级 MINORBug 修复 → 升级 PATCH示例1.0.0首个稳定版1.1.0新增行程单合并功能1.1.1修复某发票版式解析失败四、正文怎么写核心原则让 Agent 直接照做不要让 Agent 再去拼脚本Agent 拿到 Skill 后的预期行为是照着 SKILL.md 的命令直接执行不是读完后去研究 PDF、再写代码、再调试。要做到这一点正文里指向 scripts/ 下的脚本即可不必把代码贴出来。推荐章节顺序概述 — 一句话讲功能项目结构 — 列出目录、说明文件作用运行 — 一两条命令示例同时给 PowerShell 和 bash输出列 / 输出格式 — 让 Agent 知道结果长什么样依赖 — 安装命令注意事项 — 容错 / 边界情况 / 幂等性触发关键词 — 帮助 Agent 判断场景可选运行章节写法## 运行 PowerShellWindows powershell # 安装依赖首次需要 pip install pypdf openpyxl # 跑脚本路径相对于本 SKILL.md 所在目录 python scripts/invoice_to_excel.py D:\公司相关\发票 bashmacOS / Linux bash pip install pypdf openpyxl python3 scripts/invoice_to_excel.py /Users/me/invoices 可选第二参数指定输出路径 bash python3 scripts/invoice_to_excel.py in_dir out.xlsx 要点路径使用相对scripts/xxx.py让调用者无需知道机器特定目录给一两条最简命令即可不要列一堆调用方式路径示例用绝对路径方便理解但说明相对于 SKILL.md 目录同时给 PowerShell 和 bash避免跨平台失败五、避免的写法| ❌ 错误写法 | 为什么错 ||—|—|| 把完整脚本内嵌到 SKILL.md 代码块 | 让 SKILL.md 臃肿、难维护、同步风险 || 让 Agent “先读 PDF再写脚本” | 把 Skill 当教程用Agent 不会复用你的代码 || 详细写如何一步步操作 | Agent 已经有推理能力不需要你教它步骤 || 中英混杂 | 浪费 token统一一种语言 || 重复的标题/段落 | 同一信息只写一次 || 把 SKILL.md 写成 README | README 是给人看的SKILL.md 是给 Agent 看的 || description 长篇大论 | description 只用来判断要不要加载正文要短 || 用机器特定路径 | 让别的机器跑不了要相对路径 |六、自检清单写完一个 Skill 后逐条验证独立可运行解压 zip 后能否直接python scripts/xxx.py跑起来依赖最小化是否只依赖少数常见包是否在文档里给了pip install依赖版本明确依赖是否锁定了已验证的版本范围如pypdf3.0,6.0或提供requirements.txtdescription 简洁200 字内说明功能 触发场景路径相对化脚本路径是否相对 SKILL.md 所在目录如scripts/xxx.py不要绑定机器特定路径。SKILL.md 不臃肿正文是否保持简短 5 KB 为佳脚本是否独立放在scripts/命名合规目录名与name字段匹配^[a-z0-9][a-z0-9-]{0,62}$输出格式明确是否清楚说明输出列/字段含义退出码与输出约定脚本成功时返回 0、失败非 0错误信息输出到 stderr关键结果如输出文件路径输出到 stdout幂等性已声明重复运行同一输入会覆盖、跳过还是报错是否在注意事项里写明跨平台示例运行命令是否同时给了 PowerShell 与 bash 两种附测试样本是否提供一两个脱敏的小型测试样本调用者解压后能立刻跑通验证。失败可恢复脚本出错时是否会给出可读提示是否需要清理 Excel 占用重复内容已删除同一信息没在多处复述中英文统一全文一种语言语言匹配场景中文业务场景用中文 skill如电子发票“报销登记”英文业务场景用英文 skill。中英文混杂会降低触发关键词匹配精度。七、关于语言与 token英文 token 数通常比中文少英文单词约 1 token/词中文约 1.5-2 token/字。但 skill 是按场景匹配的不是按省 token优化中文业务场景里 description 写electronic invoiceAgent 触发识别会变差。取舍原则- 中文业务 → 用中文token 多花一些但触发精准- 英文业务 → 用英文省 token 也更地道- 中英文混杂 → 避免既不省 token 又损语义Frontmatter 用于触发判断触发后正文完整加载不同平台实现略有差异但通常不会前几次只读 frontmatter。八、脚本接口约定调用 Agent 需要明确的成功/失败信号才能继续动作。建议遵循下列约定| 通道 | 内容 | 用途 ||—|—|—||stdout| 关键结果如已生成: D:…\发票信息.xlsx | Agent 据此获取输出位置 ||stderr| 错误信息人类可读 | Agent 据此告知用户失败原因 ||exit code|0 成功非0 失败 | Agent 据此判断是否继续 |幂等性约定同一输入重复运行应默认覆盖输出文件而非追加或报错如行为不同例仅追加不覆盖必须在注意事项中明确说明invoice-extractor 即是覆盖行为每次运行会覆盖发票信息.xlsx错误处理建议输入路径不存在 → 退出码 1stderr 提示依赖缺失 → 启动时检查缺失时打印明确提示并退出部分字段解析失败 → 不退出把空值写入 Excel最后告知用户哪些字段需人工补九、依赖管理# 方式一直接装最新版不推荐用于生产pipinstallpypdf openpyxl# 方式二锁版本推荐pipinstallpypdf3.0,6.0openpyxl3.0,4.0# 方式三提供 requirements.txt# requirements.txt 内容# pypdf3.0,6.0# openpyxl3.0,4.0pipinstall-rrequirements.txtSKILL.md 中应写明已验证的版本范围。半年后某个包 breaking change 不会因为锁了版本而崩。十、测试样本建议随 skill 附带一两个脱敏的小型测试样本。目录约定invoice-extractor/ ├── SKILL.md ├── scripts/ │ └── invoice_to_excel.py └── tests/ ← 建议 ├── sample1.pdf ← 脱敏的测试 PDF ├── sample2.pdf └── README.md ← 说明预期输出调用者拿到后python3 scripts/invoice_to_excel.py tests/应该立即得到正确结果。如果失败说明环境/依赖有问题。样本要求文件名不包含真实公司名、税号、金额覆盖至少 2 种版式普通发票 增值税专票 / 发票 行程单 等体积小 200 KB便于分发十一、发布方式1. 单独 SKILL.md直接放到目标 IDE 的 skills 目录路径因平台而异| 平台 | 路径 ||—|—|| Trae |skills-dir/name/SKILL.md|| Claude |skills-dir/name/SKILL.md|| Qoder |skills-dir/name/SKILL.md|| 其他 | 查阅各自 IDE 文档 |通用形式把SKILL.md放进skills-dir/name/SKILL.mdscripts/与SKILL.md同级。2. 打成 zip 分发打包时排除调试文件、缓存、临时文件importzipfile,osfrompathlibimportPath srcPath(invoice-extractor)# skill 根目录outPath(invoice-extractor.zip)SKIP_DIRS{__pycache__,.git,_debug,tests}# 视情况保留 testswithzipfile.ZipFile(out,w,zipfile.ZIP_DEFLATED)asz:forroot,dirs,filesinos.walk(src):dirs[:][dfordindirsifdnotinSKIP_DIRS]forfinfiles:fullPath(root)/fiffull.suffixin{.pyc,.pyo}:continuez.write(full,arcnamefull.relative_to(src).as_posix())3. 维护策略脚本与 SKILL.md 解耦后只用维护scripts/下的源文件SKILL.md 只引用路径与版本号不会因脚本细节变动而过期每次发布新版本时同步更新version字段十二、本项目invoice-extractor示例invoice_extractor/ ← 仓库根目录 ├── README.md ├── skills/ │ ├── invoice-extractor/ ← Skill 1 │ │ ├── SKILL.md │ │ └── scripts/ │ │ └── invoice_to_excel.py │ └── skill-reviewer/ ← Skill 2审查其他 Skill │ ├── SKILL.md │ └── scripts/ │ └── review_skill.py ├── docs/ │ └── Skill写作指南.md ├── dist/ ← 分发包 │ ├── invoice-extractor.zip │ └── skill-reviewer.zip └── dev/ ← 开发调试按 skill 分目录 ├── _pack.py ├── invoice-extractor/ │ ├── scripts/ │ └── output/ └── skill-reviewer/ └── scripts/对照检查✅ SKILL.md 精简到 ~2.6 KB不内嵌脚本✅ 项目结构SKILL.mdscripts/invoice_to_excel.py职责分离✅ description 一句话讲清功能 触发场景77 字符✅ 依赖明确pip install pypdf openpyxl✅ 运行命令相对路径python scripts/invoice_to_excel.py dir✅ 输出列表格化Agent 容易解析✅ 退出码成功 0、失败非 0✅ 幂等每次覆盖发票信息.xlsx✅ 注意事项Excel 占用、未解析字段留空等边界情况✅ 触发关键词清单