AI Agent 技能(Skill)工程化指南:从 5 个开源项目里提炼的 8 条硬规范
AI Agent 技能(Skill)工程化指南:从 5 个开源项目里提炼的 8 条硬规范
本文不聊提示词技巧,只聊一件事:当你要把一项能力交给 Agent 长期、重复、无人值守地使用,Skill 应该怎么写才不像玩具。 素材来自五个真实开源项目的源码级对读:gitcode-issue-triage、SendmailSkills、PPTCraftSkill、AI 校园活动策划天团、excel-formula-explainer。它们风格各异,但在"怎么组织一个 Skill"上高度趋同——这种趋同不是巧合,是被坑出来的。
先分清两个概念
很多人心里的 Skill 长这样:
你是一个资深的 Excel 专家,请帮我分析用户上传的表格,找出错误并给出建议。
这是提示词。它的问题不在于短,而在于:没有边界(什么算错误?)、没有验收标准(怎么算完成?)、没有失败路径(出错怎么办?)、没有可复用资产(脚本、模板、知识库存在哪?)。
而那五个项目的 Skill 更像一份接口文档 + 一套可执行资产。差别相当于"口头交代一件事"和"交付一个带文档、带测试、带错误码的 CLI"。
下面八条,就是它们的共同做法。
规范一:SKILL.md 用固定骨架,不要自由发挥
所有项目都给 Skill 定了八段式结构,字段顺序一致:
---
name: <skill-name>
description: <英文简述,用于技能匹配>
version: <x.y.z>
metadata:
dependencies: [脚本与配置文件清单]
---
# Role — 角色定义(1–2 句)
# Persona — 人设特征(严谨 / 创意 / 谨慎)
# Core Responsibilities — 编号列表,明确职责边界
# Knowledge Base — 知识库路径(从配置文件读取)+ 检索策略
# Signal Protocol — 信号格式表(ACTIVATE / TASK_COMPLETE / ERROR)
# Workflow — 编号步骤,含脚本执行方式与输出路径
# Performance Rules — 性能约束(通常只有 Leader 有)
# Evolution Experiences — 自动生成的经验索引表
为什么必须固定? 因为 Agent 每次执行都要把这份文档读进上下文。结构固定意味着:
- 它可以跳过无关段落(要找输出路径就去 Workflow,不用通读)
- 人 review 时能一眼定位缺失项(没有 Signal Protocol?那就是没定义失败路径)
- 新增段落有位置可放,不会越写越乱
经验值:单份 SKILL.md 控制在 8–15KB。超过这个量,就该把细节拆进 references/——这也是它们都配了 references/runbook.md(执行走查表)和 references/analysis-guide.md(判定要素)的原因。
一句话:SKILL.md 是目录和契约,不是百科全书。
规范二:把"不做什么"写死,比写"做什么"更重要
这是多 Agent 项目最痛的一课。AI 校园活动策划天团里,每个角色的职责描述都长这样:
| 角色 | 职责 | 明确不负责 |
|---|---|---|
| Leader(统筹) | 解析输入、建任务 DAG、收集产出、委派整合 | 不执行任何具体模块 |
| 预算会计 | 检索预算标准 → 算费用 → 生成 Excel | 不负责风险,不负责文案 |
| 风险顾问 | 检索风险标准 → 识别四类风险 → 生成预案 | 不负责预算,不负责文案 |
| 宣传文案师 | 生成文案 + PPTX + 最终 HTML | 不负责预算,不负责风险 |
理由写得很直白:Leader 的 SKILL.md 已经要塞下"信息提取 + 信号协议 + 性能规则",再塞预算计算就会 Prompt 超长、执行质量下降。
更狠的是通信约束——每个成员的 SKILL.md 里都有 Communication Behavior Constraints,明确列出:
- PROHIBITED:不主动询问非自身领域的任务进度、不请求认领他人任务、不发"协调建议"
- REQUIRED:发出
TASK_COMPLETE后静默待命,只响应 Leader 分配的新任务
这条不是洁癖。实测中预算会计在任务已完成的情况下,还主动发了一条"HTML 整合进度如何",产生 2 次无效通信。作者的结论很锋利:
多 Agent 系统里,"好心办坏事"比"各扫门前雪"更浪费资源。
单 Agent 的 Skill 同样适用。excel-formula-explainer 就把边界写进了修复规则:只自动修两类(空单元格补 0、超行数收缩),循环引用、换引用目标、硬编码提取一律"只出建议,征询用户意图后改"。
能自动化的边界画在哪里,比自动化能力本身更能体现成熟度。
规范三:不可逆操作,必须有一票否决的护栏
gitcode-issue-triage 是做 issue 巡检的(识别灌水并关闭)。它把第一原则写成了不等式:
漏关一个无价值 issue 成本很低;误关一个真实缺陷报告,损害信任,还可能掩盖线上事故。
由此推出三条硬规则:
| 规则 | 实现 |
|---|---|
| 证据不足即放行 | 判定有分歧 → 归类 needs human,不做任何写操作 |
| 顺序不可颠倒 | 先回复 → 回读确认回复已落库 → 才关闭 → 再回读确认 state == closed |
| 护栏可一票否决 | 命中任何 veto 信号 → 直接拒绝关闭(退出码 5) |
这三条落到代码里,是一段不可打乱的执行序列:
1. 重读 issue;已关闭 → 跳过(幂等)
2. 载入评论;固定话术已存在 → 跳过回复(幂等)
3. 重跑安全护栏;被否决 → 退出码 5
4. 发布回复
5. 重新拉取评论,确认回复已落库;缺失 → 退出码 6 中止,不关闭
6. 关闭 issue,回读确认;仍打开 → 退出码 6
两个工程手法值得抄走:
① 写后回读(read-after-write verification)。 API 返回 200 不等于真的落库。每步写完重新读一次远端状态,把"静默失败"暴露出来。
② 幂等 + 断点续跑。 已关闭的跳过、已回复的只补关闭——所以中断后的唯一操作是"原样重跑",把一致性问题降维成无状态重试。
护栏本身也要精心设计。它的 veto 信号里最关键是"请求式表述 + 领域实质":
一条
是否支持 docker 部署、缺少 requirements.txt虽然极简,但在项目语境下是真实需求,绝不能被自动关闭。所以护栏要求领域实质(项目相关词汇或文件引用)才把请求式表述当作真实请求——这样裸愿望(如果支持apk就好了)和刷量话术(能不能拿积分)就不会借"支持/能不能"这几个字获得合法性。
这条规则的效果是可量化的:真实仓库 128 条开启 issue,判定无价值 68 条、保留 60 条,误关 0 条。
规范四:接口契约化——参数、返回值、退出码都要有语义
Agent 不该靠"读人类写的提示文案"判断成败。五个项目在这点上做法一致:
统一返回结构,永不抛异常(SendmailSkills):
{"ok": True, "message": "邮件已发送至 receiver@example.com"}
{"ok": False, "error": "SMTP 认证失败:授权码错误……"}
调用方只看 ok 字段,不需要 try/except。异常被收敛成人话错误,而不是把 traceback 甩给上层。
退出码承载语义(gitcode-issue-triage):
| 码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 网络错误 |
| 2 | 参数缺失 |
| 3 | 鉴权失败 |
| 4 | 资源不存在 |
| 5 | 护栏拒绝 |
| 6 | 写后验证失败 |
5 和 6 是刻意分开的:一个是"我拒绝执行"(保护性行为),一个是"我执行了但没生效"(需要人工介入)。混在一起,排障就只能靠猜。
自检脚本也用退出码表达结论(excel-formula-explainer 的 validate_template.py):任一检查项 FAIL 就 exit 1——所以它能直接接进 CI 当卡口。
再加一条:所有网络调用都要有超时。 SendmailSkills 里 smtplib.SMTP(..., timeout=30),避免网络抖动时脚本无限挂死。
规范五:凭据与副作用,必须物理隔离
安全不是靠"记得小心",是靠结构上不可能犯错。
凭据三条铁律(SendmailSkills / gitcode-issue-triage 共有):
- 技能目录内不含任何凭据 —— 没有 token、没有账号、没有个人绝对路径,可以安全分发
- 令牌永不落盘到会被提交的文件 —— 只用
--token参数或环境变量传入 - 真实配置进 .gitignore ——
config/accounts.json被忽略,只有accounts.example.json进仓库
再加一条可执行的自查:
grep -rE '[0-9a-f]{32,}|[A-Za-z]:[\\/]Users[\\/]' ./ # 期望无输出
副作用的四道闸,按从小到大的破坏力排列:
| 闸 | 做法 | 项目实例 |
|---|---|---|
| 只读优先 | 侦察阶段完全不需要凭据 | triage:公开仓库 list/show/评论读取均无令牌可用 |
| dry-run | 默认就是 dry-run,写文件要显式加参数 | excel:fix_excel.py 文件.xlsx 只打印计划;要写副本才加 -o,写回才加 --apply |
| 副本优先 | 输出到新文件,原文件不动 | excel:-o 文件_fixed.xlsx 被标为"推荐" |
| 自动备份 | 真要覆盖原件,先留后路 | excel:--apply 自动生成 .bak |
这个顺序是有讲究的:让"什么都不改"成为最容易做到的那一步。如果 dry-run 需要额外加参数,人就会跳过它。
规范六:目录结构就是接口
五个项目的目录长得几乎一样,因为它们解决的是同一类问题——能力需要被打包、被审查、被复用:
<skill>/
├── SKILL.md # 契约:frontmatter + 八段式
├── README.md # 给人看的说明
├── references/
│ ├── runbook.md # 执行走查表(逐步命令照抄 + 排查速查)
│ └── analysis-guide.md # 判定要素 + 报告输出模板
├── scripts/
│ ├── validate_template.py # 自检(不通过 exit 1)
│ ├── <cli>.py # CLI 薄壳:只做参数解析与打印
│ ├── <reader>.py # 读取与解析
│ ├── <graph>.py # 核心算法
│ ├── <analyzer>.py # 编排
│ └── <report>.py # 格式化输出
├── evolution/ # 演进经验(叙述式)
├── evolutions.json # 演进条目(结构化)
└── requirements.txt # 依赖锁版本
两个关键设计:
① 单一职责拆分 + CLI 与逻辑分离。 analyze_excel.py 只有 41 行,只做参数解析、校验、打印;真正的分析在 analyzer.py,图算法在 graph.py(200 行)。好处很实在:能力可以当库用,而不只是当命令用;检测逻辑和输出格式彻底解耦(想换成 JSON/Markdown 报告,不用碰算法)。
② 路径统一进配置,SKILL.md 里绝不写死。 这是被坑出来的。AI 校园活动策划天团初版把 Windows 绝对路径(D:\zhishiku\xxx.pdf)硬编码进了 SKILL.md,结果 Linux 下全线失效,换个环境要改 4 个文件里的几十处。修法三条:
- 所有路径写进
config.json - SKILL.md 只写"读取
config.json中knowledge_base.budget获取知识库路径" - 路径用正斜杠 + 相对路径,全平台通吃
于是换环境只换一个文件:本地 zhishiku/、生产 /data/event-planner/zhishiku/、容器 /app/zhishiku/。
规范七:让技能"越用越聪明"——演进协议
这是我认为最被低估的一条。四个项目都配了演进机制,结构完全一致:
双轨存储:
evolutions.json—— 结构化条目:id/source/timestamp/context/change/score/usage_statsevolution/*.md—— 按类型分文件(collaboration.md、workflow.md、constraints.md),从 JSON 生成,供 Agent 运行时阅读
source 只有三个合法值,这个设计很讲究:
| source | 含义 |
|---|---|
user_intent |
用户明确要求的改变 |
runtime_failure |
实际执行失败倒逼的修正 |
self_reflection |
自查/复盘得出的改进 |
闭环怎么走:SKILL.md 末尾自动生成 Experience Index 表(经验摘要 / 类型 / 评分 / 详情链接);Agent 执行前先查索引,命中匹配的经验就再读 evolution/*.md 详情。
还要管版本同步。 行为变更时,四个地方必须一起改:SKILL.md frontmatter 的 version、SKILL.md 标题里的 (vX.Y.Z)、evolutions.json 的 version、references/*.md 页头——而且用 validate_template.py 自动核对一致性。
机制的价值:它把"这次踩的坑"变成"下次的默认行为"。没有这一步,Skill 会一直原地踏步——同一类错误每周重犯一次。
规范八:把主观判断拆成可判定命题
这条来自 PPTCraftSkill(PPT 生成)。它要解决的问题是"AI 做的 PPT 不好看",而它的解法是把审美翻译成数值:
| 不可执行的指令 | 可执行的规范 |
|---|---|
| "排版要清晰" | 正文 ≥16px,单页 ≤14 行 |
| "颜色别太淡" | 对比度 ≥4.5:1,禁用 #B5B5B5 |
| "别太挤" | 行距 1.5,元素间距 ≥16px |
| "版式要丰富" | 10 页至少 6 种版式 |
左边是审美判断,只有人能拍板;右边是布尔判定,Agent 可以逐条自查。
这就是"能不能交给 Agent"的分水岭:不是模型行不行,而是你的要求能不能被判定。
顺便说,它还给了一条反直觉的改造优先级——版式 > 字体 > 图表 > 排列 > 配色。配色排最后。大多数人一提到"优化 PPT"就去换配色,而那是提升感知最小的动作。
反模式清单(这七条我都在真实项目里见过反面教材)
| # | 反模式 | 后果 |
|---|---|---|
| 1 | 把几百行脚本塞进 SKILL.md | Prompt 超长、上下文挤爆、改一行要重读全文 |
| 2 | 只写"你是某领域专家,请帮我做X" | 无边界、无验收标准、无失败路径 |
| 3 | 路径/端口/密钥硬编码 | 换环境全线崩;密钥进 Git 历史 |
| 4 | 没有 dry-run,直接改数据 | 一次手滑就不可逆 |
| 5 | 用自然语言传结构化数据 | 解析不稳定;跨 Agent 传文件内容还会撞参数上限(实测 400 Bad Request) |
| 6 | 用内联 write_file 写长脚本 |
同样撞参数上限。正解是"脚本预置 + 小幅修改 + 直接执行",每次改动 <2000 字符 |
| 7 | 没有返回结构/退出码 | 调用方只能读人类文案猜成败 |
第 5、6 条是同一个根因的两种表现:多 Agent / 工具调用都有参数大小限制,别把"内容"塞进消息里——传路径,传摘要。
一张自查表
给你的 Skill 打勾,全过才算能交付:
| # | 检查项 | 通过标准 |
|---|---|---|
| 1 | 结构 | frontmatter 齐全;八段式段落不缺;8–15KB |
| 2 | 边界 | 明确写了"不做什么",不只是"做什么" |
| 3 | 护栏 | 有不可逆操作?有一票否决 + 写后回读 + 幂等 |
| 4 | 契约 | 返回结构统一;退出码语义化;网络调用有超时 |
| 5 | 安全 | 目录无凭据;.gitignore 兜底;有 grep 自查命令 |
| 6 | 副作用 | dry-run 是默认;副本优先;覆盖前自动备份 |
| 7 | 目录 | references/ 有走查表;scripts/ 单一职责 + CLI 薄壳;依赖锁版本 |
| 8 | 路径 | 全进 config.json;正斜杠 + 相对路径 |
| 9 | 演进 | evolutions.json + evolution/*.md;版本四处同步;有自检脚本 |
| 10 | 可判定 | 验收标准是数值/布尔,不是形容词 |
结语
这五个项目教给我的最大一件事是:Agent 的能力上限,往往不取决于模型多强,而取决于你把需求定义得多精确。
- 写清"不做什么",它才不会越界;
- 设好一票否决,它才敢自动执行不可逆操作;
- 给出退出码,它才知道自己是不是真的成功了;
- 把"好看"翻译成 16px 和 4.5:1,它才能自己判断好不好。
所以下次写 Skill 前,先问自己一句:
如果这份文档交给一个能力很强但完全不了解你业务的实习生,他能不出错地执行吗?
能,那它就是一个合格的 Skill。
说明:本文为跨项目横向对比的原创工程总结,涉及的具体实现细节(护栏规则、退出码约定、演进协议、检测算法、目录规范)均来自对应开源项目的源码与文档;文中引用的实测数据(128/68/60 条 issue 判定、14→7 分钟耗时对比)为项目作者记录的真实执行结果。
- 点赞
- 收藏
- 关注作者
评论(0)