从零构建一个可复用的 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。它同时承担两个职责:
- 召回:用户说"帮我写个上线方案"时能被命中
- 排他:用户说"帮我写个周报"时不能被误命中
这两者的调优方向正好相反,所以写 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 + 标准库环境下验证可运行,无第三方依赖。
- 点赞
- 收藏
- 关注作者
评论(0)