收藏 | 新手程序员必看：揭秘大模型核心机制，轻松掌握Claude Skills开发

本文深入剖析了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 的能力边界，最终由两部分决定：

1. 1. 模型的指令遵循与推理能力——能不能读懂手册、照着步骤做
2. 2. 你提供的工具是否足够可用、可控——手册里写了"用 pdftotext 提取"，但如果这个工具没有暴露给模型，或者返回值不结构化，手册写得再好也执行不了

Tools 和 Skills，到底差在哪

这个问题值得用一张表说清楚。

一句话总结：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\n<available_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-message>The "pdf" skill is loading</command-message><command-name>pdf</command-name>

50 到 200 个字符，告诉用户"系统正在加载哪个技能"。

第二条：给模型看的（isMeta: true，UI 隐藏，但随请求发给 API）

You 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/次）。

从实际调用日志来看，消息序列是这样的：

1. 1. tool_use：Agent 调用 Skill Tool，传入 skill 名称
2. 2. tool_result：返回 “Launching skill: xxx”，只做确认
3. 3. user message：SKILL.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 件事

1. 1. 先把技能分层（L0 到 L2），默认只自动触发低风险技能。
2. 2. 每个技能的 description 用一句话写清"边界"，并明确"它不做什么"。
3. 3. allowed-tools最小化，能限制到命令模式就不放开整个 Bash。
4. 4. 高风险技能默认disable-model-invocation: true，只允许手动调用。
5. 5. 要求工具输出结构化（JSON/YAML/表格），并把 schema 写进SKILL.md。
6. 6. 明确每一步的失败处理：何时重试，何时换工具，何时停止请求用户补信息。
7. 7. 观测做成默认能力：记录触发 skill、注入开销、tool_calls、关键上下文。
8. 8. "写文件、改配置、发请求、执行命令"类动作做二次确认或沙箱化。
9. 9. 给常见输入做校验与纠错策略（路径不存在、权限不足、参数缺失）。
10. 10. 技能多了做"目录化"：按业务域/角色/风险等级组织。
11. 11. 建最小评测集：10 到 30 条真实任务，定期回归。
12. 12. 把技能当成团队资产：有人 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大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。

资料内容涵盖了从入门到进阶的各类视频教程和实战项目，无论你是小白还是有些技术基础的技术人员，这份资料都绝对能帮助你提升薪资待遇，转行大模型岗位。

以上全套大模型资料如何领取？