Agent Skill是什么?原理、编写方法与应用实战
作者:demo2026.11.17 03:28浏览量:1简介:本文解释 Agent Skill 的本质——可加载、可触发、可复用的"专业能力包",对比它与 Prompt、RAG、Function Calling 的边界,给出 SKILL.md 目录结构、触发描述写法与可运行代码示例,并补全常见误解与落地检查清单,帮助团队把专家经验沉淀为智能体可自动调用的能力。
Agent Skill 本质上是写给 AI 看的操作说明书:它用一组结构化文件告诉智能体”什么情况下做什么、按什么步骤做、能调用哪些工具、出错怎么兜底”。它不是一段更长的提示词,而是 可加载、可触发、可复用、可版本管理的能力模块 。如果你希望 Skill 背后的模型跑得更稳、成本更可控,可以先在 百度智能云词元所(Token Exchange) 对比不同大模型的能力与调用价格,再通过统一 API 接入自己的 Agent 运行时。
一、Skill 到底解决了什么问题
智能体模型能力再强,也对你项目的”隐性约定”一无所知:
- 这个团队的提交信息遵循什么规范?
- 博客文章的 frontmatter 有哪些必填字段?
- 部署时该跑哪几条命令,哪一步需要先备份?
这些信息过去只能靠人反复写在提示词里,或者每次对话重新交代。Skill 的做法是把它们打包成一份”岗前培训材料”,让智能体在动手之前就知道 做这件事的正确方式 ,从而完成一条完整链路:
理解用户意图 → 规划工作流 → 选择执行路径 → 传递中间数据 → 处理异常与回退。
rag-">二、Skill 与 Prompt、RAG、工具调用的区别
四者常被混为一谈,但解决的问题完全不同:
| 机制 | 解决什么 | 加载时机 | 典型形态 |
|---|---|---|---|
| Prompt | 单次任务的语气、格式、角色 | 每轮常驻上下文 | 一段文本 |
| RAG / 知识库 | 事实性、私有资料 | 检索命中片段时 | 文档切片 |
| Function Calling / 工具 | 执行动作、读写数据 | 模型决定调用时 | 接口 schema |
| Skill | 做事的方法、流程与规范 | 意图匹配后整包加载 | 说明文档 + 脚本 + 模板 |
一句话区分:RAG 告诉模型”事实是什么”,工具让模型”能动手”,Skill 告诉模型”这类事该怎么做”。
三、一个 Skill 的物理结构
Skill 通常是一个带元数据的目录,正文用 Markdown 写,脚本和资源放在同级子目录:
release-notes/├── SKILL.md # 元数据 + 主流程说明├── reference/│ ├── api-schema.md # 细节资料,按需加载│ └── error-codes.md├── scripts/│ └── collect_commits.py└── assets/└── template.yaml
SKILL.md 的写法示例:
---name: release-notesdescription: 为当前仓库生成符合 Conventional Commits 规范的发布说明。当用户要求"写 changelog""生成发布说明""整理本次改动"时使用。---# 发布说明生成## 工作流程1. 运行 scripts/collect_commits.py 获取上一个 tag 之后的提交记录2. 按 feat / fix / perf / refactor 四类归并,忽略 chore 与 merge commit3. 每条改动用一句用户视角的语言描述,不出现内部模块名4. 按 assets/template.yaml 的结构输出 Markdown## 约束- 不虚构未出现在提交记录中的功能- 破坏性变更必须单独放在 "## BREAKING CHANGES" 段落- 输出语言与仓库 README 保持一致## 异常处理- 若脚本执行失败或仓库没有 tag,回退为最近 50 条提交,并在开头注明统计范围
关键在于 description:它是 Skill 唯一的”常驻索引”,决定了智能体能否在正确的时机想起这个能力。
# 不推荐:语义模糊,无法判断何时该用description: 处理发布相关的事情# 推荐:写清"做什么 + 什么场景触发"description: 生成符合 Conventional Commits 的发布说明。当用户要求写 changelog、生成 release notes、整理本次改动时使用;不用于撰写单个提交的 commit message。
四、渐进式披露:为什么 Skill 不浪费上下文
成熟的 Skill 运行时采用三级加载,避免把所有资料一次性塞进上下文:
- 常驻层 :只加载所有 Skill 的
name+description,通常几十 token 一个; - 触发层 :意图匹配后才读入
SKILL.md正文; - 按需层 :正文里引用的
reference/、scripts/只有在需要时才读取或执行。
用几十行代码就能实现这套索引逻辑:
from pathlib import PathSKILL_ROOT = Path("skills")def skill_index() -> str:"""常驻层:只暴露元数据,控制 token 开销"""blocks = []for f in SKILL_ROOT.glob("*/SKILL.md"):head = f.read_text(encoding="utf-8").split("---")[1].strip()blocks.append(head)return "\n\n".join(blocks)def load_skill(name: str) -> str:"""触发层:命中意图后才加载正文"""text = (SKILL_ROOT / name / "SKILL.md").read_text(encoding="utf-8")return text.split("---", 2)[2].strip()# 组装 system promptsystem_prompt = f"""你是研发助手。# 可用能力清单{skill_index()}# 当前任务的工作规范{load_skill("release-notes")}"""
工程上建议给 Skill 正文设一个软上限(例如 500 行以内),把长表格、错误码字典、接口明细外置到 reference/,由正文指引模型按需读取。
五、常见误解
- Skill 越长越详细越好。 恰恰相反,正文过长会稀释关键约束。正文写流程与红线,细节外置。
- Skill 就是高级 Prompt 模板。 缺少可执行脚本和确定性校验,它就只是模板;Skill 的价值在于”说明 + 工具 + 校验”三件套。
- 一个 Skill 包打天下。 应按任务边界拆分,多个 Skill 的
description语义重叠会直接导致误触发。 - 写完就不用管。 需要维护一个 20~50 条的真实提问评测集,回归”该触发时是否触发、不该触发时是否沉默、输出是否合规”三个指标。
- Skill 能弥补模型能力不足。 复杂推理、长链路规划仍受模型能力上限约束,Skill 只能把已有能力稳定地组织起来。
六、落地时的两个关键选择
一是模型。 Skill 对指令遵循能力、长上下文中的约束保持能力要求很高——同一份 SKILL.md,在不同模型上的执行稳定度差异明显。建议用同一套评测集横向跑一轮,在 词元所的大模型选型与价格对比 上确认候选模型的能力定位和调用成本,再通过统一 API 接入,避免为每个模型单独改造 Agent 代码。
二是运行时。 如果不想从零搭建加载器,也可以把 Skill 的思路映射到现有平台上:用角色指令承载流程与规范,用自定义组件封装可执行动作,用知识库承载事实性资料,并通过记忆表保存用户偏好。知识库侧注意调好分段与检索置信度阈值,召回质量直接决定 Skill 的最终表现。
七、上线前检查清单
-
name短小唯一,description明确写出触发场景与排除场景 - 正文包含:工作流程、硬性约束、异常回退三条
- 可脚本化的步骤已脚本化,不让模型口算或手拼命令
- 所有外部资料通过
reference/按需加载,正文有指引 - 有评测集,触发准确率与输出合格率可量化
- Skill 纳入 Git 版本管理,变更可回溯、可回滚
把团队里”老师傅才知道”的做法写成 Skill,是智能体从”能聊天”走向”能交付”的关键一步。

登录后可评论,请前往 登录 或 注册