Claude Code Skills 源码深度解析：从元工具架构到 Agent 进化内核

意外：AI Agent的"圣杯"与 51.2 万行代码的秘密

2026 年 3 月 31 日，AI 开发圈发生了一件足以载入史册的"意外"：Anthropic 在发布 @anthropic-ai/claude-code 版本 2.1.88 时，因 npm 配置文件漏写了 .map 排除项，导致整个系统的 TypeScript 源代码------约 1,900 个文件，总计 51.2 万行代码------被完整泄露。

这次泄露不仅让外界看到了一个年 ARR 达到 25 亿美元的顶级 Agent 系统的"骨架"，更揭示了 AI 行业正在发生的一个本质变化：从"聊天机器人（Chatbot）"向"自主代理（Agentic System）"的彻底转移 。

在所有模块中，最让工程师们激动的莫过于其被称为"Skills"的技能系统。不同于传统的工具调用（Function Calling），Claude Code 的 Skills 是通过一种名为"渐进式揭示（Progressive Disclosure）"的提示词扩展架构实现的。今天，我们就穿过那些 minified 混淆代码的迷雾，通过泄露的源码地图，深度拆解这套支撑起"AI 程序员"自主能力的内核。

一、系统架构：元工具（Meta-Tool）的权力中心

在传统 AI 应用中，如果你想让 AI 具备"查天气"的功能，你会直接注册一个 get_weather 工具。但在 Claude Code 的 51.2 万行源码中，它的 tools/ 目录却展现了一个完全不同的世界。

1.1 Skill (大写 S) 与 skills (小写 s)

根据 SkillTool.ts 的逻辑，Anthropic 将技能系统抽象为了两层：

Skill 元工具 (The Meta-Tool) ：这是常驻在 Claude 核心工具列表（Tools Array）中的顶级组件。它唯一的职责是：根据用户的自然语言意图，从本地或插件库中检索并"挂载"具体的技能指令。
individual skills (具体技能) ：这些是以文件夹形式存在的"技能包"（如 .claude/skills/pdf/），内部包含核心指令文件 SKILL.md、辅助脚本 scripts/ 以及参考文档 references/ 。

1.2 为什么不直接把所有技能塞给模型？

这是一个工程权衡问题。Claude Code 需要处理的任务极其复杂，如果一次性将所有技能（如 /debug, /simplify, /explain-code 等）的全文提示词都塞进上下文，会导致：

上下文熵增：模型会因为过长的系统指令而忽视用户的核心诉求。
Token 浪费：即使不使用某些技能，用户也要为这些冗余的提示词支付昂贵的费用。

因此，SkillTool.ts 采用了声明式、基于 LLM 推理的动态加载机制。系统在启动时只加载技能的"名片"（Name & Description），这就是所谓的"第一级揭示" 。

二、Token 经济学：三层渐进式揭示（Progressive Disclosure）

这是 Claude Code 最精妙的工程设计之一。源码展示了其如何通过三级缓存与加载策略，将 Token 开销控制在极低水平。

加载阶段	触发条件	注入内容	Token 成本 (Approx)
Stage 1: 元数据	会话启动 (init)	YAML Frontmatter 中的 Name & Description	每个技能约 100 Tokens
Stage 2: 核心指令	模型识别到匹配意图	`SKILL.md` 的正文 Markdown	限制在 5,000 Tokens 以内
Stage 3: 外部资源	技能执行过程中	Linked Files, Reference Docs, Scripts Output	按需读取，由 Bash 工具调用驱动

源码逻辑推演：

当用户输入"帮我重构这段认证逻辑"时，模型在 system prompt 中看到的是一个 XML 块：

XML

xml 复制代码

<available_skills>
  <refactor>重构代码，优化结构，建议在涉及架构调整时使用。</refactor>
  <security-audit>审计安全漏洞，建议在处理敏感数据时使用。</security-audit>
</available_skills>

模型通过 纯 LLM 推理 发起工具调用：Skill({command: "refactor"}) 。此时，SkillTool.ts 才会读取本地文件系统的 SKILL.md 并将其作为一条标记为 isMeta: true 的用户消息注入上下文。

三、灵魂文件：SKILL.md 的解构与"Shell 预处理"

SKILL.md 不是普通的文档，它更像是一个具备"执行力"的配置文件。

3.1 YAML Frontmatter：执行策略的控制台

泄露的源码显示，frontmatter 部分定义了技能的"运行权限" ：

allowed-tools ：赋予技能在该生命周期内自动获得某些工具（如 Bash）的权限。这让 Claude Code 在执行内置技能时能将权限确认弹窗减少 84% 。
model ：允许技能临时升级模型。例如，普通编辑使用 Sonnet 3.7，但 /security-review 技能可以强制切换到 Opus 4.6 以获得更强的逻辑推理能力。

3.2 炸裂的功能：!command Shell 预处理语法

这是 Claude Code 独有的扩展。在 SKILL.md 中，你可以编写如下内容：

当前的工程依赖树：!npm list --depth=0

源码执行逻辑： 当该技能被触发、SKILL.md 被加载的一瞬间，系统会立即执行反引号中的 shell 命令。输出结果会替换占位符，然后再发送给模型。这意味着模型拿到的不是静态的模板，而是经过"实时采样"后的热数据。

四、核心源码逻辑：isMeta、QueryEngine 与 Agentic Loop

如果说 SkillTool.ts 是手脚，那么 QueryEngine.ts 就是大脑。在泄露的约 4.6 万行 QueryEngine.ts 代码中，我们发现了几处关键设计：

4.1 隐形的消息：isMeta: true

为了保证终端 UI 的简洁，Claude Code 大量使用了 isMeta: true 标志位。

作用：当技能指令被注入上下文时，如果 isMeta 为 true，用户在终端是看不见这些成千上万字的 Prompt 的，但模型却能清楚地读到。
工程意义 ：解决了"UI 污染"问题。用户只看到 /debug running...，而背后的数千字调试指南正在引导模型精准排障。

4.2 记忆架构：MEMORY.md 的自修复逻辑

源码显示 Claude 不仅仅依赖于窗口记忆。它拥有一个三层记忆体系：

活跃上下文：即当前的聊天消息。
MEMORY.md 索引：位于项目根目录，是一个极其精简的"指针文件"（每行约 150 字符），记录了核心决策和文件路径。
主题文件（Topic Files） ：存放在 .claude/memory/*.md，按领域存储深度知识。

写纪律（Strict Write Discipline） ：源码强制要求模型只有在真实文件写入成功后，才能更新索引。这种设计防止了 AI 因为过度自信（幻觉）而污染记忆索引。

五、 KAIROS 与 autoDream：Agent 的"REM 睡眠"

泄露代码中出现频率超过 150 次的特性标志是 KAIROS 。这代表了 Anthropic 的愿景：一个无需指令、始终在线（Always-on）的后台进程。

5.1 autoDream 系统

在 services/autoDream/ 目录下，我们发现了一个名为"梦境系统"的服务。它运行在用户闲置时，分四个严格阶段运行：

Orient (定位) ：读取现有的内存快照，确立认知边界。
Gather Signal (采集信号) ：扫描最近几小时的 session 日志、Git 提交和终端输出。
Consolidate (整合) ：这是最神奇的一步，模型会分析矛盾点（例如：早上说用 Redis，下午改为用 Memcached），并在后台自动合并这些事实。
Prune & Index (剪枝) ：为了防止 MEMORY.md 索引过大，系统会强行将其压缩至 200 行以内。

这证明了：Claude Code 不只是在"回复请求"，它在"维护理解" 。

六、安全与防御：Chicago 模块与 prctl 隔离

作为一个可以在你本地运行 rm -rf 的工具，Claude Code 的安全架构已经卷到了极致。

6.1 "Chicago" (Computer Use)

代号为 Chicago 的模块集成了 @ant/computer-use-mcp 。它让 AI 具备了截图、模拟键盘、点击坐标的能力。但源码中对 Chicago 的访问有着极其复杂的权限链路：

必须开启 --allow-computer-use 。
对 Anthropic 内部员工（ant 标签用户）提供免授权旁路（Bypass）。

6.2 内存嗅探防御

在 upstreamproxy/ 目录中，源码显式调用了 prctl(PR_SET_DUMPABLE, 0) 。

原理：这是 Linux 内核级别的安全加固，旨在防止同 UID 下的进程通过 ptrace 读取 Claude Code 的内存。
目的：保护存储在内存中的 API Key 和 Session Token。这通常是银行级应用才会做的，足以见得 Anthropic 对"本地提权攻击"的警惕。

七、源码彩蛋：那只被十六进制编码的"鸭子"

在解析 buddy/（宠物系统）的代码时，我们发现了一个有趣的工程折衷：所有的宠物物种名称都被写成了十六进制，例如"duck"被写为 String.fromCharCode(0x64, 0x75, 0x63, 0x6b) 。

原因揭秘： 因为 Anthropic 的 CI 自动化扫描管线严禁代码库中出现其内部模型的"绝密代号"。由于"Duck"恰好是某个尚未发布的底座模型的代号，直接写这个词会导致编译不通过。工程师们没有去修改 CI 正则规则，而是选择了十六进制转义这种"充满活力的程序员补丁" 。

八、总结：这对我们开发者意味着什么？

通过对 Claude Code 51.2 万行源码的深度解析，我们可以得到几个关于 Agent 开发的终极结论：

从代码逻辑到 Prompt 逻辑 ：未来的软件，其核心逻辑将不再由硬编码的 if-else 构成，而是由结构化的、可动态发现的 SKILL.md 指令构成。
内存重于窗口 ：学会管理 MEMORY.md 和 CLAUDE.md，比学习复杂的提示词工程更有价值。
并行是唯一的出路 ：源码中随处可见的 Promise.all 表明，AI 已经开始学会同时读取 10 个文件并汇总信息，这标志着串行思考时代的结束。
Agent 是一场持久战 ：autoDream 的存在告诉我们，一个伟大的 AI 代理不应该只在交互时存在，它应该在后台不断地自我整理和进化。

Claude Code 的源码泄露虽然是一次公关危机，但对于整个开源界来说，它更像是一份"Agentic 开发的最佳实践白皮书"。它告诉我们：真正改变世界的不是 LLM 本身，而是围绕 LLM 构建的那套复杂的、具备反思与执行能力的编排系统。

附录：Claude Code 核心源码目录清单

src/main.tsx：4683 行的系统入口，处理 OAuth 与初始化。
tools/SkillTool.ts：元工具实现。
services/autoDream/：内存整合引擎。
upstreamproxy/：核心安全防御层。
utils/modelCost.ts：精准到每个 Token 的计费逻辑。