从零构建一个可复用的 Agent Skill:结构设计、渐进式披露与脚本绑定

举报
yd_235984788 发表于 2026/10/27 11:58:14 2026/10/27
【摘要】 把一段反复失效的长 Prompt 拆成三层:领域知识写进 SKILL.md,确定性逻辑固化成脚本,触发条件交给 frontmatter description。本文用可运行的 Python 示例讲清 Agent Skill 的工程化结构、渐进式披露的调优技巧,以及三个真实踩过的坑。

一、问题:为什么 Prompt 复用总是失效

用 AI 编码助手做过一段时间重复工作之后,几乎都会遇到同一个困境:明明上次那段 Prompt 效果很好,这次再粘贴一遍,输出格式又歪了。

原因不复杂。一段长 Prompt 里混杂了三类完全不同的东西:

  • 稳定的领域知识:这个业务的固定流程、命名规范、字段清单
  • 易变的上下文:这次的需求细节、这次的文件路径
  • 确定性逻辑:拼字符串、算日期、转格式、读文件

把三者塞在同一段自然语言里,模型每次都要重新"理解"一遍前三类中本该固化的部分。上下文一长,注意力就被稀释,格式约束最先失效。

Skill 的价值就在于把这层固化下来:领域知识和流程写成文件,确定性逻辑写成脚本,模型只负责判断和编排。

二、目录结构:三层分离

一个可维护的 Skill,推荐按下面这个结构组织:

my-skill/
├── SKILL.md              # 入口:元信息 + 主干流程
├── scripts/
│   ├── build.py          # 确定性逻辑
│   └── validate.py       # 结果校验
├── references/
│   ├── template-a.md     # 按需加载的参考资料
│   └── template-b.md
└── assets/
    └── logo.png          # 输出素材

关键在于 SKILL.md 只放主干和路由,不放大段模板正文。

一个反例是把上千行的文档模板直接贴进 SKILL.md。结果是:每次调用这个技能,这上千行都会进入上下文,占用预算,而其中大部分内容这次根本用不上。

正确做法是让 SKILL.md 告诉模型"什么情况下读哪个文件",正文留在 references/ 里,命中场景时再读。这就是所谓的渐进式披露。

三、渐进式披露:description 决定一切

SKILL.md 的 frontmatter 是整个技能最重要的一段文字:

---
name: release-plan-generator
description: 根据固定模板生成产品上线方案文档,输出 .docx。
  当用户需要编写上线方案、发布方案、投产计划,或提供 PRD 要求产出
  上线相关文档时使用。输入包含产品名称、上线时间、涉及系统、
  回滚方案要点。
---

模型在决定"要不要加载这个技能"时,看到的只有这段 description。它同时承担两个职责:

  1. 召回:用户说"帮我写个上线方案"时能被命中
  2. 排他:用户说"帮我写个周报"时不能被误命中

这两者的调优方向正好相反,所以写 description 有个实用技巧——用"触发场景 + 排除条件"双段式:

当用户需要 XXX 时使用。不适用于 YYY(应走 ZZZ 技能)。

实践中遇到的典型问题:

  • 太宽:description 写成"处理文档相关任务",几乎任何文档请求都会命中,导致技能里那套模板约束污染无关任务。
  • 太窄:只写"生成上线方案 docx",用户说"写个投产计划"就召不回来了,因为术语没覆盖。
  • 缺输入要求:没写清需要哪些参数,模型会带着缺失信息进入流程,中途反复追问,体验很差。

第三点最容易被忽略。把"必需输入"写进 description,等于给调用方一个明确的准入契约。

四、脚本绑定:确定性的事别交给模型

技能里最值得写脚本的,是那些"有唯一正确答案"的环节。

举个具体例子:生成上线方案要计算变更窗口。人工算很容易错,模型算更容易错——它会在心里做加减法,然后把 22:00 到次日 02:00 的时长说成"5 小时"。

这类逻辑应该固化成脚本:

# scripts/window.py
from datetime import datetime, timedelta
import sys, json

def calc_window(start: str, duration_hours: float) -> dict:
    """start 格式: 2026-10-27T22:00"""
    s = datetime.fromisoformat(start)
    e = s + timedelta(hours=duration_hours)
    return {
        "start": s.isoformat(),
        "end": e.isoformat(),
        "crosses_midnight": s.date() != e.date(),
        "human": f"{s:%m月%d日 %H:%M} — {e:%m月%d日 %H:%M}",
    }

if __name__ == "__main__":
    print(json.dumps(
        calc_window(sys.argv[1], float(sys.argv[2])),
        ensure_ascii=False, indent=2))

然后在 SKILL.md 里用一句话指路:

计算变更窗口时,必须执行 scripts/window.py <起始时间> <时长小时>,不要自行推算。

加上"不要自行推算"这句很关键。只写"可以用脚本算",模型有时仍会选择自己算。强制语气的约束 + 明确的调用方式,命中率会高很多。

同理,格式校验、字段补齐、文件重命名,都应该脚本化。判断留给模型,计算留给代码。

五、踩过的三个坑

坑一:脚本路径用相对路径

SKILL.md 里写 python scripts/build.py,一旦工作目录不是技能根目录就找不到文件。稳妥写法是显式说明"相对于技能根目录",或者在脚本里自己做 os.chdir(os.path.dirname(__file__))。

坑二:输出格式只靠文字约束

"请输出 Markdown 表格"这种约束,在段落变多之后经常失效。更可靠的方式是给一个最小骨架示例:

| 阶段 | 负责人 | 开始 | 结束 |
|---|---|---|---|
| 预检查 | <填写> | <填写> | <填写> |

有骨架比有形容词有效得多。

坑三:技能里塞了两个目标

一个技能里同时写"生成文档"和"美化文档",模型容易在生成阶段就开始纠结排版,反而两件事都做不好。一个技能一个目标,需要组合就在编排层拆成两个技能串起来。

六、小结

Skill 的工程化,本质是把一段混沌的 Prompt 拆成三个明确的部分:

内容类型 载体 由谁处理
领域知识与流程 SKILL.md 主干 + references/ 模型阅读后理解
确定性逻辑 scripts/ 代码精确执行
输入契约与触发条件 frontmatter description 模型路由判断

拆清楚之后,重复任务从"每次重新解释"变成"每次只喂变量"。这才是 Skill 相对裸 Prompt 的真正增量——不是让模型更聪明,而是让上下文更干净。


以上代码在 Python 3.13 + 标准库环境下验证可运行,无第三方依赖。

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

评论(0)

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

全部回复

上滑加载中

设置昵称

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

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

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