AI Agent 技能(Skill)工程化指南:从 5 个开源项目里提炼的 8 条硬规范

举报
yd_274732647 发表于 2026/11/04 14:35:42 2026/11/04
【摘要】 多数人把 AI Agent 的 Skill 写成一段提示词,于是没有边界、没有验收标准、没有失败路径。本文对读五个开源项目的源码,提炼 8 条工程化规范:固定骨架、写清「不做什么」、不可逆操作的一票否决护栏、接口契约化、凭据与副作用隔离、目录即接口、演进协议、把主观判断拆成可判定命题,并附 10 项自查表与 7 条反模式。

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 共有):

  1. 技能目录内不含任何凭据 —— 没有 token、没有账号、没有个人绝对路径,可以安全分发
  2. 令牌永不落盘到会被提交的文件 —— 只用 --token 参数或环境变量传入
  3. 真实配置进 .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_stats
  • evolution/*.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 分钟耗时对比)为项目作者记录的真实执行结果。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。