深度解密Claude Agent Skills第一性原理：动态上下文与元工具架构解析

type

status

date

slug

summary

category

icon

password

网址

长话多说：ClaudeSkills是什么？

最近看到一篇关于Claude Skills的质量非常高的文章，

标题：Claude Agent Skills: A First Principles Deep Dive 链接：https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/

笔者读完，高度概括下，Claude Agent Skills 的第一性原理（First Principles）可以概括为：基于提示词的动态上下文注入与元工具架构（Prompt-based Dynamic Context Injection & Meta-Tool Architecture）。

简单来说，Claude 的 Skills不是一段在该模型之外运行的可执行代码（如 Python 函数），而是一段在需要时被“植入”到模型大脑中的高阶指令（Prompt）。

下面我将从四个核心维度拆解其第一性原理：

本质：是“提示词扩展”，而非“代码执行”

• 传统观念：通常认为 Tool/Function Calling 是“模型调用一个外部函数，函数运行代码并返回结果”。 • Skill 的原理：Skill 是一份 Markdown 文件（SKILL.md）。当 Skill 被调用时，系统并不会去“运行”这个 Skill，而是读取这个文件，将其中的大量指令、工作流和知识“展开”并“注入”到当前的对话历史中。 • 一句话总结：Skill 不直接解决问题，而是通过注入提示词，瞬间把 Claude 变成解决该问题的专家，让 Claude 自己去解决问题。

架构：元工具（Meta-Tool）与纯 LLM 推理

• Meta-Tool 设计：Claude 的 Prompt 里并没有塞入所有 Skill 的具体指令（那样会撑爆 Context Window）。相反，它只有一个名为Skill的元工具（Meta-Tool）。 • 渐进式披露（Progressive Disclosure）：

核心机制：双重上下文注入（Dual Context Injection）

当一个 Skill 被选中时，它会执行两个层面的“修改”操作：

A. 对话上下文注入 (Conversation Context Injection)

这是 Skill 最独特的地方。为了解决“既要让用户知道发生了什么，又不能让几千字的提示词刷屏”的矛盾，系统使用了双通道消息机制：

• 显性消息（Metadata）：给用户看，例如<command-message>The "pdf" skill is loading</command-message>。 • 隐性消息（Meta-Prompt）：带有isMeta: true标记。这是包含SKILL.md完整内容的巨大提示词（可能几千字）。它被发送给 API 进入 Claude 的短期记忆，但在用户界面上是隐藏的。

B. 执行上下文修改 (Execution Context Modification)

Skill 不仅注入文字，还动态改变 Claude 的权限环境：

• 工具权限：临时授予特定的工具权限（如allowed-tools: "Bash(git:*)"），而无需用户反复确认。 • 模型切换：某些 Skill 可以强制切换模型（例如从 Sonnet 切换到 Opus 以进行深度推理）。

运作流程的本质

整个过程可以看作是一个“动态加载特定领域大脑”的过程：

1.用户请求：“帮我分析这个 PDF。”

2.LLM 决策：看到Skill工具里有pdf技能的描述，决定调用command: "pdf"。

3.系统介入：

• 读取pdf/SKILL.md。 • 生成一条给用户的“正在加载...”消息。 • 生成一条给 AI 的“你现在是 PDF 专家，你的工作流是 1,2,3...”的隐藏消息。 • 修改当前 Session 的权限，允许使用 Bash 中的 PDF 工具。

4.LLM 执行：带着新注入的记忆（Prompt）和新获得的权限（Tools），Claude 仿佛变了一个人（Agent），开始执行具体的 Bash 命令来处理 PDF。

Claude Agent Skills 的第一性原理是通过“元工具”动态地将“静态的知识文件（Markdown）”转化为“动态的对话上下文（Prompt）”。

它并没有创造新的“程序执行”方式，而是极其聪明地利用了 LLMIn-Context Learning（上下文学习）的能力，实现了功能的无限扩展和按需加载。

Skills和Prompts有什么区别?

Claude 的Agent Skills与传统的/之前的提示语（Prompts，通常指 System Prompts 或初始 User Prompts）有着根本性的区别。

虽然 Skills 的本质依然是“提示词”（它们不是可执行代码，而是 Markdown 文件中的指令），但它们在架构、加载方式和作用范围上实现了质的飞跃。

可以用一个形象的比喻来概括：

• 之前的提示语（Previous Prompts）：就像是一个全科医生。他在上岗前（对话开始时）背熟了一本厚厚的医学通识手册，在整个诊疗过程中都依赖这本手册的知识。如果手册太厚，他会记不住；如果手册没写的病，他看不了。 • Claude Agent Skills：就像是一个懂得随时呼叫专家的全科医生。他平时只带一本薄薄的通讯录（Skill 列表）。当遇到特定难题（比如需要做心脏手术）时，他会立刻呼叫一位心脏外科专家（加载 Skill），这位专家带着全套专业设备和详细手术指南（完整的 Skill 提示词和工具权限）介入，手术完成后专家离开，医生恢复常态。

以下是具体的深度对比：

加载机制：静态持久 vs. 动态按需 (The Core Difference)

这是最核心的区别。

• 之前的提示语 (Static & Persistent)： • 机制：在对话开始时一次性全部输入给模型（通常在system消息中）。 • 特点：全局生效，贯穿整个对话始终。 • 缺点：如果你要让 AI 具备十种复杂的专业能力，你需要把这十种能力的详细指南都塞进初始提示语中。这会导致上下文窗口（Context Window）迅速膨胀，不仅昂贵，而且过长的提示语会让模型“抓不住重点”，导致指令遵循能力下降。 • Agent Skills (Dynamic & On-Demand)： • 机制：采用了“渐进式披露 (Progressive Disclosure)”的设计。 • 特点：在初始状态下，Claude 的上下文中并不包含Skill 的详细指令。它只看到了一个包含所有可用 Skill 名称和简短描述的列表（存在于一个名为Skill的元工具描述中）。 • 触发：只有当 Claude 自己判断需要使用某个技能来解决当前问题时（例如用户要求“分析这个 PDF”），系统才会动态地将该技能对应的庞大、详细的提示词文件（SKILL.md）注入到当前的对话上下文中。 • 优势：极大节省了上下文空间，让模型在平时保持轻量级，只在需要时“变身”为专家。

架构位置：系统层 vs. 元工具层

• 之前的提示语： • 通常直接位于 API 请求的system字段，或者对话历史最开始的user消息中。它们是对话的基础设定。 • Agent Skills： • 不在 System Prompt 中。 • 它们“寄生”在一个特殊的元工具（Meta-Tool）——即Skilltool——的描述字段里。 • Skill 的本质是一个提示词模板的容器和调度器。

作用范围：仅对话上下文 vs. 双重上下文修改

之前的提示语通常只能改变模型的“对话上下文”，即告诉它“你是什么角色，你要怎么说话”。但 Skills 能做更多：

• 之前的提示语： • 作用：设定人设、规则、输出格式。它告诉模型“你应该怎么做”。 • Agent Skills： • 作用：不仅注入了详细的操作指南（改变对话上下文），它还具备修改执行上下文（Execution Context）的能力。 • 关键区别：Skill 可以动态地改变 Claude 的权限。例如，一个普通的对话可能不允许 Claude 随便运行 Bash 命令，但当pdfSkill 被加载时，该 Skill 可以临时授予 Claude 使用Bash(pdftotext:*)的权限。甚至，Skill 还可以要求切换到更强大的模型（如从 Sonnet 切到 Opus）来执行当前任务。

可见性与交互模式

• 之前的提示语： • 通常对用户是隐藏的（System Prompt），或者是用户自己输入的。交互模式简单直接。 • Agent Skills： • 对用户可见：它会发送一条简短的元数据消息（如“正在加载 PDF 技能...”），让用户知道发生了什么。 • 对用户隐藏（对 AI 可见）：它会发送一条带有isMeta: true标记的、包含数千字详细指令的消息给 API。这条消息是真正指导 Claude 工作的核心，但用户在界面上看不到。 • 双通道通信：为了解决“既要向用户展示进度，又要向 AI 注入大量指令而不刷屏”的矛盾，Skill 采用了巧妙的设计。

下面是两者的总结对比：

简单来说，Skills 是将领域专家的知识模块化，并将其变成了一种可以动态“插拔”的提示词包，同时赋予了这个包修改系统运行环境的能力。

接下来是正文开始：

Claude 的智能体Skills系统是一套基于提示词的复杂元工具架构，它通过注入专门的指令来扩展大型语言模型 (LLM) 的能力。与传统的函数调用或代码执行不同，Skills通过提示词扩展和上下文修改来改变Claude 处理后续请求的方式，而无需编写可执行代码。

本文将从第一性原理深入剖析 Claude 的智能体Skills系统，并详细阐述其架构：一个名为“Skills”的工具充当着元工具，负责将领域特定的提示词注入到对话上下文中。我们将以skill-creator（Skills创建器）和internal-comms（内部沟通）Skills为例，详细解析其完整生命周期，包括文件解析、API 请求结构以及 Claude 的决策过程。

Claude 智能体Skills概述

Claude 利用Skills来提升特定任务的执行效果。Skills被定义为包含指令、脚本和资源的文件夹，Claude可以在需要时加载它们。Claude 采用声明式、基于提示词的系统来实现Skills的发现和调用。AI 模型（Claude）根据系统提示中提供的文本描述来决定是否调用Skills。在代码层面，不存在算法驱动的Skills选择或 AI 驱动的意图检测。所有的决策都完全基于Skills描述，在 Claude 的推理过程中完成。

Skills并非可执行代码。它们不运行 Python 或JavaScript，背后也没有 HTTP 服务器或函数调用。它们也没有硬编码到 Claude 的系统提示中。Skills存在于 API 请求结构中独立的部分。

那么，Skills到底是什么？Skills是专门的提示词模板，用于将领域特定指令注入到对话上下文中。当一个Skills被调用时，它会修改对话上下文（通过注入指令提示词）和执行上下文（通过改变工具权限并可能切换模型）。Skills不是直接执行操作，而是扩展成详细的提示词，这些提示词会为 Claude 解决特定类型的问题做好准备。每个Skills都作为对 Claude 可见工具架构的动态添加项而出现。

当用户发送请求时，Claude 会收到三类信息：用户消息、可用的工具（例如 Read、Write、Bash 等）以及Skills工具。Skills工具的描述包含一个格式化的列表，其中列出了所有可用的Skills及其名称、描述和其他字段的组合。Claude 读取这个列表，并利用其固有的语言理解能力，将用户的意图与Skills描述进行匹配。例如，如果您说“帮我为日志创建一个Skills”，Claude 会看到internal-commsSkills的描述（“当用户想使用其公司喜欢的格式编写内部通信时”），识别出匹配项，然后使用command: "internal-comms"调用Skills工具。

术语说明：

• Skills工具(首字母大写) = 管理所有Skills的元工具。它出现在 Claude 的tools数组中，与 Read、Write、Bash 等工具并列。 • Skills(首字母小写) = 诸如pdf、skill-creator、internal-comms等的单个Skills。这些是Skills工具加载的专用指令模板。

以下是 Claude 如何使用Skills的更直观表示。

Claude Skill Flowchart

Skills选择机制在代码层面没有算法路由或意图分类。Claude 代码不使用嵌入 (embeddings)、分类器(classifiers) 或模式匹配 (pattern matching) 来决定调用哪个Skills。相反，系统将所有可用Skills格式化为文本描述，并将其嵌入到Skills工具的提示词中，让 Claude 的语言模型做出决策。这是纯粹的 LLM 推理。没有正则表达式 (regex)，没有关键词匹配，也没有基于机器学习的意图检测。决策发生在 Claude 通过 Transformer 的正向通道内部，而不是在应用程序代码中。

当 Claude 调用一个Skills时，系统遵循一个简单的工作流程：加载一个 Markdown 文件 (SKILL.md)，将其扩展成详细指令，将这些指令作为新的用户消息注入到对话上下文中，修改执行上下文（允许使用的工具、模型选择），然后在这个富化的环境中继续对话。这与传统工具根本不同，传统工具会执行并返回结果。Skills是为 Claude 解决问题做准备，而不是直接解决问题。

下表有助于更好地辨析工具 (Tools) 和Skills (Skills) 及其能力之间的区别：

构建智能体Skills

现在我们来探讨如何构建Skills，我们将以 Anthropic Skills库中的skill-creatorSkills 作为案例进行分析。提醒一下，智能体Skills是由指令、脚本和资源组成的结构化文件夹，智能体可以动态发现和加载它们，以更好地完成特定任务。Skills通过将您的专业知识打包成可组合的资源提供给 Claude，从而扩展了 Claude 的能力，将通用智能体转变为符合您需求的专业智能体。

关键洞察：Skills = 提示词模板 + 对话上下文注入 + 执行上下文修改 + 可选数据文件和 Python脚本

每个Skills都定义在一个名为SKILL.md(不区分大小写) 的 Markdown 文件中，并可选择与捆绑文件一起存储在/scripts、/references和/assets目录下。这些捆绑文件可以是 Python 脚本、Shell 脚本、字体定义、模板等。以skill-creator为例，它包含SKILL.md、用于许可证的LICENSE.txt，以及/scripts文件夹下的几个 Python 脚本。skill-creator没有/references或/assets目录。

skill-creator package

Skills可以从多个来源发现和加载。Claude 代码会扫描用户设置 (~/.config/claude/skills/)、项目设置 (.claude/skills/)、插件提供的Skills以及内置Skills，来构建可用Skills列表。对于 Claude 桌面版，我们可以按如下方式上传自定义Skills。

Claude Desktop Skill

注意：构建Skills最重要的概念是渐进式披露(Progressive Disclosure)—— 只显示足够的信息来帮助智能体决定下一步做什么，然后在需要时才揭示更多细节。对于智能体Skills而言，它会：

编写 SKILL.md 文件

SKILL.md是Skills提示词的核心。它是一个 Markdown 文件，遵循“前言 (frontmatter)”和“内容 (content)”两部分结构。前言配置Skills如何运行（权限、模型、元数据），而 Markdown 内容则告诉 Claude 做什么。Frontmatter 是用 YAML 编写的 Markdown 文件头部。

┌─────────────────────────────────────┐

│ 1. YAML Frontmatter (元数据) │ ← 配置

│ ---│

│ name: Skills名称 │

│ description: 简要概述 │

│ allowed-tools: "Bash, Read" │

│ version: 1.0.0 ││ --- │

├─────────────────────────────────────┤

│ 2. Markdown 内容 (指令) │ ← Claude 的提示词

│ │

│ 目的解释 │

│ 详细指令 │

│示例和指导 │

│ 分步步骤 │

└─────────────────────────────────────┘

Frontmatter (前言)

前言部分包含控制 Claude 如何发现和使用Skills的元数据。例如，以下是skill-creator的前言：

---

name: skill-creator

description: 用于创建高效Skills的指南。当用户想要创建新Skills（或更新现有Skills）以通过专业知识、工作流或工具集成来扩展 Claude 的能力时，应使用此Skills。

license: 完整条款请参见 LICENSE.txt

---

让我们逐一探讨前言的各个字段。

Claude Skills Frontmatter

name(必填)

不言自明，是Skills的名称。Skills的name在Skills工具中用作command。

Skills的name在Skills工具中用作command。

description(必填)

description字段提供了Skills功能的简要概述。这是 Claude 判断何时调用Skills的主要依据。在上面的示例中，描述明确指出“当用户想要创建一个新Skills时，应该使用此Skills”——这种清晰、面向行动的语言有助于 Claude 将用户意图与Skills能力进行匹配。

系统会自动向描述附加来源信息（例如"(plugin:skills)"），这有助于在加载多个Skills时区分不同来源的Skills。

whentouse(未记录——可能已废弃或为未来功能)

⚠️ 重要提示：whentouse字段在代码库中大量出现，但未在任何官方 Anthropic 文档中提及。此字段可能是：

• 正在逐步淘汰的废弃功能 • 尚未正式支持的内...