Session 13:Skill——让 Agent 掌握可复用的任务执行方法
一个 Research Agent 需要完成研究报告时,除了搜索工具,还需要知道如何拆解研究问题、筛选来源、判断证据是否充分、处理相互矛盾的材料。
一、Skill 是什么
一个 Research Agent 需要完成研究报告时,除了搜索工具,还需要知道如何拆解研究问题、筛选来源、判断证据是否充分、处理相互矛盾的材料,以及按约定格式组织报告。
如果每次执行任务都把这些要求重新写进提示词,提示词会越来越长;不同任务又可能需要不同的操作规范。Skill 的思路,是把某一类任务经常使用的方法、约束和参考资料整理成可复用的内容,在需要时再交给 Agent。
常见的 Agent Skill 以一个目录为单位,核心文件通常是 SKILL.md。它可以包含任务说明、操作步骤、质量标准、输出格式,也可以附带参考文档和脚本。Skill 的具体加载和执行方式取决于宿主应用或 Agent 框架。
Skill 本身通常是一组任务指令和相关资源。它不必然是一个独立运行的 Agent,也不天然拥有执行代码或访问外部系统的权限。真正的工具调用仍然需要工具运行环境提供能力。
二、Skill、Tool、MCP 和 Workflow 的区别
概念 解决的问题 Research Agent 示例
Tool 能执行什么操作 搜索网页、读取文件、查询数据库
MCP 外部能力如何通过标准协议被连接和发现 通过 MCP Server 接入搜索服务
Skill 执行一类任务时应遵循什么方法 如何检索资料、核验来源、整理证据
Workflow 任务步骤如何被编排和控制 搜索 → 分析 → 检查证据 → 补充搜索 → 写报告
Agent 根据目标和运行时信息选择动作并推进任务 决定下一步搜索什么,或是否可以生成报告
这些概念可以组合使用。Research Agent 可以通过 MCP 接入搜索工具,通过 Skill 获取研究方法,再由 Workflow 控制主要步骤。证据不足时,模型可以提出补充搜索词,但程序仍然需要限制最大循环次数和总耗时。
三、Skill 目录通常怎么组织
一个简单的目录可以这样安排:
skills/
└── research/
├── SKILL.md
├── references/
│ ├── evidence-criteria.md
│ └── report-template.md
└── scripts/
└── validate_report.py
SKILL.md 放最重要的任务说明。references/ 保存较长的参考材料,例如证据质量标准、领域术语或报告模板。scripts/ 放适合用程序确定性执行的操作,例如检查报告是否包含必需章节。
并不是每个 Skill 都需要 references 或 scripts。任务简单时,一个 SKILL.md 就够了;只有当内容开始变长、某些规则需要独立维护,或存在明确的程序化校验需求时,再拆分文件。
四、一个 Research Skill 示例
下面是一个简化版的 SKILL.md:
---
name: research
description: Research a topic using traceable sources, check evidence sufficiency, and produce a structured report.
---
# Research Skill
## When to use
Use this skill when the user asks for a research report that requires
multiple sources and evidence-backed conclusions.
## Procedure
1. Clarify the research question and identify its scope.
2. Generate search queries covering the main question and important subtopics.
3. Search for relevant sources and record each source's title, URL, date,
and useful evidence.
4. Prefer primary sources and clearly identify the type and limitations
of each source.
5. Compare sources and identify unsupported claims or conflicts.
6. Check whether the evidence covers the important subquestions.
7. If evidence is insufficient, generate more specific search queries and
continue searching within the allowed iteration limit.
8. Produce the report only after the evidence check passes, or clearly
state the remaining gaps.
## Evidence requirements
- Important factual claims should be traceable to a source.
- Distinguish source statements from the agent's own analysis.
- Do not invent URLs, quotations, statistics, or publication dates.
- If sources conflict, describe the conflict instead of hiding it.
## Output format
- Research question and scope
- Executive summary
- Findings
- Evidence and source links
- Conflicts, limitations, and missing evidence
- Conclusion
## Stop conditions
Stop when the required subquestions have sufficient evidence, the iteration
limit is reached, or further searching is unlikely to improve the result.
If evidence remains insufficient, report the limitation explicitly.
这个 Skill 把研究方法和质量要求集中在一个文件里。它没有规定搜索工具具体怎么实现,也没有把每一步都写成必须由模型自由决定的流程。工具的实现属于 Tool 或 MCP 接入层,步骤是否固定以及循环如何结束,可以交给 Workflow 或运行时处理。
description 很重要,因为宿主应用可能先根据 Skill 的名称和描述判断它是否适合当前任务。描述应该写清楚适用场景,避免所有 Skill 都写成"帮助完成任务"这种没有区分度的句子。
五、为什么经常采用按需加载
如果一个 Agent 有几十个 Skill,而且每个 Skill 都附带大量参考资料,一开始就把所有内容放进模型上下文,会产生不必要的 token 开销,也会增加模型选择错误方法的机会。
一种常见做法是分层加载:
- 发现阶段:只提供 Skill 的名称和简短描述。
- 选择阶段:根据当前任务判断需要哪些 Skill。
- 加载阶段:读取选中 Skill 的
SKILL.md。 - 按需读取:只有在需要时才读取 references,或执行 scripts 中的程序。
这种方式通常被称为渐进式披露(progressive disclosure)。它减少了初始上下文的负担,也让不同任务可以使用不同的操作规范。
不过,按需加载需要宿主应用实现相应的发现和读取逻辑。把文件放进 skills/ 目录,并不意味着任意模型都会自动发现、加载和执行它们。
六、用 Python 实现一个最小 Skill Registry
如果自己手搓 Agent,可以先实现一个简单的目录扫描器。它负责发现 Skill,并读取对应的 SKILL.md。下面的示例为了突出核心逻辑,假定每个 Skill 目录都有一个 SKILL.md,并且 frontmatter 中包含 name 和 description。
from dataclasses import dataclass
from pathlib import Path
import re
@dataclass
class SkillMetadata:
name: str
description: str
skill_file: Path
class SkillRegistry:
def __init__(self, root: str):
self.root = Path(root)
def discover(self) -> list[SkillMetadata]:
skills = []
for skill_file in self.root.glob("*/SKILL.md"):
content = skill_file.read_text(encoding="utf-8")
metadata = self._parse_frontmatter(content)
if not metadata.get("name"):
continue
skills.append(
SkillMetadata(
name=metadata["name"],
description=metadata.get("description", ""),
skill_file=skill_file,
)
)
return skills
def load(self, name: str) -> str:
for skill in self.discover():
if skill.name == name:
return skill.skill_file.read_text(encoding="utf-8")
raise KeyError(f"Skill not found: {name}")
@staticmethod
def _parse_frontmatter(content: str) -> dict[str, str]:
match = re.match(r"\A---\s*\n(.*?)\n---\s*\n", content, re.S)
if not match:
return {}
result = {}
for line in match.group(1).splitlines():
if ":" not in line:
continue
key, value = line.split(":", 1)
result[key.strip()] = value.strip().strip("'\"")
return result
registry = SkillRegistry("skills")
for item in registry.discover():
print(item.name, "-", item.description)
research_instructions = registry.load("research")
print(research_instructions)
这个例子只实现了最基础的 frontmatter 解析。实际项目中,如果要兼容完整 YAML 语法,建议使用 YAML 解析库,而不是继续扩展正则表达式。还需要处理重复名称、目录权限、文件读取失败、Skill 版本和元数据校验。
更重要的是,load() 只负责读取文本,并没有让模型自动执行其中的所有步骤。后续还需要把加载出来的内容放进模型请求,或者交给 Agent 的运行时处理。
七、把 Skill 放进模型调用流程
在简单实现里,可以在任务开始时选中 Skill,然后把它作为任务指令的一部分加入模型请求:
def build_messages(user_request: str, skill_content: str) -> list[dict]:
return [
{
"role": "system",
"content": (
"You are a research agent. Follow the task instructions "
"and use available tools when needed.\n\n"
"Selected skill:\n"
+ skill_content
),
},
{
"role": "user",
"content": user_request,
},
]
skill_content = registry.load("research")
messages = build_messages(
"研究当前 AI Agent 工程化的主要挑战,并输出带来源的报告。",
skill_content,
)
# response = client.chat.completions.create(
# model="your-model",
# messages=messages,
# tools=available_tools,
# )
真实项目还需要处理工具调用循环、对话状态和上下文长度。Skill 也不一定每次都放进 system message;具体放置位置取决于模型 API、宿主应用和指令优先级设计。这里重点是:Skill 被加载之后,需要通过明确的运行时机制进入模型能够使用的上下文。
如果 Skill 引用了 references/evidence-criteria.md,运行时还需要让 Agent 知道这个文件存在,并在需要时读取它。引用一个文件路径不会自动把文件内容交给模型。
八、哪些内容适合写进 Skill,哪些应该写成代码
适合写进 Skill 的内容通常包括:
- 任务的适用范围和目标。
- 一般性的操作步骤和检查清单。
- 如何判断结果质量,以及遇到冲突时应如何表达。
- 输出格式和领域约定。
- 何时需要读取某份参考资料。
更适合写成代码的内容包括:
- 参数校验和权限检查。
- 必须遵守的循环次数、超时和资源限制。
- 报告是否包含必需字段等确定性校验。
- 数据库读写、外部 API 调用和文件操作。
- 需要可重复、可测试执行的计算逻辑。
Skill 可以指导 Agent 调用校验脚本,但脚本是否真的被执行,取决于运行时有没有提供执行能力,以及 Agent 是否被允许调用它。涉及权限、资金、数据删除等高风险操作时,不能只靠 Skill 中的一句提醒来保护系统。
九、Skill 的工程边界
1. Skill 不应无限膨胀
一个文件里塞进所有业务规则、工具说明、领域知识和输出模板,会让加载成本越来越高,也难以维护。可以把核心流程留在 SKILL.md,将详细标准放进 references,并明确什么情况下需要读取。
2. 不要把所有流程都交给模型自由发挥
对于研究报告,可以让模型判断哪些子问题还缺证据、下一轮应该搜索什么;但最大搜索轮数、总耗时、可调用工具范围和终止条件仍应由程序约束。Skill 提供方法,Workflow 和运行时负责控制。
3. Skill 需要测试
同一个任务可以在启用和不启用 Skill 时分别运行,观察结果是否更符合预期。测试不应只检查最终文本是否看起来不错,还可以检查来源链接是否真实、必需章节是否齐全、证据是否覆盖关键问题,以及工具调用是否符合约束。
4. Skill 内容也需要版本管理
Skill 文件会影响 Agent 的行为,因此应像代码一样管理变更。修改研究标准后,可以记录版本、更新测试案例,并观察输出变化。否则当 Agent 的结果发生变化时,很难判断是模型、工具还是 Skill 指令导致的。
十、我的理解
Skill 的价值在于把一类任务的做法沉淀下来,让 Agent 在需要时能够复用,而不用每次都从头组织相同的指令。它可以逐渐形成一套团队共享的任务规范,配合 Tool、MCP 和 Workflow 使用。
但 Skill 的实际效果取决于宿主如何发现、加载和使用它,也取决于模型是否遵循指令。需要强约束的逻辑仍然应放在程序里,涉及外部副作用的动作也必须由工具权限和运行时控制。把任务说明写成一个文件,只是实现可复用 Agent 能力的一部分。
希望这篇文章能对你有所帮助。关注我,持续分享更多实用、好用的 AI 干货。