Agent Skills 这个词最近在 AI 圈子里被反复提起，我自己在几个实际项目里把它从概念落到了代码，踩了不少坑，也攒了一些心得。这篇文章就把我理解的 agent-skills 到底是什么、怎么设计、怎么落地，以及实测中那些文档里不会写的坑，一次性讲清楚。如果你正在做 Agent 相关的开发，或者准备把自己的工具链接入 AI 流程，这篇文章应该能帮你省下不少试错的时间。
1. Agent Skills 到底是什么：先搞清楚它解决的问题
1.1 技能不是一个新概念，只是换了个封装思路
先说结论：Skills（技能）本质上是把 Agent 可以执行的一组能力，按照一种相对规范的格式封装起来，让大模型能够“看见”这些能力，并且知道在什么场景下调用它们。
我之前做过一个内部调研工具，最开始用的是最粗暴的方式——把一堆功能函数直接塞给模型，告诉它“你可以用这些”。结果很惨：模型经常在错误的场景调用错误的函数，参数格式五花八门，我不得不花大量时间在 prompt 里反复解释每个函数是干嘛的。后来我把这些函数按照“技能”的方式重新组织，每个技能带清晰的描述、参数说明、使用场景示例，情况立刻好转。所以技能化不是给函数换个名字，而是解决“模型如何正确使用工具”这个核心问题。
很多人会把 Skills 和 Tools、Plugins、Workflow 混为一谈。我自己的理解是：Tool 是单位能力，比如“搜索网页”“调用某个 API”；Skill 是围绕一个目标任务组织起来的能力组合，比如“完成一份竞品分析报告”可能需要搜索、爬取、总结多个 Tool 协作；Plugin 通常指宿主平台对第三方能力的接入规范；Workflow 则是把这些技能串起来的执行流程。Skills 卡在 Tool 和 Workflow 之间，既要管理底层工具的调用细节，又要给上层编排提供清晰的能力边界。
1.2 技能化到底解决了什么痛点
我在实际项目中感受到的痛点有三个。第一个是能力目录混乱。当 Agent 需要调用的工具超过十个以后，靠 prompt 堆叠描述的方式根本不可持续，模型会被淹没在信息里。第二个是复用困难。同一个“读取 PDF 并提取表格”的能力，A 项目里写了一版，B 项目又得重写，没有统一的封装就谈不上复用。第三个是安全边界模糊。没有技能这个中间层，Agent 可能会直接调用底层系统命令，这在生产环境里是灾难。
技能化之后，能力变成了一个个可注册、可查询、可启用的独立模块。你可以在运行时决定给这个 Agent 挂载哪些技能，也可以根据任务动态加载。这种解耦带来的好处是：Agent 变得更专注，能力维护变得更简单，安全控制也找到了一个合适的抓手——在技能层做权限校验，比在函数内部到处加判断干净得多。
2. 技能体系的设计思路：接口、描述与注册机制
2.1 技能描述（Schema）是灵魂
我反复修改了很多版之后得出的结论是：一个技能好不好用，80% 取决于它的描述质量。大模型不是通过函数名理解你的能力，而是通过自然语言描述和参数说明来匹配意图。设计技能 Schema 的时候，我的模板固定包含这几部分：
- 技能 ID：全局唯一的英文标识，例如
web_search_basic - 名称：简短的人类可读名称
- 描述：说明技能在什么情况下使用、解决什么问题，要用“当用户需要……时，使用此技能”这样带有触发条件的写法，而不是干巴巴的能力陈述
- 参数定义：每个参数的类型、必填性、默认值、取值范围和自然语言解释
- 返回值格式：定义输出结构，便于上层解析
- 使用示例：给一两个典型的调用样例，帮助模型举一反三
这里有个容易犯的错误：描述写得过于抽象。比如“获取天气信息”和“当用户想了解某个城市当前或未来的天气情况时使用此技能，参数 city 为城市中文名，例如‘北京’”，后者在大模型眼里完全是两个信息量级。我后来养成了一个习惯：让另一个同事不看代码，只读描述，如果他能判断出什么场景该用这个技能，这个描述才算合格。
2.2 注册与调度：技能不是硬编码在代码里的
技能的注册机制决定了整个系统的扩展性。我采用的是“声明式注册 + 运行时装载”的方式。每个技能一个独立目录，包含一个SKILL.md（描述文件）和对应的执行代码。系统启动时扫描技能目录，把每个技能的 Schema 加载进内存，等到对话请求进来时，再根据任务内容决定把哪些技能暴露给模型。
这样做的好处是增加新技能不需要改主程序代码，只需要新增目录、写好描述和实现。调度器层面我加了一个简单的过滤逻辑：根据用户请求的关键词和技能描述之间的语义相似度做一次粗筛，把明显不相关的技能从上下文里剔除。虽然大模型理论上可以处理很多工具描述，但实测下来，一次对话挂载的技能超过 15 个之后，模型的选择准确率会明显下降。粗筛这一层能省不少 token，还能提升准确率。
2.3 选型对比：为什么我放弃了纯 Function Calling
市面上做 Agent 技能的方式大致有三种：纯 Function Calling、ReAct 模式的自然语言调用、以及图形化工作流编排。我最初用的是某家大模型平台的 Function Calling 接口，直接把工具数组传给模型。试下来发现问题：Function Calling 虽然有结构化输出，但技能之间的依赖关系、状态传递需要自己在代码里维护，而且平台绑定的成分比较大——换一个模型服务商，整套调用逻辑就得重写。
后来我采用了 ReAct 风格的技能描述方式，把技能当作模型可以“阅读”的文档，模型自己决策调用顺序和参数。这样做的好处是模型无关，换底层模型不用改系统架构。坏处是对描述质量要求高，而且需要自己处理多轮调用中的状态。如果你追求快速上线、且锁定了单一模型服务商，直接用 Function Calling 更省事；如果像我一样需要长期演进、频繁更换底层模型，建议走技能文档化这条路。
3. 从零实现一个轻量技能系统：完整实操过程
3.1 基础框架与目录结构
我做一个最小可用的技能系统，目录结构如下：
agent_skills/ ├── skills/ │ ├── web_search/ │ │ ├── SKILL.md │ │ └── implement.py │ ├── pdf_extract/ │ │ ├── SKILL.md │ │ └── implement.py │ └── ... ├── registry.py ├── scheduler.py └── main.py每个技能就是一个目录，SKILL.md用来描述能力，implement.py用来实现具体逻辑。这种约定简单到不需要额外框架，新成员上手也快。我见过很多团队把技能封装做得特别复杂，动不动引一个重型框架，最后维护成本比收益还高。对大多数场景来说，一个约定、一个扫描函数、一个统一调用入口，足够了。
3.2 技能描述文件的写法和完整示例
以“网页搜索摘要”技能为例，我的SKILL.md长这样：
--- name: 网页搜索并提取摘要 description: 当用户需要了解某个话题的最新信息、查找特定事实或想让我搜索互联网时使用。注意：此技能只返回搜索结果摘要，不返回完整网页正文。 parameters: - name: query type: string required: true description: 搜索关键词，建议使用疑问句或关键词组合，例如“2025年新能源汽车销量排行” - name: top_k type: integer required: false default: 5 description: 返回结果条数，范围 1-10 return_schema: type: object properties: items: type: array items: type: object properties: title: { type: string } url: { type: string } snippet: { type: string } examples: - input: 帮我查一下最新的行业报告 output: items 数组返回每条结果的标题、链接和 200 字以内的摘要文本 --- # 技能说明 本技能封装搜索服务，内部使用搜索 API，对返回结果做摘要截断，不保留完整正文。异常时返回 error 字段，由上层决定是否重试。关键细节都在这个文件里。参数描述里我写明了“建议使用疑问句或关键词组合”，这是从实际效果中总结出来的——模型生成的搜索词质量直接影响结果质量。top_k限制了数量，防止模型一次要 100 条结果把上下文撑爆。return_schema给模型看了输出长什么样，它才能正确解析结果。这些都是让技能真正“好用”的细节。
3.3 注册器与调度器实现
注册器负责扫描目录、加载元信息。调度器负责把技能列表交给模型，并执行模型选择的技能调用。核心代码如下：
import importlib import json from pathlib import Path from typing import Any, Dict, List class SkillRegistry: def __init__(self, skill_dir: str = "skills"): self.skill_dir = Path(skill_dir) self.skills: Dict[str, Dict[str, Any]] = {} def load_all(self) -> None: for skill_path in self.skill_dir.iterdir(): if not skill_path.is_dir(): continue skill_id = skill_path.name meta = self._load_meta(skill_path / "SKILL.md") module = importlib.import_module(f"skills.{skill_id}.implement") self.skills[skill_id] = { "id": skill_id, "meta": meta, "execute": module.execute, } print(f"已加载 {len(self.skills)} 个技能") def _load_meta(self, path: Path) -> Dict[str, Any]: # 这里用简单解析方式，实际可引入 yaml 解析 raw = path.read_text(encoding="utf-8") # 截取 --- 之间的 YAML 部分再做解析，此处省略细节 return {"name": "demo_skill", "description": "..."}class SkillScheduler: def __init__(self, registry: SkillRegistry): self.registry = registry def build_skill_documents(self, task: str, max_skills: int = 12) -> List[Dict]: # 简单粗筛：基于关键词和描述重叠度排序，取前 max_skills 个 candidates = list(self.registry.skills.values()) # 实际可接入 embedding 做语义筛选 selected = candidates[:max_skills] return [{"id": s["id"], "description": s["meta"]["description"]} for s in selected] def execute(self, skill_id: str, params: Dict) -> Any: skill = self.registry.skills.get(skill_id) if not skill: raise ValueError(f"技能 {skill_id} 不存在") try: return skill["execute"](params) except Exception as e: return {"error": str(e), "skill_id": skill_id}这段代码只求讲清楚最小闭环：注册器加载，调度器选择并调用。实际项目里我会在execute里加超时控制、重试、日志记录，并且把执行结果写进一个运行追踪表，方便后期分析模型到底是怎么调用这些技能的。日志很关键，后面讲排查时会细说。
3.4 参数校验：别让模型传什么你都信
模型生成的参数不一定合法，这是我在实测里最头疼的问题。比如要求top_k是 1-10 的整数，模型可能传 100，也可能传字符串 "5"。所以参数校验必须在调用技能之前做。
我在注册器里加了一个校验器，按照 SKILL.md 里的参数定义逐个检查：类型不对就尝试转换，范围越界就裁剪到合法范围，必填缺失就直接返回一个友好的错误提示，并且把这个提示反馈给模型，让它重新生成调用。这比直接在技能内部报一个 Python 异常要有效得多——模型的错误恢复能力很强，只要把原因说清楚，它下一轮就能纠正过来。实测中，加上这层校验后，整个系统的调用失败率从 18% 降到了 4% 左右。
4. 实测中的常见问题与排查方法
4.1 问题一：模型选了技能但参数一塌糊涂
症状：技能调用频繁，但结果经常报错，日志里全是参数类型不匹配。排查之后发现根因有两个：一是技能描述里的参数解释不够具体，模型不知道该怎么填；二是系统没有做参数校验，错误一路抛到最外层，模型得不到反馈，下一轮继续犯同样的错。
解决办法：先补描述，把参数的格式、范围、示例都写清楚；再加校验层，让模型在调用失败时能看到明确错误原因。这个组合拳比调整 model prompt 的参数更有效。另外我还发现一个细节：参数命名尽量用snake_case并且含义清晰，不要用a、b、data这种含糊名字，模型的生成正确率会好很多。
4.2 问题二：技能描述互相重叠导致模型选错
症状：系统里有“网页搜索”和“新闻检索”两个技能，实际功能差不多，模型在使用时随机选择，导致行为不一致。根因是技能边界没划清。
解决思路：要么合并成一个技能，要么在描述里明确边界。我在SKILL.md里加了一句话：“若用户关注的是实时新闻事件，请使用 news_lookup 技能；若是一般信息查询，请使用本技能。”这种“排他性”描述对模型的选择准确率提升非常明显。技能不在多，而在于每个技能的“适用场景”写得足够清楚。
4.3 问题三：长任务执行中超时和上下文膨胀
我做的调研型 Agent 经常需要连续调用五六个技能，整个过程要几分钟。一开始没有超时控制，一个技能卡住会导致整个 Agent 挂起。后来我在调度器里给每个技能调用加了独立的超时阈值，基础技能 15 秒，耗时技能 60 秒，超时后返回“技能执行超时，请稍后重试或更换方案”。同时我把每个技能返回的结果做了截断策略，比如搜索结果只保留前 5 条摘要，全文内容提取只保留关键段落，防止多个技能结果累加之后超出模型的上下文窗口。
4.4 问题四：并发调用的状态冲突
多用户同时使用同一个技能实例时，如果技能内部有全局变量，会有状态污染。我遇到的一个真实案例：一个技能里缓存了上次调用的用户 ID，结果下一个用户调用时读到了上一个用户的数据。排查过程很费劲，后来明确规定：技能内部禁止使用全局可变状态，所有数据都通过函数参数传递。这个约束写进了团队开发规范，之后再也没有出现过同类问题。
4.5 排查技巧：日志就是第二语言
技能系统的排查效率，几乎完全取决于日志质量。我给自己定了三条日志原则：第一，每个技能调用的入参和出参都记录完整，方便复现；第二，记录模型是在哪一轮对话里发起调用的，方便对照上下文；第三，用统一的 trace ID 串起一次完整任务里所有技能调用，这样排查问题时能看到完整的调用链。配上一个简单的日志查询界面，你会发现排查效率提升一个量级。
5. 进阶经验：技能编排、测试与迭代
5.1 从单技能到技能组合
单个技能解决单个问题，但真实任务往往是组合式的。比如“整理本周行业动态”这个任务，可能需要搜索技能收集信息、解析技能读取网页内容、总结技能生成周报。我在系统里增加了一个“组合技能”的概念——它不实现具体功能，而是编排其他技能的执行顺序。组合技能也走同样的注册和调用流程，只是在执行时调度内部的子技能。
这种“技能套技能”的设计让整个系统呈现出一种树形结构：顶层是任务级的组合技能，底层是原子级的基础技能。新增一个业务场景时，多数情况下只需要调整组合技能的编排逻辑，底层技能不用改。我现在回顾下来，这个抽象层次是整套系统扩展性最强的设计决定。
5.2 技能测试：不能只用完美用例测
技能测试和普通函数测试有很大差异。普通函数测试关注边界值和异常输入，技能测试还要关注“描述是否被模型正确理解”。我的做法是维护一组测试任务，每个任务是一个真实的用户请求，比如“帮我查一下某地明天的天气”“总结这篇文档的三个要点”。每次修改技能描述或实现后，都跑一遍全量测试任务，对比模型选技能的正确率和参数生成的合法率。
这里踩过一个大坑：只用了理想输入测试，结果上线后被用户的各种口语化请求打懵。后来我把测试任务分成三档：标准输入、口语化输入、带干扰信息的输入。比如干扰档是“我想看看天气，对了顺便问一下明天的会议几点开始”，模型要能识别主要意图并选择正确的技能。用这套测试集跑下来，系统的鲁棒性提升很明显。
5.3 数据驱动的技能迭代
技能描述怎么优化？靠感觉是不行的。我每两周导出一次日志，统计哪些技能的调用失败率高、哪些技能的调用频率低、模型的哪些请求没有被任何技能接住。频率高但失败率高的技能优先优化；一直没人调用的技能考虑是否该下线；没被接住的请求则标记为“技能空缺”，作为新增技能的候选依据。这套数据驱动的迭代机制，比拍脑袋决定做什么技能靠谱得多。
5.4 关于安全边界的再提醒
技能层的权限校验一定要做。给模型挂载技能时，我从一开始就区分了只读技能和可写技能：只读技能直接放行，可写技能在执行前必须经过二次确认或鉴权。比如一个“发送邮件”的技能，无论如何不能因为模型判断需要就自动发出。在技能层统一做鉴权，比在每个技能实现里自己写安全逻辑要规范得多。另外，技能能够访问的系统资源要尽量收敛，遵循最小权限原则，不要图省事给技能开一个大而全的权限。
6. 最后分享几个用了很久的实用习惯
写到这，分享几个我自己一直在用的小习惯。第一个，每次给技能加新功能时，顺手更新SKILL.md里的示例，因为示例就是给模型的“模板”，示例质量直接决定模型调用的下限。第二个，技能系统上线后一定要保留一段时间的对比基线——修改描述前后各跑一轮测试任务，用数据说话，别凭感觉判断“好像变聪明了”。第三个，技能数量控制在 30 个以内，超过这个数就考虑合并或者分层，不然描述之间的重叠会越来越多，模型的选择准确率会持续下降。
我个人在实操中最深的体会是：Agent 的能力上限不完全取决于底层模型，很大程度取决于你给模型提供的技能质量与其描述的可理解性。把时间花在打磨技能描述、健全调用链路的健壮性上，回报率比换更贵的模型参数高得多。技能系统一旦跑顺，后面加新能力其实就是“写一个目录、填一份描述、写一个函数”三件事而已。
