Skills 是 DeepAgents 把专门工作方法沉淀成可复用能力包的机制：启动时只暴露名称和描述，任务命中时再读取完整说明和配套资源，让代理既能复用经验，又不会把所有流程一次塞进上下文。

　　很多初学者会把 Skills 理解成“多放几个提示词文件”，这个理解只说对了一半。Skill 确实包含文字说明，但它不是普通文档，也不是给人看的知识库目录。一个合格的 Skill 应该告诉代理：

什么时候使用它。执行时按什么步骤推进。需要调用哪些工具。遇到错误怎样恢复。产物应该长什么样。哪些参考文件或脚本需要按需读取。

　　DeepAgents 之所以需要 Skills，是因为长任务代理经常会遇到重复流程。比如一个数据分析代理，每次都要先查看 schema，再写查询，再限制结果行数，再解释结果；一个内容生产代理，每次都要先研究，再写草稿，再生成配图，再检查发布格式。

如果这些流程每次都靠用户重新说明，代理容易遗漏步骤。如果全部塞进系统提示，模型窗口又会被无关流程占满。

　　Skills 提供的是第三种选择：把稳定流程封装起来，但只在相关任务出现时展开。

Skill 解决重复说明

　　工具解决“能不能做”，Skill 解决“怎样做得稳定”。以数据库问答为例，SQL 工具可以列出表、查看 schema、执行查询，但工具本身不会告诉代理

什么时候需要先探索关系。什么时候需要限制结果行数。什么时候应该避免 DML 语句。

Skill 把这些经验写成可执行的流程，代理在遇到查询任务时先读规则，再使用工具。

　　这就是 Skills 和普通提示词的关键差别。普通提示词通常是一次背景说明，Skill 则是面向一类任务的操作手册。它可以包含步骤、判断标准、错误恢复、输出格式和示例。它的目标不是让代理“知道更多”，而是让代理在同类任务中少犯重复错误。

　　重复说明的成本常常被低估。它不只是多打几行字：每多讲一次，流程就多一个版本，代理对新旧两版说明的取舍并不稳定。更隐蔽的是上下文税——为了讲清流程而占用的窗口，会挤掉真正与当前任务相关的材料。把流程写成 Skill，相当于把它从每次口述改成按需查阅，既固定了版本，也把窗口留给眼前的任务。

　　这张流程可以帮助初学者建立一个简单判断：Skill 不是为了替代工具，而是为了约束工具组合。工具越多，越需要 Skill 解释“先用什么、后用什么、失败后怎么办”。没有 Skill，代理可能也能调用工具，但每次都会临场组织流程；有了 Skill，流程被沉淀成可复用资产。

目录结构表达能力边界

　　DeepAgents 的 Skill 通常是一个目录，里面必须有 SKILL.md。这个文件以 YAML frontmatter 开头，至少包含 name 和 description。name 是稳定标识，通常使用小写字母、数字和连字符，并且应当和目录名一致；description 是启动时暴露给模型的关键信息，用来帮助模型判断什么时候该读取这个 Skill。

　　Skill 目录还可以包含 scripts/、references/、assets/ 等资源。

scripts/ 放可执行脚本，适合把稳定的数据转换、校验、导出逻辑写成代码。references/ 放较长的说明材料，适合 API 规则、错误码、领域背景。assets/ 放模板、配置样例、图片或 schema。

　　关键点在于，这些资源不会在启动时全部进入上下文，代理只有在 SKILL.md 指示需要时才读取。

　　目录边界还决定了可维护。一个 Skill 对应一个目录，评审、替换和删除都能以目录为单位，出问题时可以定位到具体能力，而不必在一段超长提示词里猜是哪句规则失效。反过来，把数据库、写作、配图和部署塞进同一个目录，表面省了一个文件，实际是让边界重新模糊，回归时也说不清一次改动影响了哪类任务。

skills/ sql-query/ SKILL.md references/ join-patterns.md error-recovery.md scripts/ validate_query.py report-writing/ SKILL.md assets/ report-template.md

　　这类结构把能力边界放在文件系统里，而不是藏在长提示词中。sql-query 负责查询写法，report-writing 负责报告结构，两者可以组合使用，但不应该互相吞并。如果一个 Skill 同时解释数据库、写作、配图、部署和权限，它就会变成新的大杂烩，代理也更难判断什么时候该启用它。

描述决定能否被选中

　　Skill 的 description 很重要，因为代理启动时通常只看到每个 Skill 的名称和描述。完整 SKILL.md 不会一开始全部加载。

描述太泛，模型就不知道什么时候该选。描述太宽，多个 Skill 会互相竞争。描述缺少关键词，相关任务可能根本不会触发。

　　一个好的描述应该同时回答“做什么”和“什么时候用”。例如：

---name: sql-query description: Write and validate read-only SQL queries, includingSELECT, JOIN, filtering, aggregation, and LIMIT. Use when the user asks to retrieve, compare, summarize, or report data from database tables. allowed-tools: read_file grep --- # SQL Query Skill ## Workflow 1. Identify the tables and fields needed for the question. 2. Read schema notes or inspect schema before writing a complex query. 3. Write a read-only query with explicit columns and a safe LIMIT. 4. Validate joins, grouping, aliases, and filters before execution. 5. Explain the result in the users language. ## Do Not - Do not use INSERT, UPDATE, DELETE, DROP, or ALTER. - Do not use SELECT * for production-style answers. - Do not skip schema inspection when table relationships are unclear.

　　这段示例不需要很长，但它已经给了代理足够多的选择线索：SQL、只读、JOIN、聚合、LIMIT、查询数据、生成报告。它也给了执行约束：先识别表，再检查 schema，再写查询，再验证。初学者写 Skill 时，最容易犯的错误是把 description 写成“帮助处理 SQL”。这句话太短，也太模糊，模型无法可靠判断它和其他数据类 Skill 的差别。

　　描述还要能区分同类 Skill。当一个仓库里同时存在 sql-query、schema-exploration 和 report-writing，如果三个描述都以“处理数据”开头，模型只能靠猜。更稳的写法是让每个描述回答一个不同的动宾结构：探索表结构、编写只读查询、组织报告输出。描述之间的差异越清楚，选择就越不依赖运气。

渐进披露控制上下文

　　Skills 的核心机制是渐进披露。启动时，DeepAgents 扫描配置的技能来源，解析每个 SKILL.md 的 frontmatter，把技能名称、描述、路径和少量注解放进系统提示。模型此时知道“有哪些能力可以用”，但还没有读取完整说明。任务命中某个 Skill 后，代理再通过 read_file 读取完整 SKILL.md。如果说明中提到参考文件、脚本或模板，代理再按需读取或执行这些资源。

　　渐进披露的收益很直接：你可以给代理配置多个能力，但不会让每个能力的完整说明都长期占用上下文。比如一个内容代理可以同时拥有 blog-post、social-media、research、image-prompt 等 Skill。用户要求写博客时，代理不需要读取社交媒体线程规则；用户要求改写 LinkedIn 文案时，也不需要加载长文 SEO 模板。上下文变轻，选择也更准确。

　　渐进披露反过来也能当诊断工具。

如果一个 Skill 的 description 已经长到接近正文，说明它把该按需读取的内容提前暴露了。如果正文里堆满了只在个别任务才用到的模板和脚本，说明分层没有落到位。

　　把每层内容放回它该在的位置，加载顺序会自然变轻，描述也更容易保持克制。

　　这里也要看到一个边界：Skill 的描述会一直出现在启动上下文里，所以描述本身也要克制。不要在 description 里塞长段操作步骤，也不要把完整规范压缩成一串关键词。description 负责“被发现”，SKILL.md 正文负责“被执行”，references 和 scripts 负责“被深入使用”。这三层职责分清，Skill 才不会变成另一种上下文污染。

skills= 接入能力库

　　在 create_deep_agent 中传入 skills=[...]，DeepAgents 会把对应路径交给 Skills middleware 处理。路径指向技能来源目录，不是单个 SKILL.md。每个来源目录下再包含多个 Skill 子目录。来源可以有多个，声明靠后的来源优先级更高；当两个来源里有同名 Skill 时，靠后的版本会覆盖靠前的版本。这让团队可以先提供基础技能，再用项目技能覆盖细节。

from deepagents import create_deep_agent fromdeepagents.backendsimport FilesystemBackend agent = create_deep_agent( model="openai:gpt-5.5", backend=FilesystemBackend(root_dir="./agent-workspace", virtual_mode=True), skills=[ "/skills/base/", "/skills/project/", ], system_prompt=( "你是数据分析助手。遇到数据库结构、SQL 查询或报告生成任务时，" "优先检查可用 Skills，并按匹配 Skill 的流程执行。" ), )

　　这段代码展示的是最小配置形状：backend 提供文件访问，skills 提供技能来源，系统提示只补充角色和选择倾向。具体 SQL 怎样写、报告怎样组织、错误怎样恢复，不应该全写进系统提示，而应该沉淀到对应 Skill 中。这样项目增长时，你扩展的是技能库，而不是让主提示越来越长。

　　来源顺序是一条容易被忽略的细节。基础技能库和项目技能库同时存在时，同名 Skill 会由后者覆盖，这让团队可以先给一份通用流程，再在具体项目里收紧规则。但它也意味着一次无意的重名会悄悄改变行为：项目目录里放进一个同名的实验版本，代理就会改用新的那份。把重名当成一次显式覆盖来评审，比事后排查看不见的差异要划算。

使用默认状态后端时，技能文件可以通过运行输入预先放入线程状态。使用持久后端时，技能可以跨线程保存。使用文件系统后端时，技能从受控根目录读取。

　　初学者不需要一开始掌握所有后端，只要先记住：Skill 是通过 backend 暴露给代理的文件能力，不是 Python 进程直接读取任意磁盘路径。

Skill 不是 Tool

　　Skill 和 Tool 很容易混淆。

Tool 是模型可以调用的执行接口，例如读文件、搜索、查询数据库、生成图片、执行脚本。Skill 是告诉模型如何完成一类任务的说明包。

Skill 可以建议使用哪些 Tool，也可以包含脚本，但它本身不是一次工具调用。

　　以报告生成为例，write_file 是工具，负责把内容写进文件；generate_cover 是工具，负责生成图片；blog-post Skill 则规定要先研究、再写文章、再生成封面、再检查标题和结构。

　　边界混在一起时，症状往往出现在别处。工具描述被写成长流程，模型会犹豫该先调用哪个接口；Skill 里硬编码执行动作，就绕过了权限与审批；记忆里写上流程步骤，下次任务读到旧版本，行为随之漂移。分开之后，每一层只回答自己的问题，出问题也更容易定位是说明、执行还是存储的责任。没有工具，Skill 只是说明书；没有 Skill，工具调用就缺少稳定流程。二者结合起来，DeepAgents 才能把“可执行能力”和“可复用方法”放在同一个 Harness 中。

　　这个边界也能帮助你决定内容放哪里。

需要真实执行的动作放 Tool，例如调用数据库、运行脚本、生成文件。需要指导代理选择、排序、验证和解释的内容放 Skill，例如查询策略、报告结构、错误恢复和质量检查。需要长期保存用户偏好或组织政策的内容放记忆或只读文件。

　　把三者混在一起，会让系统难以维护：工具描述过长，Skill 过度执行，记忆又被流程细节污染。

触发条件决定 Skill 是否可用

Skill 写得再完整，如果触发条件不清楚，模型也很难正确使用。触发条件主要来自名称、description 和任务语义。名称负责让人和模型快速识别领域，description 负责说明适用场景，正文负责在触发后指导执行。初学者常见错误，是把正文写得很长，却把 description 写得很虚，结果代理启动时根本不知道这个 Skill 何时有用。

　　一个清楚的触发条件应该包含任务动词和对象。例如“生成发布报告”“审查 SQL 查询”“迁移旧配置”“整理会议纪要”比“处理文档”“提升质量”“辅助开发”更容易命中。还可以写出排除条件，避免 Skill 被错误选择。比如只读 SQL Skill 要说明不处理写入语句，报告 Skill 要说明不负责数据采集，代码审查 Skill 要说明不自动修改文件。排除条件越清楚，多个 Skill 同时存在时越不容易互相抢任务。

　　Skill 也可以按阶段触发。一个长任务不一定从一开始就读取完整 Skill。代理可能先用文件工具收集材料，再发现需要报告模板，于是读取 report-writing Skill；也可能先由子代理完成研究，主 Agent 在交付阶段读取发布 Skill。渐进披露的价值就在这里：不要让所有说明一开始占满上下文，而是在任务真的需要某个流程时再展开。

支持文件和脚本要按需进入

Skill 可以引用模板、示例、脚本和参考文件，但这些资源不应该全部塞进 SKILL.md。正文只需要说明何时读取哪个资源，以及资源负责什么。模板适合放固定格式，脚本适合放可重复执行的校验动作，示例适合放少量高质量样例。这样 Skill 本身保持短小，真正需要细节时再读取支持文件。

　　支持资源也要和权限配合。一个 Skill：

如果建议执行脚本，就必须说明脚本的输入、输出和风险。如果建议写文件，就要说明目标目录和命名规则。如果建议读取敏感材料，就要说明审批或只读限制。

　　否则 Skill 会绕过工具和权限设计，把风险藏进流程说明里。

　　对团队来说，Skill 还需要版本意识。

　　资源边界还影响失败处理。参考文件缺失、脚本执行出错、模板版本过期，都会让一次本该成功的任务停在半路。把“找不到材料怎么办、脚本失败怎么办、模板不适用怎么办”写进正文，代理才有明确的退出或求助路径；只写顺利路径的 Skill，一旦环境偏离预期就会安静地做出错误产出。业务流程会变化，模板会升级，依赖脚本会失效。把 Skill 当作长期资产，就要定期检查 description 是否仍然准确，支持文件是否仍然存在，示例是否过期，脚本是否还能运行。模型没有能力凭空知道 Skill 已经过时，维护责任必须落在工程流程里。

把 Skill 当成可测试资产

　　Skill 不是只能靠肉眼试用。可以准备一组小任务样本，验证代理是否会选择正确 Skill、是否读取了必要支持文件、是否按流程执行、是否避免了禁止动作。比如 SQL Skill 可以用“查询销售汇总但不要修改数据”的任务测试只读约束；报告 Skill 可以用“根据材料生成摘要”的任务测试模板触发；迁移 Skill 可以用“列出迁移步骤但不执行”的任务测试风险边界。

　　这些测试不一定复杂，关键是能暴露选择错误和流程漂移。

如果代理经常不用某个 Skill，可能是 description 太弱。如果代理过度使用某个 Skill，可能是范围写得太宽。如果代理读了 Skill 仍然跳过关键步骤，可能是正文结构不够明确。

　　通过样本回归，Skill 才能从“写给模型看的文档”变成可以持续维护的能力包。

　　Skill 还可以和子代理配合。一个通用主 Agent 不一定要掌握每个领域流程，可以把某些 Skill 只配置给特定子代理。例如研究子代理使用资料整理 Skill，代码审查子代理使用 review Skill，报告子代理使用写作 Skill。这样主 Agent 只负责委托和综合，专业流程留在更窄的上下文中运行。Skill 的作用域越清楚，越不容易让所有流程一起污染主代理提示词。

　　在团队环境里，还要区分个人 Skill、项目 Skill 和组织 Skill。

个人 Skill 可以保存自己的写作或编码习惯。项目 Skill 可以保存当前项目的发布流程、测试流程和目录约定。组织 Skill 则可能涉及统一安全规范、合规流程和审批要求。

　　三类 Skill 的维护权限不同，触发范围也不同。把组织规范放进个人 Skill，可能导致别人无法复用；把个人偏好放进组织 Skill，又会影响不该影响的用户。

　　Skill 的描述也要避免过度承诺。它可以告诉代理“按照这个流程尝试”，不能保证外部系统一定可用、数据一定正确、任务一定成功。正文最好包含失败处理：找不到输入文件怎么办，脚本失败怎么办，缺少权限怎么办，结果不满足标准怎么办。没有失败路径的 Skill，只适合演示，不适合长期任务。

　　因此，设计 Skill 时可以按四个问题检查：它什么时候触发，触发后先读什么，执行时用哪些工具，失败时怎样退出或请求帮助。四个问题都回答清楚，Skill 才能真正减少上下文负担，而不是把另一份长说明塞进 Agent。

　　Skill 的更新也要有评审意识。因为它会改变代理的工作方式，修改 description、步骤顺序、引用文件或允许工具，都可能影响一类任务的输出。团队可以把 Skill 当作轻量流程代码来管理：改动要有原因，重要变更要经过审阅，发布后要用样本任务回归。这样 Skill 才不会在长期维护中悄悄漂移。

　　流程也需要版本意识。

　　回归的价值在于把维护责任写进流程，而不是留给记忆。团队可以给每个 Skill 留一组最小样本，改动 description、步骤顺序或允许工具后重跑一遍；样本不必覆盖全部边界，只要能证明这次改动没有让原先能用的任务退化。没有这层回归，Skill 会随着一次次“看起来更清楚”的修改慢慢偏离它最开始的意图。

让 Skill 可维护

　　一个 Skill 能不能长期使用，不取决于它写得多详细，而取决于它是否容易被正确触发、正确阅读、正确修改。名称要稳定，description 要具体，正文要按任务步骤组织，引用资源要少而清楚。支持文件最好只放真正会被使用的材料，不要把整套知识库都拖进一个 Skill。

　　还要避免技能数量失控。如果十个 Skill 的 description 都写着“处理数据分析任务”，模型很难选择。更好的做法是合并重叠能力，或者把一个主 Skill 拆成少量清晰分支：

schema-exploration 负责看结构。sql-query 负责写查询。report-writing 负责组织输出。

　　每个 Skill 的第一段就应该让模型知道它的边界。

　　加载失败也应被看见。DeepAgents 会跳过缺失 frontmatter、解析失败或不符合基本约束的 Skill，并把来源级错误记录为加载警告。对初学者来说，这说明 Skill 不是“放进去就一定生效”。当代理没有按预期使用某个 Skill，不要只改提示词，应该先检查目录结构、frontmatter、名称、description 和路径来源。

写在结尾的话

Skills 的价值不在于多存几份说明，而在于把稳定流程变成可发现、可按需读取、可覆盖、可维护的能力包；当工具负责执行、记忆负责长期事实、Skill 负责专门流程时，DeepAgents 的长任务 Harness 才能在复杂项目中持续复用经验，而不是每次从零临场组织。