1. 为什么你的 Agent 总是“差点意思”如果你正在用 deepagents 搭 Agent大概率遇到过这种场景模型本身能力不差但一到具体任务就开始“自由发挥”——让它审查代码它给你写一段泛泛而谈的点评让它按团队规范生成文档它按自己的理解来一套。问题不在模型而在于你没有把“专业能力”以结构化的方式喂给它。AI Skills 技能系统解决的就是这件事。你可以把它理解成给 Agent 装 App每个 Skill 是一个独立的功能单元里面封装了特定领域的指令、脚本和参考资料。Agent 在收到请求时先扫描所有技能的元数据做语义匹配命中后把该技能的完整指令加载进上下文再按步骤执行。整个过程对用户透明你只管表达意图Agent 自己找技能、用技能。这套机制的核心载体是一个叫SKILL.md的文件。它由两部分组成开头的 YAML Frontmatter 定义技能名称和描述后面的 Markdown 正文写具体执行指令。描述字段尤其关键它直接决定 Agent 能不能在正确的时机找到这个技能。一个写得好的 description 应该简洁、包含触发条件让 Agent 一看就知道“什么场景下该用我”。这篇文章面向正在使用 deepagents 和 FilesystemBackend 的开发者我会从目录结构讲起给出技能注册的配置骨架然后通过 TaoToken 统一 Key/API 通道接入最后演示 Agent 加载技能后自动增强的完整验证步骤。全程可跟做代码可直接复制。2. 前置准备TaoToken 统一 Key 与 API 通道在写 Skill 之前先把模型接入这层理顺。deepagents 底层依赖 LangChain 的模型初始化而很多开发者在多模型切换时最头疼的就是 Key 和 base_url 的管理。我的做法是用 TaoToken 做统一入口一个 Key 走通所有模型调用省去到处配环境变量的麻烦。TaoToken 的 API 地址是https://taotoken.net/api你需要在控制台创建一个 API Key。拿到 Key 之后把它写进项目的.env文件不要硬编码在代码里。下面是我实际使用的.env结构# .env TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o-mini这里TAOTOKEN_MODEL可以换成你需要的任何模型标识TaoToken 会根据模型名路由到对应的上游。如果你还没创建 Key可以去控制台的 API Keys 页面生成一个建议按项目分 Key方便后续排查用量。注意deepagents 目前不支持通过init_chat_model直接构造的模型对象需要调整初始化方式。下面第 3 节会给出可用的写法。环境准备好之后安装依赖pip install deepagents python-dotenv langchain langchain-community装完之后先别急着写 Skill我们先把目录结构定下来这是整个技能系统能跑通的基础。3. SKILL.md 目录结构与技能注册配置骨架3.1 目录结构设计一个 Skill 的标准目录长这样skills/ └── code-review/ ├── SKILL.md # 必需技能指令和元数据 ├── scripts/ # 可选可执行脚本 │ └── review.py └── references/ # 可选参考文档、示例数据 └── rules.mdSKILL.md是唯一必需的文件。scripts/放 Python、Shell 等可执行脚本Agent 可以在指令中调用它们。references/放辅助资料比如团队编码规范、示例输入输出Agent 需要时会读取。3.2 SKILL.md 文件写法Frontmatter 用 YAML 格式定义name和description。description 要包含触发条件这是 Agent 做语义匹配的依据。正文部分写具体执行步骤。--- name: code-review description: 审查代码质量、检查常见问题。当用户要求代码审查、review 代码、检查代码规范时使用。 --- # 代码审查 审查代码文件检查以下问题 - 语法错误和潜在 Bug - 代码风格和规范性 - 性能问题 - 安全隐患 ## 使用方法 当用户要求审查代码时执行 python /skills/code-review/scripts/review.py file_path ## 输出格式 按严重程度分类 - 严重问题必须修复 - 警告建议改进 - 提示可选优化description 里我特意加了“当用户要求代码审查、review 代码、检查代码规范时使用”这三个短语覆盖了用户可能的表达方式能显著提高匹配命中率。如果你只写“审查代码”用户说“帮我看看这段代码有没有问题”时可能就匹配不上。3.3 技能注册配置骨架deepagents 的create_deep_agent通过skills参数指定技能目录。这里有个容易忽略的点默认使用的是内存后端StateBackend它读不到本地文件系统。要加载磁盘上的 Skill 文件必须显式传入FilesystemBackend。import os from dotenv import load_dotenv from deepagents import create_deep_agent from deepagents.backends import FilesystemBackend from langchain.chat_models import init_chat_model from langchain_core.tools import BaseTool from langchain_community.tools import WriteFileTool, ReadFileTool, ListDirectoryTool load_dotenv() # 使用 configurable_fields 创建可配置模型 model init_chat_model( model_provideropenai, configurable_fields[model, api_key, base_url], config_prefixTAOTOKEN ).with_config({ configurable: { TAOTOKEN_model: os.getenv(TAOTOKEN_MODEL), TAOTOKEN_api_key: os.getenv(TAOTOKEN_API_KEY), TAOTOKEN_base_url: os.getenv(TAOTOKEN_BASE_URL) } }) os.environ[OPENAI_API_KEY] os.getenv(TAOTOKEN_API_KEY) os.environ[OPENAI_BASE_URL] os.getenv(TAOTOKEN_BASE_URL) model fopenai:{os.getenv(TAOTOKEN_MODEL)}这里config_prefix设为TAOTOKEN对应的环境变量就是TAOTOKEN_model、TAOTOKEN_api_key、TAOTOKEN_base_url。这样配置的好处是模型、Key、base_url 三者解耦换模型时只改.env里的TAOTOKEN_MODEL即可代码不用动。接下来定义工具和创建 Agentclass CalculateTool(BaseTool): name: str calculate description: str 计算数学表达式的值 def _run(self, expression: str) - str: try: return f计算结果: {eval(expression)} except Exception as e: return f计算错误: {str(e)} async def _arun(self, expression: str) - str: return self._run(expression) calculate CalculateTool() write_file WriteFileTool() read_file ReadFileTool() list_dir ListDirectoryTool() agent create_deep_agent( modelmodel, tools[calculate, write_file, read_file, list_dir], system_prompt你是一个助手会用工具计算、读写文件、列出目录。, skills[skills], backendFilesystemBackend(root_diros.getcwd()), debugTrue )skills[skills]告诉 Agent 去skills目录下扫描所有SKILL.md。backendFilesystemBackend(root_diros.getcwd())让 Agent 能读取当前工作目录下的文件。debugTrue会打印技能匹配和加载的日志调试阶段建议开着。4. 验证请求Agent 加载技能后自动增强配置写好了怎么确认技能真的被加载并生效我设计了一组查询来验证覆盖技能匹配、工具调用、文件读写三个维度。queries [ 审查 mcp_weather.py 代码, 计算 2024*12500然后把结果保存到 result.txt, 读取 result.txt 的内容, 列出当前目录文件 ] for q in queries: print(f\n问{q}) result agent.invoke({messages: [{role: user, content: q}]}) print(f答{result[messages][-1].content})跑起来之后重点观察第一个查询。当输入“审查 mcp_weather.py 代码”时Agent 会先扫描skills目录下所有SKILL.md的 Frontmatter提取出code-review这个技能的 name 和 description生成可用技能列表。然后把用户请求和列表里的 description 做语义匹配命中code-review后调用load_skill方法把该技能的完整 Markdown 指令加载到对话上下文中。最后 Agent 按照指令里的步骤调用review.py脚本执行审查返回结果。如果你开了debugTrue控制台会打印类似这样的日志[Skill] Scanning skills directory... [Skill] Found: code-review - 审查代码质量、检查常见问题... [Skill] Matching query: 审查 mcp_weather.py 代码 [Skill] Matched: code-review [Skill] Loading skill: code-review [Skill] Executing: python /skills/code-review/scripts/review.py mcp_weather.py看到Matched: code-review和Loading skill这两行就说明技能系统正常工作了。第二个查询验证的是工具调用链Agent 先调calculate算出结果再调write_file写入文件。第三个查询验证read_file能读回内容。第四个验证list_dir。实测下来加了 Skill 之后最明显的变化是以前让它审查代码它会输出一段通用点评现在它会按SKILL.md里定义的分类格式输出严重问题、警告、提示分得清清楚楚而且会真的去调用review.py脚本而不是凭空生成。5. 本篇常见错排查5.1 技能没被匹配到最常见的原因是 description 写得太窄。比如只写“审查代码”用户说“帮我看看这段代码有没有问题”就匹配不上。解决办法是在 description 里补充同义触发词用逗号分隔。另外检查skills参数路径是否正确skills[skills]是相对路径相对于FilesystemBackend的root_dir。5.2 报错 “StateBackend cannot read local files”这是没传FilesystemBackend导致的。create_deep_agent默认用内存后端读不到磁盘文件。加上backendFilesystemBackend(root_diros.getcwd())即可。注意root_dir要指向包含skills目录的父目录。5.3 模型初始化报错 “init_chat_model object has no attribute”deepagents 目前不支持直接传init_chat_model构造的模型对象。需要用configurable_fields方式创建然后通过with_config注入配置最后用fopenai:{model_name}字符串形式传给create_deep_agent。上面第 3.3 节的代码就是可用的写法。5.4 脚本执行权限问题SKILL.md里写的python /skills/code-review/scripts/review.py是绝对路径。如果你的root_dir不是/这个路径会找不到文件。建议改成相对路径python skills/code-review/scripts/review.py或者用os.path.join动态拼接。另外确认脚本有可执行权限Linux/macOS 下chmod x review.py。5.5 API 调用返回 401 或 404检查.env里的TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL是否正确。base_url 应该是https://taotoken.net/api不要多加/v1或结尾斜杠。如果用的是自定义模型名确认 TaoToken 控制台里该模型可用。401 通常是 Key 无效404 通常是 base_url 或模型名写错。6. 把技能系统用起来Skill 系统的价值在于模块化。你可以为团队常用的每个任务写一个 Skill代码审查、文档生成、数据分析、接口测试。每个 Skill 独立开发、独立测试、独立复用。新成员加入时不用口头传授规范把SKILL.md给他看就行Agent 会自动按规范执行。如果你想让 Agent 在长期编码任务中持续变强建议把常用 Skill 沉淀到项目仓库里配合 TaoToken 的 Coding Plan 做统一模型调度。需要生成新 Key 或查看用量去控制台的 API Keys 页面操作。接入文档里有更详细的参数说明和示例遇到报错可以先对照排查。最后留一个实用技巧SKILL.md的 description 字段值得反复打磨。我通常会拿 10 条真实用户请求做测试看命中率。如果某条没命中就把那条请求里的关键词补进 description。迭代两三轮之后匹配准确率会有明显提升。