logo

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 写,脚本和资源放在同级子目录:

  1. release-notes/
  2. ├── SKILL.md # 元数据 + 主流程说明
  3. ├── reference/
  4. │ ├── api-schema.md # 细节资料,按需加载
  5. │ └── error-codes.md
  6. ├── scripts/
  7. │ └── collect_commits.py
  8. └── assets/
  9. └── template.yaml

SKILL.md 的写法示例:

  1. ---
  2. name: release-notes
  3. description: 为当前仓库生成符合 Conventional Commits 规范的发布说明。
  4. 当用户要求"写 changelog""生成发布说明""整理本次改动"时使用。
  5. ---
  6. # 发布说明生成
  7. ## 工作流程
  8. 1. 运行 scripts/collect_commits.py 获取上一个 tag 之后的提交记录
  9. 2. 按 feat / fix / perf / refactor 四类归并,忽略 chore 与 merge commit
  10. 3. 每条改动用一句用户视角的语言描述,不出现内部模块名
  11. 4. 按 assets/template.yaml 的结构输出 Markdown
  12. ## 约束
  13. - 不虚构未出现在提交记录中的功能
  14. - 破坏性变更必须单独放在 "## BREAKING CHANGES" 段落
  15. - 输出语言与仓库 README 保持一致
  16. ## 异常处理
  17. - 若脚本执行失败或仓库没有 tag,回退为最近 50 条提交,并在开头注明统计范围

关键在于 description:它是 Skill 唯一的”常驻索引”,决定了智能体能否在正确的时机想起这个能力。

  1. # 不推荐:语义模糊,无法判断何时该用
  2. description: 处理发布相关的事情
  3. # 推荐:写清"做什么 + 什么场景触发"
  4. description: 生成符合 Conventional Commits 的发布说明。当用户要求写 changelog、
  5. 生成 release notes、整理本次改动时使用;不用于撰写单个提交的 commit message。

四、渐进式披露:为什么 Skill 不浪费上下文

成熟的 Skill 运行时采用三级加载,避免把所有资料一次性塞进上下文:

  1. 常驻层 :只加载所有 Skill 的 name + description,通常几十 token 一个;
  2. 触发层 :意图匹配后才读入 SKILL.md 正文;
  3. 按需层 :正文里引用的 reference/、scripts/ 只有在需要时才读取或执行。

用几十行代码就能实现这套索引逻辑:

  1. from pathlib import Path
  2. SKILL_ROOT = Path("skills")
  3. def skill_index() -> str:
  4. """常驻层:只暴露元数据,控制 token 开销"""
  5. blocks = []
  6. for f in SKILL_ROOT.glob("*/SKILL.md"):
  7. head = f.read_text(encoding="utf-8").split("---")[1].strip()
  8. blocks.append(head)
  9. return "\n\n".join(blocks)
  10. def load_skill(name: str) -> str:
  11. """触发层:命中意图后才加载正文"""
  12. text = (SKILL_ROOT / name / "SKILL.md").read_text(encoding="utf-8")
  13. return text.split("---", 2)[2].strip()
  14. # 组装 system prompt
  15. system_prompt = f"""你是研发助手。
  16. # 可用能力清单
  17. {skill_index()}
  18. # 当前任务的工作规范
  19. {load_skill("release-notes")}
  20. """

工程上建议给 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,是智能体从”能聊天”走向”能交付”的关键一步。

发表评论

活动