本文深入剖析了Claude Agent Skills的底层运作机制强调Skill作为提示词扩展而非传统函数调用的本质。文章详细解读了元工具Skill的设计、动态加载机制、双重上下文注入等关键环节并通过实际调用日志进行验证。同时提供了工程实践清单包括技能分层、description编写、权限控制等最佳实践帮助开发者理解和应用Skills技术实现AI工程能力的提升。太长不看版• Skill 的本质是提示词扩展不是函数调用不是插件。系统把SKILL.md的内容按需注入对话上下文让模型临时学会一套做法。• 管理所有技能的是一个名为Skill的元工具Meta-Tool。模型先看到通讯录名称 简介选中后才加载完整操作手册。• 选择哪个技能完全依赖 LLM 自身的语言理解——没有路由器、没有正则、没有分类器决策发生在 Transformer 的前向传播中。• 一次调用同时改写两件事对话上下文注入指令与工作流执行上下文临时放行工具权限、可选切换模型。• 代价也很现实每次注入可能额外消耗 1500 tokens技能越多歧义与误触发越难避免。• 工程启示把 Skill 当成可版本化的配置资产来运营而不是写完扔在那里。先把 Skill 放回正确的分类很多人把 Skill 直觉类比成函数调用或插件。这个类比会带偏。Skill 不运行 Python不运行 JavaScript背后也没有 HTTP 服务器或函数调用。你写在SKILL.md里的不是可执行代码。系统做的事情是把文档内容注入模型的短期记忆并临时给它配一套可用工具让它照着文档里的步骤自己完成任务。Han Lee 在原文里说得很精确Skills are specialized prompt templates that inject domain-specific instructions into the conversation context.Skills 不直接解决问题它让模型准备好去解决问题。用一个比喻来说传统的 System Prompt 像是让全科医生在上岗前背熟一本厚厚的通识手册。手册越厚记忆负担越大没写到的病就看不了。Skill 更像是给这个医生配了一本通讯录。平时只知道有心外科专家、有骨科专家遇到特定手术时再呼叫专家到场。专家自带全套设备和手术指南做完之后退出医生恢复常态。这个比喻里藏着 Skill 最核心的设计思想渐进式披露Progressive Disclosure——只在需要时才加载详细信息。下面这张图是整个 Skill 系统的工作流概览先有个全局印象后面再逐段拆所以 Skill 的能力边界最终由两部分决定模型的指令遵循与推理能力——能不能读懂手册、照着步骤做你提供的工具是否足够可用、可控——手册里写了用 pdftotext 提取但如果这个工具没有暴露给模型或者返回值不结构化手册写得再好也执行不了Tools 和 Skills到底差在哪这个问题值得用一张表说清楚。维度ToolsSkills执行方式调用后同步执行返回即时结果先注入指令提示词扩展再由模型按指令执行核心价值做一个动作指导一类工作流返回值操作结果对话上下文 执行上下文变更典型例子Read、Write、Bashskill-creator、internal-comms并发安全通常安全不保证并发安全Token 开销很小约 100 tokens显著约 1500 tokens/次类型多种始终为prompt一句话总结Tools 直接解决问题Skills 让模型准备好去解决问题。这个区分很重要。如果你把 Skill 当 Tool 来设计——期望它调用一下就返回结果——你会困惑于它为什么什么也没做。它确实什么也没执行它做的是改写模型的认知和权限环境。元工具设计为什么不把所有技能都塞进 prompt这是我觉得整个 Skill 系统最聪明的地方。如果一开始就把所有技能的完整说明都塞进系统提示词你会立刻撞上两堵墙。第一堵是成本。假设你有 20 个技能每个SKILL.md平均 2000 tokens全部预加载就是 40000 tokens。大部分情况下用户一次对话只会用到其中一两个剩下的全是浪费。第二堵更隐蔽过长的提示词会让模型抓不住重点。该触发的技能触发不了不该触发的反而乱跳出来。指令遵循能力反而下降了。Claude Code 的思路是做一个**“通讯录 叫号系统”**• 启动时只汇总每个技能的名称与一句话简介足够让模型做选择• 真正要用某个技能时再把它的SKILL.md正文动态加载进来从 Han Lee 拆出的源码来看这个通讯录的实现方式非常具体它不在 system prompt 里而是嵌入在Skill元工具的description字段中作为 API 请求tools数组的一部分。具体的 API 请求结构长这样{ model: claude-sonnet-4-5-20250929, system: You are Claude Code..., messages: [...], tools: [ { name: Skill, description: Execute a skill...\n\navailable_skills\n\pdf\: Extract text from PDF...\n\skill-creator\: Create new skills...\n/available_skills, input_schema: { type: object, properties: { command: { type: string } } } }, { name: Bash, ... }, { name: Read, ... } ]}注意available_skills那一段——所有可用技能的名称和描述都格式化在这里面。Claude 读到这个列表用自己的语言理解能力去匹配用户意图。这里面没有正则匹配没有嵌入向量没有分类器。决策完全发生在模型的推理过程中。用 Han Lee 的原话说This is pure LLM reasoning. The decision happens inside Claude’s forward pass through the transformer, not in the application code.还有一个容易忽略的细节这个通讯录有大小预算。available_skills列表受默认约 15,000 字符的预算约束。技能越多、description 越长越容易互相挤掉。这就像一本通讯录只有这么多页你的名字写得太长就把别人挤出去了。一次调用到底发生了什么双重上下文注入这是理解 Skill 机制最关键的部分。传统的提示词只能改变模型看到什么文字。Skill 多做了一件事它还能临时改变模型的权限环境。这就是所谓的双重上下文注入。对话上下文注入你说什么模型就照着做什么系统把SKILL.md的正文作为消息注入到对话历史里。但这里有一个设计上的矛盾模型需要看到几千字的详细指令才能正确执行。但用户不需要看到这些——几千字的内部指令刷屏聊天界面直接没法用了。解决办法是把注入拆成两条消息第一条给人看的isMeta: false在 UI 中可见command-messageThe pdf skill is loading/command-messagecommand-namepdf/command-name50 到 200 个字符告诉用户系统正在加载哪个技能。第二条给模型看的isMeta: trueUI 隐藏但随请求发给 APIYou are a PDF processing specialist.Your task is to extract text from PDF documents using the pdftotext tool.## Process1. Validate the PDF file exists2. Run pdftotext command to extract text3. Read the output file4. Present the extracted text to the user## Tools Available- Bash(pdftotext:*) - For running pdftotext command- Read - For reading extracted text- Write - For saving results if needed...可能 500 到 5000 字是真正指导模型工作的核心。为什么非要拆成两条Han Lee 在原文里分析得很透彻如果合并成一条消息你就被迫在刷屏和黑箱之间二选一。拆开之后两条消息各司其职——一条负责透明度一条负责指令传递。用他的话说这是在做meta-prompting for meta-tools。对比一下普通 Tool 调用和 Skill 调用的消息结构差异就很清楚了左边两步就结束右边要注入五六条消息才真正开始干活。这也是为什么 Skill 的 token 开销比普通工具高一个数量级约 1500 tokens/次。从实际调用日志来看消息序列是这样的tool_useAgent 调用 Skill Tool传入 skill 名称tool_result返回 “Launching skill: xxx”只做确认user messageSKILL.md的完整内容作为一条新的 user message 注入注意第三步——skill 内容不是通过 tool_result 塞回去的而是作为 user message 注入的。从语义上讲tool_result 意味着工具执行的返回结果但 skill 内容并不是执行结果——它是一份操作指南。作为 user message 注入语义上更像用户补充了一些背景资料模型在后续推理中会把它当作上下文参考。执行上下文修改不只改文字还改权限Skill 还能临时修改运行环境。这是它比传统提示词真正多出来的能力。具体来说它通过一个contextModifier函数来实现•放行工具权限allowed-tools比如pdf技能可以临时授予Bash(pdftotext:*)权限后续调用无需用户逐次确认•切换模型复杂任务可以从 Sonnet 切换到 Opus 做深度推理从安全视角看这一步非常关键。它改变的是权限边界不只是模型看到的文字。一个普通对话可能不允许 Claude 随意跑 Bash 命令但当pdfSkill 被加载时系统会临时把特定命令写进alwaysAllowRules——后续模型调用这些工具就不再弹窗确认。这既是便利也是风险点。这也是为什么allowed-tools的设计需要像生产权限一样认真对待。之前在 代码就是一切Anthropic 为什么从 Agent 转向 Skills[1] 里聊过Anthropic 选择 Skills 而非更激进的 Agent 自主模式核心考量之一就是可控性——权限可声明、行为可审计、范围可限定。从一次完整调用看清全链路我建议你用事件链去理解 Skill而不是用功能列表。以一个读取飞书文档的 Skill 为例用户说帮我看一下这个飞书文档整个过程用序列图表示用文字展开来看① 用户请求帮我看一下这个飞书文档② Agent 读到 Skill 工具描述里的 available_skills 列表 → 看到 feishu-docx: Export Feishu/Lark cloud documents to Markdown... → 推理判断这个任务需要 feishu-docx 技能③ Agent 调用 Skill 工具command: feishu-docx④ 系统验证 - skill 是否存在 ✓ - 类型是否为 prompt ✓ - 是否禁止模型调用 ✓ - 权限检查 → 询问用户执行 feishu-docx skill → 用户批准⑤ 系统加载 SKILL.md 正文注入两条消息 - 元数据可见正在加载 feishu-docx skill - 完整指令隐藏怎么安装工具、怎么调用命令、输出格式是什么⑥ 系统修改执行上下文 - 放行 allowed-tools 里声明的工具权限 - 如果指定了 model切换模型⑦ 完整消息数组发送到 API⑧ Agent 带着新指令和新权限开始执行 → 调用 Bash: feishu-docx export https://... --stdout → 获取结果格式化呈现给用户把这个链路记住很多线上怪问题就能更快定位没触发先检查 frontmatter——description 字段有没有有没有被标记disable-model-invocation: true技能有没有出现在available_skills列表里从 Han Lee 拆出的过滤代码来看技能至少要满足有 description 或 when_to_use、类型为 prompt、未禁用模型调用、来源非 builtin 或为 mode command。任何一项不满足技能就不会出现在通讯录里。触发错了description 语义撞车模型选了相邻技能。解法是在 description 里不光说我做什么还要说我不做什么。触发了但没跑对SKILL.md的步骤不够确定性或者工具输出不结构化模型读不懂返回值在重试里烧 token。写 Skill 时容易被忽略的工程细节description 是你的产品入口这个字段直接决定模型能不能在对的时候找到你的技能。系统的处理逻辑是这样的如果你同时提供了when_to_use系统会把它拼接到 description 后面——${description} - ${whenToUse}。这个拼接后的字符串就是模型在available_skills列表里看到的全部信息。但 Han Lee 特别提醒了when_to_use在代码库里大量出现却没有出现在任何 Anthropic 官方文档中。它可能是废弃功能、可能是实验性功能、也可能是尚未发布的规划功能。安全的做法是把使用指南直接写进description不要把生产行为绑死在一个未文档化的字段上。写 description 有一个原则用清晰的、面向动作的语言。比如skill-creator的 description 是这么写的Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude’s capabilities with specialized knowledge, workflows, or tool integrations.明确说了什么时候该用。这种写法比一个很有用的技能创建工具好十倍。allowed-tools是权限边界不是便利清单一个常见的错误是把所有能想到的工具都列上去。这会扩大攻击面破坏安全模型。# ✅ 只做文件操作allowed-tools: Read,Write,Edit,Glob,Grep# ✅ 限制到具体 git 命令allowed-tools: Bash(git status:*),Bash(git diff:*),Bash(git log:*),Read,Grep# ✅ 脚本自动化限制到特定脚本allowed-tools: Bash(python {baseDir}/scripts/*:*), Read, Write# ❌ 不必要的攻击面allowed-tools: Bash,Read,Write,Edit,Glob,Grep,WebSearch,Task,Agent原则很简单只包含技能实际需要的工具。如果只是读写文件Read,Write就够了。能限制到命令模式就不要放开整个 Bash。SKILL.md要写成可执行的操作手册我见过最多的失败案例是技能文档写得像产品说明书——步骤全是大词模型读完之后大致明白但不确定该怎么做。Han Lee 给出了一个推荐的内容结构# 简要用途说明1-2句话## Overview## Prerequisites## Instructions### Step 1: [第一个动作]### Step 2: [下一个动作]## Output Format## Error Handling## Examples## Resources还有四条最佳实践值得记住• 正文控制在 5000 词约 800 行以内避免上下文过载• 用祈使句“分析代码中的…”而不是第二人称“你应该分析…”• 详细内容引用外部文件用{baseDir}占位不要硬编码绝对路径• 确定性步骤该用脚本就用脚本——scripts/目录放可执行代码比自然语言可靠得多模型不怕长它怕不确定。目录结构的设计决定了 token 效率一个标准的技能包长这样my-skill/├── SKILL.md # 核心提示词与指令├── scripts/ # 可执行脚本├── references/ # 参考文档会被 Read 进上下文占 tokens└── assets/ # 模板与静态资源只按路径引用不占上下文这里有一个容易忽视的区别references/和assets/的 token 开销完全不同。references/里的文件会被 Claude 通过 Read 工具读进上下文——一个 10KB 的 markdown 文件会消耗对应的 token。assets/里的文件只按路径引用Claude 知道文件在哪但不会把内容读进来——一个 10KB 的 HTML 模板不消耗 token。这个区分直接影响你的 context window 管理。大型参考文档放references/模板和二进制文件放assets/。还有几个不太常见但很有用的字段•disable-model-invocation设为true技能从自动列表里消失只能通过/skill-name手动调用。适合危险操作、配置命令、需要用户明确控制的交互式工作流。•mode设为true技能归类为模式命令出现在技能列表顶部的特殊区域。适合debug-mode、expert-mode、review-mode这类设定工作上下文的场景。•model指定技能执行时使用的模型。默认继承会话模型复杂任务可以强制切到 Claude Opus。几种常见的 Skill 设计模式Han Lee 在原文里总结了几种在实践中验证过的技能设计模式非常实用。模式一脚本自动化复杂操作交给scripts/目录里的 Python 或 Bash 脚本。SKILL.md 只负责告诉模型运行这个脚本解析它的输出。适合数据处理、API 交互、多步计算。模式二读取-处理-写入最简单的模式——读输入、按指令转换、写输出。适合格式转换、数据清洗、报告生成。工具权限只需要Read, Write。模式三搜索-分析-报告先用 Grep 搜索代码库中的模式再读取匹配文件分析后生成结构化报告。适合代码审查、安全审计、质量分析。模式四向导式多步工作流把复杂任务拆成多个阶段每个阶段之间等待用户确认。适合配置向导、部署流程、需要人工把关的操作。模式五迭代深化第一遍做广度扫描第二遍对发现的问题做深度分析第三遍给出具体建议。适合代码审查、安全审计。选择哪种模式取决于你的任务是偏确定性用脚本还是偏探索性用迭代是一步到位读-处理-写还是需要人在环向导式。大多数场景下单 Agent 多 Skill 已经够用。真到了需要多 Agent 编排的时候可以翻翻之前写的 Claude Agent Teams 架构与实战拆解[1]。真正的工程化难点技能多了以后怎么管当技能从 5 个增长到 50 个问题会从能不能用变成怎么运营。我认为有四件事要前置。可观测性至少把这些埋点做出来• 触发了哪个 skill以及触发前的用户意图原文• 注入了多少 token• 工具调用次数、失败原因、重试次数• 每一步的中间产物结构化日志或可回放轨迹Skill 的执行过程涉及多个环节——description 匹配、内容注入、指令解析、工具调用——任何一个环节出问题最终表现都是没跑对或者没触发。但你想定位到具体是哪个环节就得看完整的对话日志。如果系统没有把这些中间状态都记录下来排查问题会非常痛苦。你不把这些变成数据就只能靠感觉调 prompt——而凭感觉调 prompt是最贵的调试方式。歧义与冲突治理技能撞车是常态不是例外。当两个 description 语义相近模型就面临选择困难。解法是把 description 写成任务边界不只说我做什么还要说我不做什么。给技能做分层也很有效•L0只做信息读取与整理低风险•L1能写文件、改配置中风险•L2能跑命令、能发请求高风险默认需要显式确认并发安全问题这个问题原文里专门提到了Skills arenot concurrency-safe。当你把多个技能当作可随意叠加的插件来设计很容易出现互相覆盖指令、权限边界混乱、顺序依赖不清晰的问题。技能越重——越是那种改变模型整体行为模式的——越要谨慎组合。版本化与回滚把 Skill 当成配置资产来管理SKILL.md加版本号、变更日志、回滚策略、灰度与 A/B 实验。怎么用 git 管理这些配置文件之前在 团队落地把 Claude Code 配置当代码管理[1] 里聊过同样的思路完全适用于 Skill。这会让你从写 prompt升级成运营能力资产。落地清单12 件事先把技能分层L0 到 L2默认只自动触发低风险技能。每个技能的 description 用一句话写清边界并明确它不做什么。allowed-tools最小化能限制到命令模式就不放开整个 Bash。高风险技能默认disable-model-invocation: true只允许手动调用。要求工具输出结构化JSON/YAML/表格并把 schema 写进SKILL.md。明确每一步的失败处理何时重试何时换工具何时停止请求用户补信息。观测做成默认能力记录触发 skill、注入开销、tool_calls、关键上下文。写文件、改配置、发请求、执行命令类动作做二次确认或沙箱化。给常见输入做校验与纠错策略路径不存在、权限不足、参数缺失。技能多了做目录化按业务域/角色/风险等级组织。建最小评测集10 到 30 条真实任务定期回归。把技能当成团队资产有人 review有人维护有人对线上效果负责。如何学习大模型 AI 由于新岗位的生产效率要优于被取代岗位的生产效率所以实际上整个社会的生产效率是提升的。但是具体到个人只能说是“最先掌握AI的人将会比较晚掌握AI的人有竞争优势”。这句话放在计算机、互联网、移动互联网的开局时期都是一样的道理。我在一线科技企业深耕十二载见证过太多因技术卡位而跃迁的案例。那些率先拥抱 AI 的同事早已在效率与薪资上形成代际优势我意识到有很多经验和知识值得分享给大家也可以通过我们的能力和经验解答大家在大模型的学习中的很多困惑。我们整理出这套AI 大模型突围资料包✅ 从零到一的 AI 学习路径图✅ 大模型调优实战手册附医疗/金融等大厂真实案例✅ 百度/阿里专家闭门录播课✅ 大模型当下最新行业报告✅ 真实大厂面试真题✅ 2026 最新岗位需求图谱所有资料 ⚡️ 朋友们如果有需要《AI大模型入门进阶学习资源包》下方扫码获取~① 全套AI大模型应用开发视频教程包含提示工程、RAG、LangChain、Agent、模型微调与部署、DeepSeek等技术点② 大模型系统化学习路线作为学习AI大模型技术的新手方向至关重要。 正确的学习路线可以为你节省时间少走弯路方向不对努力白费。这里我给大家准备了一份最科学最系统的学习成长路线图和学习规划带你从零基础入门到精通③ 大模型学习书籍文档学习AI大模型离不开书籍文档我精选了一系列大模型技术的书籍和学习文档电子版它们由领域内的顶尖专家撰写内容全面、深入、详尽为你学习大模型提供坚实的理论基础。④ AI大模型最新行业报告2025最新行业报告针对不同行业的现状、趋势、问题、机会等进行系统地调研和评估以了解哪些行业更适合引入大模型的技术和应用以及在哪些方面可以发挥大模型的优势。⑤ 大模型项目实战配套源码学以致用在项目实战中检验和巩固你所学到的知识同时为你找工作就业和职业发展打下坚实的基础。⑥ 大模型大厂面试真题面试不仅是技术的较量更需要充分的准备。在你已经掌握了大模型技术之后就需要开始准备面试我精心整理了一份大模型面试题库涵盖当前面试中可能遇到的各种技术问题让你在面试中游刃有余。以上资料如何领取为什么大家都在学大模型最近科技巨头英特尔宣布裁员2万人传统岗位不断缩减但AI相关技术岗疯狂扩招有3-5年经验大厂薪资就能给到50K*20薪不出1年“有AI项目经验”将成为投递简历的门槛。风口之下与其像“温水煮青蛙”一样坐等被行业淘汰不如先人一步掌握AI大模型原理应用技术项目实操经验“顺风”翻盘这些资料真的有用吗这份资料由我和鲁为民博士(北京清华大学学士和美国加州理工学院博士)共同整理现任上海殷泊信息科技CEO其创立的MoPaaS云平台获Forrester全球’强劲表现者’认证服务航天科工、国家电网等1000企业以第一作者在IEEE Transactions发表论文50篇获NASA JPL火星探测系统强化学习专利等35项中美专利。本套AI大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。资料内容涵盖了从入门到进阶的各类视频教程和实战项目无论你是小白还是有些技术基础的技术人员这份资料都绝对能帮助你提升薪资待遇转行大模型岗位。以上全套大模型资料如何领取