本文深入剖析了Claude Agent Skills的核心机制从本质到工程实践为程序员提供了一份可落地的工程清单。文章详细解释了Skills如何通过提示词扩展实现功能以及元工具、对话上下文注入、执行上下文修改等关键概念。此外还探讨了Skills的常见设计模式、工程化难点和落地清单帮助读者更好地理解和应用Claude大模型技能。我们都是架构师架构未来你来不来大年初一先给大家拜年了 假期这几天终于有整块时间把一直想读的几篇 Skill 底层分析啃完了。年前团队里就有人问过“Claude 的 Skill 我们能不能也搞一套” 当时没来得及细看趁这个假期把它彻底拆开。Skill 的热度这几周明显上来了。之前我也聊过几次但基本都停在怎么用这个层面。大多数讨论也是如此。我更关心第二个问题它到底靠什么工作真要判断这东西能不能在自己业务里用起来光看功能列表是不够的。你得知道它底层是怎么运作的动态加载机制长什么样有哪些限制条件。把机制想清楚了很多工程问题会自己浮出水面description 怎么写才不乱触发allowed-tools怎么收口才安全技能多了之后怎么避免互相打架这篇文章我按第一性原理把 Claude Agent Skills 的核心机制拆开再给一份可落地的工程清单。主要参考了 Han Lee 那篇Claude Agent Skills: A First Principles Deep Dive——质量非常高深入到了源码层面。结合实际的 Agent 调用日志做验证基本能把 Skill 的里外看透。本篇不重复基础概念直接进机制。如果你还不熟悉 Skill 的基本用法建议先看之前的 Anthropic 官方 33 页指南拆解: 构建Skills的最佳实践太长不看版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 的能力边界最终由两部分决定1. 模型的指令遵循与推理能力——能不能读懂手册、照着步骤做2. 你提供的工具是否足够可用、可控——手册里写了用 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-message command-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. ## Process 1. **Validate the PDF file exists** 2. **Run pdftotext command to extract text** 3. **Read the output file** 4. **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/次。从实际调用日志来看消息序列是这样的1.tool_useAgent 调用 Skill Tool传入 skill 名称2.tool_result返回 “Launching skill: xxx”只做确认3.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 架构与实战拆解。真正的工程化难点技能多了以后怎么管当技能从 5 个增长到 50 个问题会从能不能用变成怎么运营。我认为有四件事要前置。可观测性至少把这些埋点做出来触发了哪个 skill以及触发前的用户意图原文注入了多少 token工具调用次数、失败原因、重试次数每一步的中间产物结构化日志或可回放轨迹Skill 的执行过程涉及多个环节——description 匹配、内容注入、指令解析、工具调用——任何一个环节出问题最终表现都是没跑对或者没触发。但你想定位到具体是哪个环节就得看完整的对话日志。如果系统没有把这些中间状态都记录下来排查问题会非常痛苦。你不把这些变成数据就只能靠感觉调 prompt——而凭感觉调 prompt是最贵的调试方式。歧义与冲突治理技能撞车是常态不是例外。当两个 description 语义相近模型就面临选择困难。解法是把 description 写成任务边界不只说我做什么还要说我不做什么。给技能做分层也很有效L0只做信息读取与整理低风险L1能写文件、改配置中风险L2能跑命令、能发请求高风险默认需要显式确认并发安全问题这个问题原文里专门提到了Skills are not concurrency-safe。当你把多个技能当作可随意叠加的插件来设计很容易出现互相覆盖指令、权限边界混乱、顺序依赖不清晰的问题。技能越重——越是那种改变模型整体行为模式的——越要谨慎组合。版本化与回滚把 Skill 当成配置资产来管理SKILL.md加版本号、变更日志、回滚策略、灰度与 A/B 实验。怎么用 git 管理这些配置文件之前在 团队落地把 Claude Code 配置当代码管理 里聊过同样的思路完全适用于 Skill。这会让你从写 prompt升级成运营能力资产。落地清单12 件事1. 先把技能分层L0 到 L2默认只自动触发低风险技能。2. 每个技能的 description 用一句话写清边界并明确它不做什么。3.allowed-tools最小化能限制到命令模式就不放开整个 Bash。4. 高风险技能默认disable-model-invocation: true只允许手动调用。5. 要求工具输出结构化JSON/YAML/表格并把 schema 写进SKILL.md。6. 明确每一步的失败处理何时重试何时换工具何时停止请求用户补信息。7. 观测做成默认能力记录触发 skill、注入开销、tool_calls、关键上下文。8. 写文件、改配置、发请求、执行命令类动作做二次确认或沙箱化。9. 给常见输入做校验与纠错策略路径不存在、权限不足、参数缺失。10. 技能多了做目录化按业务域/角色/风险等级组织。11. 建最小评测集10 到 30 条真实任务定期回归。12. 把技能当成团队资产有人 review有人维护有人对线上效果负责。收个尾Skill 这套机制从设计上看相当优雅。它用一个元工具实现了按需加载领域知识的完整闭环同时保持了上下文窗口的高效利用。Han Lee 在原文结尾的总结我很认同By treating specialized knowledge as prompts that modify conversation context and permissions that modify execution context rather than code that executes, Claude Code achieves flexibility, safety, and composability that would be difficult with traditional function calling.但优雅归优雅拿到生产环境里用还需要补很多地基。还有一点很实在那些想用小尺寸模型来验证Skill 功能的想法建议直接放弃。光是意图识别就够呛更别说后面那些复杂的多步骤执行了。Skill 对模型的推理能力、指令遵循能力和多步规划能力都有相当高的要求。这不是你换个便宜模型就能省下来的。如果你打算在团队里试我的建议是从一个低风险技能起步先把可观测性 权限最小化 结构化输出三件事打稳再谈规模化。团队怎么落地 Claude Code 的工作流可以看 AI 编程实践从 Claude Code 到团队协作的 6 个落地抓手 和 把 Claude Code 用成工程工具8 条黄金法则与一套可复用工作流。别急着搞一套。先把一个跑通。最后如果说程序员已经是高薪职业那么干AI的程序员就是高薪中的高薪。现在的市场已经用数据给程序员指明了方向学****AI大模型就是冲刺高薪的最优解看着身边越来越多的同行转型大模型、拿到高薪offer很多人心里都动了心但真正的难题来了零基础小白不知道从哪入门有基础的程序员找不到系统学习路径实战项目练手无门面试不知道考什么别慌今天就给大家整理了一份【2026年最新版】AI大模型免费学习资源包覆盖从入门到实战、从理论到面试、从基础到进阶的全流程所有资料均已整理归档无冗余、无套路免费分享给每一位想抓住AI风口的程序员和小白扫码免费领取全部内容1、大模型系统化学习路线2、大模型学习书籍文档3、AI大模型最新行业报告4、大模型项目实战配套源码5、大模型大厂面试真题四阶段精细化学习规划附时间节点可直接照做结合上述资源给大家整理了一份可直接落地的四阶段学习规划总时长约2个月小白可循序渐进程序员可根据自身基础调整节奏高效掌握大模型核心能力快速实现从“入门”到“能落地、能面试”的跨越。第一阶段10天初阶应用该阶段让大家对大模型 AI有一个最前沿的认识对大模型 AI 的理解超过 95% 的人可以在相关讨论时发表高级、不跟风、又接地气的见解别人只会和 AI 聊天而你能调教 AI并能用代码将大模型和业务衔接。大模型 AI 能干什么大模型是怎样获得「智能」的用好 AI 的核心心法大模型应用业务架构大模型应用技术架构代码示例向 GPT-3.5 灌入新知识提示工程的意义和核心思想Prompt 典型构成指令调优方法论思维链和思维树Prompt 攻击和防范…第二阶段30天高阶应用该阶段我们正式进入大模型 AI 进阶实战学习学会构造私有知识库扩展 AI 的能力。快速开发一个完整的基于 agent 对话机器人。掌握功能最强的大模型开发框架抓住最新的技术进展适合 Python 和 JavaScript 程序员。为什么要做 RAG搭建一个简单的 ChatPDF检索的基础概念什么是向量表示Embeddings向量数据库与向量检索基于向量检索的 RAG搭建 RAG 系统的扩展知识混合检索与 RAG-Fusion 简介向量模型本地部署…第三阶段30天模型训练恭喜你如果学到这里你基本可以找到一份大模型 AI相关的工作自己也能训练 GPT 了通过微调训练自己的垂直大模型能独立训练开源多模态大模型掌握更多技术方案。到此为止大概2个月的时间。你已经成为了一名“AI小子”。那么你还想往下探索吗为什么要做 RAG什么是模型什么是模型训练求解器 损失函数简介小实验2手写一个简单的神经网络并训练它什么是训练/预训练/微调/轻量化微调Transformer结构简介轻量化微调实验数据集的构建…第四阶段20天商业闭环对全球大模型从性能、吞吐量、成本等方面有一定的认知可以在云端和本地等多种环境下部署大模型找到适合自己的项目/创业方向做一名被 AI 武装的产品经理。硬件选型带你了解全球大模型使用国产大模型服务搭建 OpenAI 代理热身基于阿里云 PAI 部署 Stable Diffusion在本地计算机运行大模型大模型的私有化部署基于 vLLM 部署大模型案例如何优雅地在阿里云私有部署开源大模型部署一套开源 LLM 项目内容安全互联网信息服务算法备案…扫码免费领取全部内容6、这些资料真的有用吗这份资料由我和鲁为民博士(北京清华大学学士和美国加州理工学院博士)共同整理现任上海殷泊信息科技CEO其创立的MoPaaS云平台获Forrester全球’强劲表现者’认证服务航天科工、国家电网等1000企业以第一作者在IEEE Transactions发表论文50篇获NASA JPL火星探测系统强化学习专利等35项中美专利。本套AI大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。资料内容涵盖了从入门到进阶的各类视频教程和实战项目无论你是小白还是有些技术基础的技术人员这份资料都绝对能帮助你提升薪资待遇转行大模型岗位。这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】https://mp.weixin.qq.com/s/mt8kU-8roiiqwrcWSUjolA
小白程序员必看：收藏这份Claude大模型技能（Skills）学习指南
发布时间：2026/6/4 16:28:52
本文深入剖析了Claude Agent Skills的核心机制从本质到工程实践为程序员提供了一份可落地的工程清单。文章详细解释了Skills如何通过提示词扩展实现功能以及元工具、对话上下文注入、执行上下文修改等关键概念。此外还探讨了Skills的常见设计模式、工程化难点和落地清单帮助读者更好地理解和应用Claude大模型技能。我们都是架构师架构未来你来不来大年初一先给大家拜年了 假期这几天终于有整块时间把一直想读的几篇 Skill 底层分析啃完了。年前团队里就有人问过“Claude 的 Skill 我们能不能也搞一套” 当时没来得及细看趁这个假期把它彻底拆开。Skill 的热度这几周明显上来了。之前我也聊过几次但基本都停在怎么用这个层面。大多数讨论也是如此。我更关心第二个问题它到底靠什么工作真要判断这东西能不能在自己业务里用起来光看功能列表是不够的。你得知道它底层是怎么运作的动态加载机制长什么样有哪些限制条件。把机制想清楚了很多工程问题会自己浮出水面description 怎么写才不乱触发allowed-tools怎么收口才安全技能多了之后怎么避免互相打架这篇文章我按第一性原理把 Claude Agent Skills 的核心机制拆开再给一份可落地的工程清单。主要参考了 Han Lee 那篇Claude Agent Skills: A First Principles Deep Dive——质量非常高深入到了源码层面。结合实际的 Agent 调用日志做验证基本能把 Skill 的里外看透。本篇不重复基础概念直接进机制。如果你还不熟悉 Skill 的基本用法建议先看之前的 Anthropic 官方 33 页指南拆解: 构建Skills的最佳实践太长不看版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 的能力边界最终由两部分决定1. 模型的指令遵循与推理能力——能不能读懂手册、照着步骤做2. 你提供的工具是否足够可用、可控——手册里写了用 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-message command-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. ## Process 1. **Validate the PDF file exists** 2. **Run pdftotext command to extract text** 3. **Read the output file** 4. **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/次。从实际调用日志来看消息序列是这样的1.tool_useAgent 调用 Skill Tool传入 skill 名称2.tool_result返回 “Launching skill: xxx”只做确认3.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 架构与实战拆解。真正的工程化难点技能多了以后怎么管当技能从 5 个增长到 50 个问题会从能不能用变成怎么运营。我认为有四件事要前置。可观测性至少把这些埋点做出来触发了哪个 skill以及触发前的用户意图原文注入了多少 token工具调用次数、失败原因、重试次数每一步的中间产物结构化日志或可回放轨迹Skill 的执行过程涉及多个环节——description 匹配、内容注入、指令解析、工具调用——任何一个环节出问题最终表现都是没跑对或者没触发。但你想定位到具体是哪个环节就得看完整的对话日志。如果系统没有把这些中间状态都记录下来排查问题会非常痛苦。你不把这些变成数据就只能靠感觉调 prompt——而凭感觉调 prompt是最贵的调试方式。歧义与冲突治理技能撞车是常态不是例外。当两个 description 语义相近模型就面临选择困难。解法是把 description 写成任务边界不只说我做什么还要说我不做什么。给技能做分层也很有效L0只做信息读取与整理低风险L1能写文件、改配置中风险L2能跑命令、能发请求高风险默认需要显式确认并发安全问题这个问题原文里专门提到了Skills are not concurrency-safe。当你把多个技能当作可随意叠加的插件来设计很容易出现互相覆盖指令、权限边界混乱、顺序依赖不清晰的问题。技能越重——越是那种改变模型整体行为模式的——越要谨慎组合。版本化与回滚把 Skill 当成配置资产来管理SKILL.md加版本号、变更日志、回滚策略、灰度与 A/B 实验。怎么用 git 管理这些配置文件之前在 团队落地把 Claude Code 配置当代码管理 里聊过同样的思路完全适用于 Skill。这会让你从写 prompt升级成运营能力资产。落地清单12 件事1. 先把技能分层L0 到 L2默认只自动触发低风险技能。2. 每个技能的 description 用一句话写清边界并明确它不做什么。3.allowed-tools最小化能限制到命令模式就不放开整个 Bash。4. 高风险技能默认disable-model-invocation: true只允许手动调用。5. 要求工具输出结构化JSON/YAML/表格并把 schema 写进SKILL.md。6. 明确每一步的失败处理何时重试何时换工具何时停止请求用户补信息。7. 观测做成默认能力记录触发 skill、注入开销、tool_calls、关键上下文。8. 写文件、改配置、发请求、执行命令类动作做二次确认或沙箱化。9. 给常见输入做校验与纠错策略路径不存在、权限不足、参数缺失。10. 技能多了做目录化按业务域/角色/风险等级组织。11. 建最小评测集10 到 30 条真实任务定期回归。12. 把技能当成团队资产有人 review有人维护有人对线上效果负责。收个尾Skill 这套机制从设计上看相当优雅。它用一个元工具实现了按需加载领域知识的完整闭环同时保持了上下文窗口的高效利用。Han Lee 在原文结尾的总结我很认同By treating specialized knowledge as prompts that modify conversation context and permissions that modify execution context rather than code that executes, Claude Code achieves flexibility, safety, and composability that would be difficult with traditional function calling.但优雅归优雅拿到生产环境里用还需要补很多地基。还有一点很实在那些想用小尺寸模型来验证Skill 功能的想法建议直接放弃。光是意图识别就够呛更别说后面那些复杂的多步骤执行了。Skill 对模型的推理能力、指令遵循能力和多步规划能力都有相当高的要求。这不是你换个便宜模型就能省下来的。如果你打算在团队里试我的建议是从一个低风险技能起步先把可观测性 权限最小化 结构化输出三件事打稳再谈规模化。团队怎么落地 Claude Code 的工作流可以看 AI 编程实践从 Claude Code 到团队协作的 6 个落地抓手 和 把 Claude Code 用成工程工具8 条黄金法则与一套可复用工作流。别急着搞一套。先把一个跑通。最后如果说程序员已经是高薪职业那么干AI的程序员就是高薪中的高薪。现在的市场已经用数据给程序员指明了方向学****AI大模型就是冲刺高薪的最优解看着身边越来越多的同行转型大模型、拿到高薪offer很多人心里都动了心但真正的难题来了零基础小白不知道从哪入门有基础的程序员找不到系统学习路径实战项目练手无门面试不知道考什么别慌今天就给大家整理了一份【2026年最新版】AI大模型免费学习资源包覆盖从入门到实战、从理论到面试、从基础到进阶的全流程所有资料均已整理归档无冗余、无套路免费分享给每一位想抓住AI风口的程序员和小白扫码免费领取全部内容1、大模型系统化学习路线2、大模型学习书籍文档3、AI大模型最新行业报告4、大模型项目实战配套源码5、大模型大厂面试真题四阶段精细化学习规划附时间节点可直接照做结合上述资源给大家整理了一份可直接落地的四阶段学习规划总时长约2个月小白可循序渐进程序员可根据自身基础调整节奏高效掌握大模型核心能力快速实现从“入门”到“能落地、能面试”的跨越。第一阶段10天初阶应用该阶段让大家对大模型 AI有一个最前沿的认识对大模型 AI 的理解超过 95% 的人可以在相关讨论时发表高级、不跟风、又接地气的见解别人只会和 AI 聊天而你能调教 AI并能用代码将大模型和业务衔接。大模型 AI 能干什么大模型是怎样获得「智能」的用好 AI 的核心心法大模型应用业务架构大模型应用技术架构代码示例向 GPT-3.5 灌入新知识提示工程的意义和核心思想Prompt 典型构成指令调优方法论思维链和思维树Prompt 攻击和防范…第二阶段30天高阶应用该阶段我们正式进入大模型 AI 进阶实战学习学会构造私有知识库扩展 AI 的能力。快速开发一个完整的基于 agent 对话机器人。掌握功能最强的大模型开发框架抓住最新的技术进展适合 Python 和 JavaScript 程序员。为什么要做 RAG搭建一个简单的 ChatPDF检索的基础概念什么是向量表示Embeddings向量数据库与向量检索基于向量检索的 RAG搭建 RAG 系统的扩展知识混合检索与 RAG-Fusion 简介向量模型本地部署…第三阶段30天模型训练恭喜你如果学到这里你基本可以找到一份大模型 AI相关的工作自己也能训练 GPT 了通过微调训练自己的垂直大模型能独立训练开源多模态大模型掌握更多技术方案。到此为止大概2个月的时间。你已经成为了一名“AI小子”。那么你还想往下探索吗为什么要做 RAG什么是模型什么是模型训练求解器 损失函数简介小实验2手写一个简单的神经网络并训练它什么是训练/预训练/微调/轻量化微调Transformer结构简介轻量化微调实验数据集的构建…第四阶段20天商业闭环对全球大模型从性能、吞吐量、成本等方面有一定的认知可以在云端和本地等多种环境下部署大模型找到适合自己的项目/创业方向做一名被 AI 武装的产品经理。硬件选型带你了解全球大模型使用国产大模型服务搭建 OpenAI 代理热身基于阿里云 PAI 部署 Stable Diffusion在本地计算机运行大模型大模型的私有化部署基于 vLLM 部署大模型案例如何优雅地在阿里云私有部署开源大模型部署一套开源 LLM 项目内容安全互联网信息服务算法备案…扫码免费领取全部内容6、这些资料真的有用吗这份资料由我和鲁为民博士(北京清华大学学士和美国加州理工学院博士)共同整理现任上海殷泊信息科技CEO其创立的MoPaaS云平台获Forrester全球’强劲表现者’认证服务航天科工、国家电网等1000企业以第一作者在IEEE Transactions发表论文50篇获NASA JPL火星探测系统强化学习专利等35项中美专利。本套AI大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。资料内容涵盖了从入门到进阶的各类视频教程和实战项目无论你是小白还是有些技术基础的技术人员这份资料都绝对能帮助你提升薪资待遇转行大模型岗位。这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】https://mp.weixin.qq.com/s/mt8kU-8roiiqwrcWSUjolA
