Claude Skills 架构拆解:渐进披露、运行时与安全沙箱

 

架构师(JiaGouX)
我们都是架构师!
架构未来,你来不来?



1. 范式转移:从提示词工程到上下文工程

在过去二十年的软件架构演进中,我们见证了从单体应用向微服务架构的转变,其核心驱动力是降低耦合度并提高系统的可扩展性。如今,在大语言模型(LLM)的应用开发领域,一场类似的范式转移正在悄然发生。作为一名长期在这个领域深耕的架构师,我认为我们需要重新审视我们构建 AI 应用的方式——从传统的“提示词工程”(Prompt Engineering)转向更为结构化、模块化的“上下文工程”(Context Engineering)。而 Anthropic 推出的 Claude Skills 架构,正是这一转型的里程碑式产物。

1.0 核心命题(可验证)

为了避免“介绍功能但缺少可检验结论”,本文先把 Skills 的架构价值收敛成一句可验证的命题:

Skills 把 LLM 系统从“文本堆叠的单体提示词”,重构为“可版本化、可审计、可组合的运行时模块”;核心收益来自三件事:上下文预算可控、执行路径可控、权限边界可控。

这三个“可控”,将分别对应本文三条主线:

  • • 上下文预算可控:用分层披露(progressive disclosure)把“常驻/激活/执行”的上下文开销分账,避免一次性堆叠。
  • • 执行路径可控:把关键逻辑从自然语言推理迁移到可测试脚本,模型更像编排者而非解释器。
  • • 权限边界可控:用沙箱、网络代理与权限提示,把工具执行面收敛到可审计、可治理的边界内。

1.1 上下文窗口的“公地悲剧”

在 Skills 架构出现之前,构建复杂 AI 代理(Agent)面临着一个被称为“上下文公地悲剧”的核心瓶颈。当我们试图让一个通用模型(如 Claude 3.5 Sonnet)成为特定领域的专家时,我们通常的做法是将所有的业务规则、品牌指南、API 文档以及错误处理流程全部塞入系统提示词(System Prompt)中。

这种做法导致了三个严重的技术债:

  1. 1. 注意力稀释(Attention Dilution): 随着上下文窗口被无关信息填满,模型在处理具体指令时的精确度下降,这种现象在学术界被称为“迷失在中间”(Lost in the Middle)。
  2. 2. 推理成本与延迟: 即使是处理一个简单的请求,如果系统提示词包含了 50 页的文档,每一次 API 调用都需要为这些并未被激活的知识付费,且显著增加了首字延迟(TTFT)1。
  3. 3. 维护的不可持续性: 巨大的提示词文本块难以进行版本控制、难以进行单元测试,且极易因微小的修改导致不可预测的“蝴蝶效应”。

1.2 动态加载的“闪存”隐喻

Claude Skills 的核心设计哲学是将“知识”与“推理”解耦。如果将 LLM 的上下文窗口比作计算机的内存(RAM),那么传统的提示词工程就是试图在开机时将所有数据加载进内存。相比之下,Claude Skills 更像是一个可热插拔的外部存储设备(如 USB 闪存盘)1。

在这个架构下,代理并不需要时刻“记住”所有的知识。它只需要知道它“拥有”哪些能力。当且仅当用户触发了特定任务时,相关的知识模块(Skill)才会被动态加载到内存中。这种设计使得我们可以为代理配备成千上万种技能——从“SQL 性能优化”到“法律合规审查”——而不会在初始阶段消耗任何额外的上下文资源,从而实现了代理能力的无限扩展可能 2。


2. 核心架构:渐进式披露机制(Progressive Disclosure)

Claude Skills 能够实现高效扩展的秘密在于其独特的加载算法,技术文档中将其称为渐进式披露(Progressive Disclosure)。这是一种分层加载策略,旨在最小化令牌(Token)消耗,同时最大化模型在特定任务上的表现 2。

2.1 分层披露策略详解

与一次性加载所有信息不同,Skills 采用**分层披露策略(progressive disclosure)**来管理上下文的生命周期。

Level(官方)/Tier(本文)
内容组件
令牌量级与工程建议
触发机制
架构意义
Level 1 / Tier 1:元数据层 (Metadata)
SKILL.md 中的 YAML Frontmatter(名称与描述)
Level 1 元数据:典型约 100 tokens / Skill 的量级
会话初始化 (Session Start)
建立索引,使模型具备“元认知”能力,即知道自己“能做什么”。
Level 2 / Tier 2:指令层 (Instructions)
SKILL.md 的 Markdown 正文
Level 2 指令正文:典型约 1k 到 5k tokens(取决于指令正文长度与引用策略)
语义匹配或显式调用
激活特定领域的“系统提示词”,将通用模型转化为领域专家。
Level 3 / Tier 3:资源层 (Resources)
脚本 (scripts/) 与参考文档 (resources/)
Level 3 资源与脚本:按需访问;脚本可执行,脚本内容不进入上下文,只有输出进入上下文
任务执行中的具体步骤
实现“零上下文执行”,仅在必要时读取文件或运行代码。

2.2 系统账本模型:把 Token、延迟与确定性统一成三类预算

如果把“上下文窗口”理解为一张系统账本,那么每次请求都在支付三笔预算。后续所有优化策略,都可以被解释为“减少某一类预算,同时不伤害目标”:

  1. 1. 常驻成本(Resident):会话启动时长期占用的内容,例如 Skills 的元数据索引、全局约束等(对应 Level 1)。
  2. 2. 激活成本(Activation):某个 Skill 被加载时注入的指令正文(对应 Level 2)。
  3. 3. 执行成本(Execution):工具返回、文件内容、脚本 stdout/stderr 等运行时产物进入上下文(对应 Level 3)。

在工程上,这张账本同时决定三件事:

  • • Token 成本:账本的直接计费项。
  • • 延迟(Latency):常驻/激活成本会直接影响首字延迟(TTFT),执行成本会影响整体完成时长与交互节奏。
  • • 确定性(Determinism):执行成本如果主要来自“可测试脚本的输出”,系统行为会比“模型现场编写并解释执行”更稳定。

2.2.1 “确定性”的工程定义与度量

“确定性”在 AI 系统里常被说空。这里给出一个更工程化、可验证的定义:在固定环境与输入下,系统输出的差异度可控,且失败模式可分类、可重试、可回归测试。

  • • 确定性提升的来源:把关键逻辑从自然语言推理转移到可测试脚本;把模型角色收敛为“编排与判断”。
  • • 确定性的衡量方式:
    • • 同一输入在固定环境下输出差异度(例如结果 diff 率)。
    • • 回归测试通过率(脚本与工具调用链可被自动化验证)。
    • • 失败模式是否可分类、是否可重试、是否可降级(见第 6 章的契约与失败模式)。

2.3 把“分层披露”提升为运行时状态机

流程图回答“会发生什么”,状态机回答“当前上下文里到底有什么、哪些可回收、污染从哪里来”。下面用四个状态把 Skills 的运行时过程抽象成可推演的状态机,并把 context: fork 表达为状态跃迁:


这张图对应两个关键工程结论:

  • • 上下文污染从哪里来:主要来自 S2 的大量中间输出(工具返回、错误、调试日志)。
  • • 污染如何被隔离:主会话可停留在 S0/S1,把试错放到 fork 的子会话;子会话结束后只回填摘要进入 S3,避免主上下文膨胀。

2.1.1 Tier 1:元认知索引

当一个 Claude 会话启动时,系统会扫描 .claude/skills 目录。此时,它不会读取每个 Skill 的详细指令,而是仅提取 SKILL.md 顶部的 YAML 元数据 5。这些元数据(主要是 name 和 description)被注入到系统提示词的末尾。

这一步至关重要。它相当于为模型构建了一个轻量级的“能力目录”。例如,模型会看到 pdf-extractor: Extracts text from PDFs。这里的 token 消耗更准确的表述是:文档给出的典型量级约为每个 Skill 百 tokens 级别,实际占用取决于元数据长度与实现细节 6。

2.1.2 Tier 2:即时激活(Just-in-Time Activation)

当用户输入“请帮我分析这份财务报表 PDF”时,Claude 的推理引擎会对用户意图进行语义分析,并与已加载的元数据描述进行匹配。一旦确定 pdf-extractor 是相关技能,系统会立即从文件系统中读取该 Skill 的 SKILL.md 完整内容,并将其追加到当前的上下文窗口中 2。

这一过程对用户是透明的,但在架构上,这标志着模型从“通用助手”模式切换到了“PDF 处理专家”模式。此时,模型拥有了处理 PDF 的所有步骤、规则和异常处理逻辑。

2.1.3 Tier 3:零上下文执行(Zero-Context Execution)

这是 Skills 架构中最具革命性的部分。在传统的代码解释器(Code Interpreter)模式中,代码往往是由模型实时编写并执行的。而在 Skills 架构中,我们可以预置经过严格测试的脚本(如 Python 或 Bash 脚本)。

当 Skill 指令要求运行 python scripts/analyze.py 时,模型不需要读取这个 Python 脚本的源代码。它只需在沙箱环境中调用该文件。更贴近官方语义的表述是:脚本可执行且无需把脚本内容加载进上下文,只有脚本输出(stdout/stderr 等)进入上下文并消耗 tokens 5。这种机制使得我们可以将极其复杂的算法(如金融建模、数据清洗)封装在脚本中,而模型仅负责高层的编排与决策,极大地提升了系统的确定性和效率。


3. 技术解构:Skill 的物理形态与规范

作为架构师,我们需要深入理解 Skill 的物理结构。不同于封闭的数据库记录,Claude Skills 采用了基于文件系统的设计,这使得它们天然支持 Git 版本控制、CI/CD 流水线以及现有的 IDE 开发流程 7。

3.1 目录结构标准

一个标准的 Skill 本质上是一个文件夹。文件夹的命名必须严格匹配 Skill 的 ID(通常为小写字母、数字和连字符)。

典型的企业级 Skill 目录结构:

data-analysis-pro/ # 根目录,必须与 Skill ID 一致  
├── SKILL.md # [必须] 核心定义文件  
├── README.md # [可选] 供人类阅读的文档  
├── scripts/ # [推荐] 可执行代码库  
│ ├── clean_data.py # Python 清洗脚本  
│ ├── visualize.R # R 语言可视化脚本  
│ └── query_db.sh # Bash 数据库查询封装  
├── templates/ # [推荐] 输出模版  
│ ├── report_format.md # 报告结构定义  
│ └── email_draft.txt # 邮件草稿模版  
└── resources/ # [可选] 静态知识库  
├── schema.json # 数据库结构定义  
└── glossary.csv # 术语表  

这种结构体现了“关注点分离”(Separation of Concerns)的设计原则:SKILL.md 负责与 LLM 的自然语言交互,scripts/ 负责确定性的逻辑计算,resources/ 负责静态知识的存储 5。

3.2 SKILL.md 规范详解

SKILL.md 是 Skill 的灵魂,它由两部分组成:YAML Frontmatter 和 Markdown 正文。

3.2.1 YAML Frontmatter 配置表

这是 Skill 的 API 签名,决定了 Skill 如何被系统识别和调用 5。

---
name:
 data-analysis-pro  
description:
 Analyzes CSV/Excel datasets using advanced statistical methods. Use when the user asks for "trends", "forecasts", or "data insights".  
allowed-tools:
  
user-invocable:
 true  
context:
 fork  
agent:
 plan  
---
  • • name (Required): 必须与目录名完全一致。仅限小写字母、数字和连字符,最大 64 字符。这是调用的唯一标识符。
  • • description (Required): 最关键的字段(最大 1024 字符)。这不仅仅是文档,更是触发逻辑。Claude 会根据这段文字的语义来决定是否加载此 Skill。最佳实践是使用“当用户请求...时使用此技能”的句式 2。
  • • allowed-tools (Optional):allowed-tools 用于限制 Skill 激活时可调用的工具范围,把执行面收敛到一个更小集合,并在权限询问方面更收敛。若省略该字段,则不对工具范围施加该约束,仍按 Claude Code 的标准权限模型进行权限请求…
— 以上为试看内容(约 40%),开通会员后阅读全文 —