去年 10 月Anthropic 在 Claude Code 里推 Agent Skills 的时候我第一反应是这玩意儿不就是 prompt 工程的「换皮」吗把 SOP 写进一个 Markdown 文件命名 SKILL.md放进一个固定目录让 Agent 自己来读——这跟我以前在项目根目录放一个prompts/文件夹有什么区别直到我前几天在跟 DeepAgents Day 12 收尾准备给自己的 Agent 加点「业务套路」开 IDE 翻create_deep_agent的签名看到一个我之前一直略过的参数skills: list[str] | None None跟一行注释List of skill source paths (e.g.,[/skills/user/, /skills/project/]).我当时就停下来了。这个参数我前 12 天笔记里只在 Day 1 提过一句在 Day 4 默认中间件清单里又一笔带过真到要用的时候发现完全不知道它能不能解决我手上的问题我有几套已经在 Claude Code 里跑得很顺的 SKILL.md能不能直接挪到 LangGraph 跑的 Agent 上跨平台复用这件事到底是不是真的于是我把deepagents/middleware/skills.py整个文件约 1000 行 Python其中过半是 docstring 和注释通读了一遍又对照着 agentskills.io 规范和 Claude Code 的实际目录布局比了一下。这是 Day 13 的笔记把里面看到的写下来。阅读提示DeepAgents 的 Skills 系统不是新概念——它是 Anthropic Agent Skills 规范的一个第三方实现本质上一个中间件 一个 system prompt 模板Progressive Disclosure 的三段式加载到底什么时候花什么 tokenTool / Skill / Sub-agent 三者的边界——这套配齐了 DeepAgents「能力扩展」的全部抽象一段把~/.claude/skills/直接挂到 DeepAgents 上的最小可运行代码 全文约 14 分钟。一、先把上下文交代清楚Skills 是 Anthropic 推出的、Open 的标准很多人——包括之前的我——以为 Skills 是 Claude Code 自家的特性。其实不是。事实层面来自 agentskills.ioagentskills.io是一份公开的规范定义 SKILL.md 的格式、字段约束、目录结构规范的核心是「Progressive Disclosure」Agent 启动时只装载 skill 的 name description约 100 token / skill决定要用了再读全文建议 ≤ 5000 tokenClaude Code 是该规范的第一个实现但任何 Agent 框架都可以实现这个规范DeepAgents 干的事情是把这个规范在 Python 端复现了一遍让任何用create_deep_agent起来的 Agent 都能消费同一套 SKILL.md。它甚至直说自己抄了 Claude CodeREADME 最底下那句不显眼的话Inspired by Claude Code: an attempt to identify what makes it general-purpose, and push that further.这意味着你之前在~/.claude/skills/攒了一堆 skill可以直接挂过来不需要任何格式转换团队内部沉淀的.claude/skills/项目级 skill同样可以你新写的 SKILL.md两边都能用这是 Day 13 我决定单独写一篇的根本原因——它不是又一个框架专属配置它是一个跨厂商生态位。二、Day 13 在哪一层12 天计划已经收尾。Day 13 是补漏Day 5 讲了Tool怎么把函数注册给 AgentDay 7 讲了Workflow怎么编排多步流程Day 8 讲了Sub-agent怎么开子 Agent 处理子任务Day 13本篇讲 Skill——前面三个都不太合适放的那一类东西Skill 跟 Tool / Sub-agent 是平行抽象不是替代关系。后面专门有一节比这件事。三、源码层面一个中间件 一个 system prompt 模板完了我把middleware/skills.py通读后得出一个让我自己也有点意外的结论DeepAgents 的 Skills 系统单文件 1068 行 Python——其中近七成是 docstring 和类型注解去掉这些以后核心实现只剩 380 行。整个系统就两个东西一个 AgentMiddleware 子类 一段 system prompt 模板。下面把架构画出来图 1SkillsMiddleware 通过两个 hook 介入——before_agent 做加载wrap_model_call 做注入3.1SkillsMiddleware干两件事读源码可以看到整个SkillsMiddleware类就是AgentMiddleware的子类重写了几个关键钩子middleware/skills.py:748起的SkillsMiddleware定义钩子时机干什么before_agentAgent 启动时跑一次扫描所有 source 目录下载并解析 SKILL.md 的 YAML frontmatter结果写进state[skills_metadata]wrap_model_call每轮模型调用前拿skills_metadata按模板拼出一段 “## Skills System…”追加到system_messageabefore_agent/awrap_model_call同上异步版本用await backend.als()/adownload_files()注意一个我看源码才意识到的细节class SkillsState(AgentState): skills_metadata: NotRequired[Annotated[list[SkillMetadata], PrivateStateAttr]]PrivateStateAttr是 LangChain Middleware 的私有状态标注——它不会被传递给 sub-agent。也就是说每个 sub-agent 都得自己挂自己的 SkillsMiddleware主 Agent 加载好的 metadata 不会污染子 Agent 的上下文。这个设计后面讲 Sub-agent 边界的时候再回来看。3.2 一个 skill 到底是什么按规范一个 skill 一个目录 一个 SKILL.md 文件my-skill/├── SKILL.md # 必须YAML frontmatter Markdown 正文├── scripts/ # 可选可执行代码├── references/ # 可选参考文档└── assets/ # 可选静态资源SKILL.md 的 frontmatterDeepAgents 的解析逻辑在_parse_skill_metadata函数里middleware/skills.py:366起---name: pdf-processing # 必填1-64 字符小写字母数字加单连字符description: Extract PDF... # 必填1-1024 字符license: Apache-2.0 # 可选compatibility: Python 3.10 # 可选1-500 字符metadata: # 可选任意 key-value author: exampleallowed-tools: Bash Read # 可选实验性空格分隔---# 正文随你写源码里有几个我觉得有意思的硬约束name必须等于父目录名_validate_skill_name里这一行if name ! directory_name: return False——这强制规范化防止两个目录用同名 skill 互相覆盖单文件最大10 MBMAX_SKILL_FILE_SIZE——防御性的 DoS 防护因为加载逻辑会把整个文件读进内存解析description超过 1024 字符会自动截断不会报错——这点要注意过长 description 会被默默砍掉3.3 多 Source 叠加的 “last-wins” 是怎么实现的这是 Skills 系统最被低估的设计点。你可以同时挂多个 source按顺序加载后挂的覆盖先挂的sources[ /skills/base/, # 框架自带最低优先级 ~/.claude/skills/, # 个人 skill .claude/skills/, # 项目 skill最高优先级]源码实现极其朴素before_agentmiddleware/skills.py:941起all_skills: dict[str, SkillMetadata] {}for source_path in self.sources: source_skills, source_error _list_skills_with_errors(backend, source_path) for skill in source_skills: all_skills[skill[name]] skill # 同名直接赋值后挂的赢就一个 dict。但这就是「base → user → project」三层 skill 叠加的全部秘密。它对应的实际意义base 层放公司/团队的基础 skill强制全员继承user 层放个人偏好比如「我喜欢用中文写注释」project 层放当前项目的硬规则比如「这个 repo 用 pytest 不用 unittest」跟 Python 的 ChainMap、Git 的 config 优先级、CSS 的级联是完全一样的设计哲学。四、Progressive Disclosure到底省了多少 token这是 Skills 系统真正的卖点。我把启动到激活的完整时序画出来图 2三个阶段——启动扫描、每轮注入、按需激活每个阶段花的 token 量级不同来做个粗略的 token 对比。这里用规范建议的上限做估算单个 SKILL.md 建议正文 ≤ 5000 tokenagentskills.io 推荐metadata 部分约 100-200 tokenname 最多 64 字符 description 最多 1024 字符。假设你有 20 个 skill做法 A全塞 system prompt很多人最初的做法启动注入20 × 5000 100,000 token上限每轮 prompt 都带~100,000 tokenLLM 决策在十万 token 里挑要用哪个模型 context 直接被 system 占满每次 input 都贵模型注意力还会被冗余信息淹没。做法 BProgressive DisclosureDeepAgents 默认启动注入仅 metadata20 × ~150 ~3,000 token每轮 prompt 都带~3,000 token触发激活LLM 决定用 pdf-processing - 调 read_file(limit1000)单 skill 全文≤ 5,000 token只在用到的那一轮带最不利情况下做法 B 也比做法 A 少了一个数量级的常驻 token这个差距随 skill 数量线性放大。这个估算用的是规范建议的上限实际 SKILL.md 大多比 5000 token 短差距会更大。source 里把这个意图写得很直白SKILLS_SYSTEM_PROMPTmiddleware/skills.py:705Skills follow a **progressive disclosure** pattern - you see their name and description above, but only read full instructions when needed:1. Recognize when a skill applies2. Read the skills full instructions: Use read_file ... Pass limit1000 since the default of 100 lines is too small for most skill files.注意第 2 步那个limit1000——这是给 LLM 的明确指令。默认的read_file只读 100 行对大多数 skill 不够所以模板里把这个值固定写死提示给模型。一个小细节但能看出工程上踩过的坑。Progressive Disclosure 的代价这套设计有一个不太被提及的成本它把「要不要激活 skill」的决策权交给了 LLM。如果 description 写得不好LLM 不会激活——skill 等于白挂如果 description 写得太宽泛LLM 在不该激活的时候也激活——浪费 read_file 一轮多个 skill 描述重叠LLM 可能挑错的那个所以 SKILL.md 的description字段是整个体系最值钱的字段。规范甚至写明要求Should describe both what the skill doesand when to use it. Should include specific keywords that help agents identify relevant tasks.「用途 触发条件 关键词」三件套缺一不可。我自己写 SKILL.md 都会先把这一行打磨 5 分钟。五、跟 Tool / Sub-agent 摆在一起看到这里我突然意识到一件事DeepAgents 提供了三种「让 Agent 多会一点东西」的机制三者完全不能互相替代。图 3三种能力扩展的本质、加载时机、context 成本、适合与不适合的场景我把决策树写出来——你下次想给 Agent 加点东西时对照这个决定该选哪种你要加的是「一个确定性动作」→ 用 Tool调一个 REST API、查一次数据库、跑一个计算输入输出有明确 schema、结果可以复现、不需要 LLM 二次理解例子get_weather(city)、query_user_orders(uid)Tool 的代价是它的完整 schema 必须进 system promptOpenAI / Anthropic 都这样所以加多了 context 涨得快。你要加的是「一套做事的方法 / SOP」→ 用 Skill「怎么做技术评审」「怎么写公众号文章」「怎么从 PDF 抽表格再交叉验证」内容是指令不是函数执行靠 LLM 理解 调用现有 tool 组合例子本仓库~/.opencode/skills/creator-weixin/SKILL.md里面写了一整套微信公众号文章的写作规范、自查清单、图表风格——LLM 读完按它去写Skill 的优势是 progressive disclosure 控成本加 100 个 skill 也不会爆 context劣势是结果不确定性高——同一个 SKILL.md 不同模型读出来的产出可能不一样。你要加的是「需要独立思考多步的子任务」→ 用 Sub-agent子任务复杂到需要自己有完整的 reasoning loop主 Agent 不希望子任务的中间 tool_call 污染自己的上下文例子「研究 LangChain 最新版本变化」——主 Agent 给一句话sub-agent 自己 plan、自己调搜索工具、自己整理最后只把结论返回Sub-agent 最贵——它是一个完整的 Agent 实例自己有 LLM 调用、自己有 context 窗口。别用 sub-agent 干 tool 该干的事。三者还能组合最后这一点 Day 8 没讲透Day 13 补回来Skill 可以告诉 LLM 该调哪些 ToolSub-agent 可以独立挂自己的 Skill。比如一个code-reviewskill 可能写着1. 先用 read_file 读出 PR 涉及的所有文件2. 用 grep 找出所有可能的 SQL 注入点3. 用 task 调 sub-agent security-reviewer 做深度审查整套 SOP 就在 skill 里固化下来LLM 读完按部就班执行——这才是 Skill 的真正价值。它不是替代 Tool / Sub-agent它是它们的编排说明书。六、最小可运行 Demo把 ~/.claude/skills 直接挂到 DeepAgents废话讲完看代码。下面这套代码是基于源码 API 直接读出来的最小写法前面三节涉及的所有机制都跑通一遍。6.1 准备一个 skill如果你已经有~/.claude/skills/可以跳过。没有的话造一个最简单的mkdir -p ~/.claude/skills/sql-reviewcat ~/.claude/skills/sql-review/SKILL.md EOF---name: sql-reviewdescription: Review SQL queries for performance issues and common bugs. Use when the user asks to review, optimize, or check SQL/HiveQL/Spark SQL code.---# SQL Review SkillWhen reviewing a SQL query, walk through these checks in order:1. **Full table scan**: does any subquery miss a WHERE on the partition key?2. **Join order**: largest table on the left (broadcast hint for small dim tables)?3. **DISTINCT after GROUP BY**: redundant?4. **Window function**: PARTITION BY missing leads to scan-all-data?5. **Cartesian product**: any JOIN missing the ON clause?Output format:- One issue per line- Severity tag: [HIGH] / [MEDIUM] / [LOW]- Suggested fix in one sentenceEOF这个 SKILL.md同时是合法的 Claude Code skill 和合法的 DeepAgents skill——一份文件两边都能跑。6.2 挂载到 DeepAgentsimport osfrom deepagents import create_deep_agentfrom deepagents.backends.filesystem import FilesystemBackend# 用 FilesystemBackend 直读本地文件root_dir 设到家目录backend FilesystemBackend(root_diros.path.expanduser(~))agent create_deep_agent( modelopenai:gpt-4o-mini, backendbackend, skills[.claude/skills/], # 相对 root_dir 的路径 system_promptYou are a senior data engineer.,)result agent.invoke({ messages: [{role: user, content: 帮我 review 这段 SQLSELECT u.user_id, COUNT(DISTINCT o.order_id)FROM user u JOIN orders o ON u.user_id o.user_idWHERE o.dt 2024-01-01GROUP BY u.user_id}]})print(result[messages][-1].content)按源码逻辑跑出来你应该能观察到三件事开 LangSmith trace 或直接打 log 验证第一轮Agent 收到消息system prompt 已经被wrap_model_call注入了 “## Skills System …sql-review: Review SQL queries…”第二轮LLM 看到 description 里的「Use when the user asks to review … SQL」匹配发出read_file(file_path.claude/skills/sql-review/SKILL.md, limit1000)的 tool call第三轮拿到完整 SKILL.md 后按里面的 5 条 check 逐条输出 review 结果如果第 2 步没发生LLM 没激活 skill通常是 description 写得不够具体或者用户 prompt 的关键词跟 description 没对上——回去把 description 重写一下加上明确的触发关键词「SQL」「HiveQL」「review」这类。注意第 2 步是 LLM 自主决定的不是中间件强制的。如果换一个能力较弱的模型比如本地 7B它可能不会激活 skill——这是 Progressive Disclosure 的固有代价前面讲过。6.3 进阶多源叠加agent create_deep_agent( modelanthropic:claude-sonnet-4-5, backendbackend, skills[ .claude/skills/team-base/, # 团队基础 skill低优先级 .claude/skills/, # 个人 skill # 用 (path, label) 元组给 source 取显示名否则两个 skills 目录会撞名 # 注意当前 create_deep_agent 的 skills 参数只接 list[str] # 如果要 (path, label) 元组需要手动构造 SkillsMiddleware 传 middleware 参数 ], system_promptYou are a senior engineer.,)如果有同名 skill后挂的赢。这是 source 顺序敏感的——别搞反。6.4 在 Sub-agent 里独立挂 skill源码graph.py:629有这段subagent_skills spec.get(skills)if subagent_skills: subagent_middleware.append(SkillsMiddleware(backendbackend, sourcessubagent_skills))所以每个 sub-agent 可以有自己的 skill 集——主 Agent 的 skill 不会被继承下去子 Agent 也不会污染主 Agent。前面提到的PrivateStateAttr就是为了这个隔离设计的。agent create_deep_agent( modelopenai:gpt-4o-mini, backendbackend, skills[.claude/skills/], # 主 agent 用通用 skill subagents[{ name: security-reviewer, description: Security audit specialist, skills: [.claude/skills/security/], # 子 agent 用专精 skill }],)这是工程上很重要的一点——避免 skill 列表无脑膨胀到所有 Agent 都看到。七、跟 Claude Code Skills 的实际差异源码对照讲到这里必须把「跨平台复用」这件事拆开看不能只说「兼容」就过去。我把目前能确认的差异点列一下维度Claude CodeDeepAgentsSKILL.md 格式agentskills.io 规范完全相同可双向迁移加载机制进程启动时扫描~/.claude/skills/和 CWD 的.claude/skills/由skills[...]参数显式指定 source 路径激活方式LLM 决定Progressive DisclosureLLM 决定同 Progressive Disclosurescripts 执行内置 Bash tool 直接跑需要 backend 支持executetoolSandbox / LocalShellallowed-tools 字段严格执行限制 skill 能调哪些 tool仅当作元信息暴露给 LLM不强制截至当前版本多 source 叠加user project 两层固定任意多层顺序自定义最值得注意的一条allowed-tools字段。规范说它是 “experimental”DeepAgents 在_parse_allowed_tools里只是把它读出来挂在 metadata 上并不会真的强制限制 skill 能调哪些工具——它只会让 LLM 在 system prompt 看到这条信息。也就是说当前版本截至 2026 年 6 月DeepAgents 的 skill 安全边界靠的是 LLM 自己「听话」。如果你在生产环境用 skill 跑敏感操作别只依赖 allowed-tools要在 backend 层用 permissions 或者 HITL 拦一道。这是规范 vs 实现的一个典型 gap写文章不交代清楚就是不诚实。八、什么时候别用 Skill讲完优势也讲讲不适合的场景。我自己踩过的8.1 输出需要严格确定性的场景Skill 的执行靠 LLM 阅读理解 markdown不同模型、不同温度、甚至同一模型不同 turn 都可能产出不一样。如果你的需求是「给我一个能严格按规则跑的 pipeline」写 Tool 或者写一段确定性 Python 代码别写 Skill。我自己的判断标准如果两个一线工程师严格按 SKILL.md 执行产出会不会一致如果不会那 LLM 执行也不会一致。8.2 改动频繁的场景Skill 写完是「固化」的——改一次就要重新测一次 LLM 在不同模型上的执行表现。如果你的 SOP 每周都在改Skill 不如直接动态拼 prompt来得灵活。8.3 简单到不需要复用的场景只用一次的指令不要包装成 Skill。Skill 是为「跨项目、跨 Agent、跨人复用」存在的——一次性的事直接写在用户消息里就行。8.4 LLM 不够强的场景Progressive Disclosure 的工作原理是「让 LLM 自己决定要不要读 SKILL.md 全文」——这个决策对模型的 instruction following 能力有要求。我自己在gpt-4o-mini上跑前面那个 sql-review 例子是稳定能激活的但机制上更弱的模型很可能出现两类问题要么不激活 skill白挂要么激活了但不严格按 SKILL.md 步骤走。这跟 ReAct 模式在弱模型上经常跑飞是同一个原因。建议做法如果你用的不是 GPT-4 / Claude Sonnet 4 级别的模型先用 LangSmith 把几个典型用户输入跑一遍 trace确认 LLM真的会发出read_file(SKILL.md, limit1000)的 tool_call 再上 skill——别把这件事的成功率当默认值。九、Skill 不是新东西但它把一件事变得便宜了整篇笔记看到这里可以收一下了。Skill 这套机制从技术角度看一点都不复杂——它就是「Markdown 文档 Progressive Disclosure 加载」。任何 Agent 框架都能在一周内自己实现一遍。但它的真正价值在两个工程层面的小事第一它定义了一个跨厂商的标准目录布局——.claude/skills/name/SKILL.md。我可以在 Claude Code 里写 skill在 DeepAgents 里直接用下次出现新框架只要它实现 agentskills.io 规范我的 skill 也能跑。这种「写一次到处跑」的能力对真正在生产环境维护 Agent 的人价值很大。第二它把 SOP / 最佳实践这种**「半结构化经验知识」**有了一个稳定的存放地点。以前这些东西要么散在prompts/文件夹里没人管要么塞进 system prompt 越塞越长。现在有了 SKILL.md团队的领域专家把套路写下来所有 Agent 都能受益。但它没解决的事也要清楚不解决 LLM 执行的不确定性不解决安全边界allowed-tools 当前不强制不解决 skill 数量爆炸后的 description 撞车问题不解决弱模型激活率低的问题下一步该做哪一步如果你已经在用 Claude Code先把现有 skill 挂到 DeepAgents 跑一遍 demo确认能跑通如果你在用 DeepAgents 但还没用 skill先把一个你最常重复写的 SOP 抽成 SKILL.md——通常是「代码评审」「文档审阅」「数据探查」这类高频流程如果你打算把 skill 上生产先在 backend 层加 permissions不要依赖 allowed-toolsSkill 不会让你的 Agent 突然变强但它能让你少写很多重复 prompt——这对工程师就够了。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】