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. 注意力稀释(Attention Dilution): 随着上下文窗口被无关信息填满,模型在处理具体指令时的精确度下降,这种现象在学术界被称为“迷失在中间”(Lost in the Middle)。
2. 推理成本与延迟: 即使是处理一个简单的请求,如果系统提示词包含了 50 页的文档,每一次 API 调用都需要为这些并未被激活的知识付费,且显著增加了首字延迟(TTFT)1。
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 3 / Tier 3: 执行 (Resource Access) Level 2 / Tier 2: 激活 (Instruction Loading) Level 1 / Tier 1: 初始化 (Session Start)
仅消耗 ~100 tokens/skill
Match
追加到 Context Window
Code Execution
Read Reference
Stdout/Stderr
File Content
Level 1 / Tier 1:元数据层 (Metadata)
SKILL.md 中的 YAML Frontmatter(名称与描述)
Level 1 元数据:典型约 100 tokens / Skill 的量级
建立索引,使模型具备“元认知”能力,即知道自己“能做什么”。
Level 2 / Tier 2:指令层 (Instructions)
Level 2 指令正文:典型约 1k 到 5k tokens(取决于指令正文长度与引用策略)
激活特定领域的“系统提示词”,将通用模型转化为领域专家。
Level 3 / Tier 3:资源层 (Resources)
脚本 (scripts/) 与参考文档 (resources/)
Level 3 资源与脚本:按需访问;脚本可执行,脚本内容不进入上下文,只有输出进入上下文
实现“零上下文执行”,仅在必要时读取文件或运行代码。
2.2 系统账本模型:把 Token、延迟与确定性统一成三类预算
如果把“上下文窗口”理解为一张系统账本,那么每次请求都在支付三笔预算。后续所有优化策略,都可以被解释为“减少某一类预算,同时不伤害目标”:
1. 常驻成本(Resident) :会话启动时长期占用的内容,例如 Skills 的元数据索引、全局约束等(对应 Level 1)。
2. 激活成本(Activation) :某个 Skill 被加载时注入的指令正文(对应 Level 2)。
3. 执行成本(Execution) :工具返回、文件内容、脚本 stdout/stderr 等运行时产物进入上下文(对应 Level 3)。
在工程上,这张账本同时决定三件事:
• 延迟(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 的标准权限模型进行权限请求与审批 5。推荐用法: 只读审阅类技能,或安全敏感工作流中只允许 Read 与搜索类工具。
• context: fork (Advanced): 设置为 fork 时,Skill 将在独立的子代理(Sub-agent)上下文中运行,避免主会话上下文被中间步骤污染 10。
• agent (Advanced): 配合 context: fork 使用,指定子代理(subagent)的配置与运行方式;具体字段与可用类型以 Claude Code 的 subagents 文档为准 30。
user-invocable 仅控制是否出现在 slash 命令菜单中,并不等同于“完全隐藏” :仍可能被自动发现或被模型通过 Skill tool 程序化调用。若需要阻止通过 Skill tool 的程序化调用,可使用 disable-model-invocation: true;其对自动发现与斜杠菜单的具体行为以文档定义与实际版本行为为准。
3.2.2 Markdown 指令正文
YAML 之后的部分是具体的执行指南。这里是“提示词工程”发挥作用的地方,但与传统提示词不同,这里的指令应更侧重于流程编排 而非知识灌输 5。
最佳实践指南:
1. 简洁性(Conciseness): 保持在 500 行以内。冗长的文档会增加加载延迟和 Token 成本。
2. 引用优于内联(Reference over Inline): 不要把巨大的数据字典直接写在 SKILL.md 里。应该写“读取 resources/glossary.csv 以查找定义”。这样只有在真正需要查阅时,模型才会去读取该文件(Tier 3 加载)5。
3. 确定性引导: 明确指示模型运行 scripts/ 中的代码,而不是让模型自己编写代码。例如:“运行 python scripts/verify_format.py 来验证数据”,而不是“请写一段 Python 代码来验证数据”。
4. 运行时环境:Claude Code CLI 与系统集成
Claude Skills 并非只能在云端 API 运行,它最强大的载体是 Claude Code ——一个运行在终端(Terminal)中的代理编码工具。Claude Code 充当了 Skills 的操作系统,提供了文件系统访问、代码执行和沙箱隔离环境 12。
4.1 监督者-执行者模式(Supervisor-Executor Pattern)
在实际的高级工程实践中,我们观察到一种被称为“监督者-执行者”的双模架构模式正在兴起 14。
Local Skill (工具层) Claude Code CLI (战术层) Claude Desktop (战略层) 开发者 Local Skill (工具层) Claude Code CLI (战术层) Claude Desktop (战略层) 开发者 需求: "重构登录模块为 OAuth2" 分析架构文档 & 规划 生成 "手术式提示词" (Surgical Prompt) 粘贴提示词 / 执行指令 激活 refactor-skill 读取测试脚本 在沙箱中执行重构代码 运行 scripts/test\_runner.sh 返回执行结果 & 测试报告
• Claude Desktop (监督者/Supervisor): 运行在图形界面中。它负责高层的意图理解、架构规划和文档阅读。它拥有全局视野,但通常没有直接修改代码库的权限。
• Claude Code CLI (执行者/Executor): 运行在开发者的终端中。它加载具体的 Skills,拥有对文件系统的读写权限。这种模式完美地平衡了战略规划(高上下文需求)与战术执行(高工具交互需求)14。
4.2 冲突解决与优先级
当安装了数十个 Skills 时,难免会出现命名冲突或功能重叠。Claude 的解析引擎具备内置的冲突解决逻辑 15:
1. 显式调用优先: 如果用户输入 /data-analysis,系统会强制调用该名称的 Skill,忽略其他语义匹配。
2. 来源层次与排障思路: Claude Code 的 Skill 可能来自个人目录(~/.claude/skills/)、项目目录(.claude/skills/)以及插件内置 Skill 等不同来源 5。当出现同名冲突时,不同版本/实现可能存在覆盖或解析差异;工程上更稳妥的做法是开启 --debug,以日志确认最终被加载的来源,并以当前版本行为为准。
5. 安全治理与沙箱机制(Sandboxing)
随着 Agent 获得执行代码和操作文件系统的能力,安全成为了不可忽视的核心议题。Claude Skills 引入了基于操作系统原语(OS-level primitives)的沙箱机制,以防止“越狱”或恶意操作 17。
5.1 双重隔离架构
Claude Code 的沙箱环境(Bubblewrap on Linux, Seatbelt on macOS)实施了两个维度的隔离:
1. 文件系统隔离(Filesystem Isolation): 文件系统隔离的默认行为:默认写入权限限定在启动目录(工作目录)与其子目录;默认读取权限覆盖整台机器的大多数路径,但会排除部分被 deny 的目录;对工作目录之外的修改操作需要显式许可,且可通过设置细化 allow 与 deny 规则。 18
• 深度洞察: 这使“读取面”与“写入面”在默认语义上解耦:在不牺牲排障可观测性的前提下,把持久化写入的破坏半径控制在工作区。
2. 网络隔离(Network Isolation): Skill 的网络请求不能直接通过主机的网卡发出。所有的网络流量必须经过一个专门的代理服务器。这个代理服务器维护着一个允许名单(Allowlist)。 该出网限制对 Skill 启动的脚本与子进程同样生效,从而形成工程上的闭包边界 18。
• 示例: 一个“GitHub PR 审查”技能只能访问 api.github.com。如果恶意代码试图连接 attacker.com 传回数据,代理层会直接丢弃该请求 17。
5.2 权限模型与“以人为本”的控制
Claude Code 采用了“请求-许可”(Ask-Before-Act)的权限模型。对于任何产生副作用(Side-effect)的操作(如写文件、执行 Shell 命令),系统默认会暂停并询问用户。
• 风险警示: 系统提供了一个 --dangerously-skip-permissions 标志,用于 CI/CD 等无人值守场景。但在本地开发中,强烈建议不要启用 此选项。安全研究表明,恶意的 Skill 可能利用这一点,配合 Git 配置中的漏洞(如 GHSA-j4h9-wv2m-wrf7),在用户无感知的情况下执行任意代码 19。
• 供应链攻击防御: 由于 Skill 本质上是代码,它们可以通过 Git 仓库分发。企业必须像管理开源依赖库(npm/pip)一样管理 Skills。建议企业建立内部的 Skill 注册中心,并对引入的第三方 Skill 代码(特别是 scripts/ 目录下的二进制和脚本)进行严格的安全审计 21。
5.3 典型攻击链与控制点
第 5 章的信息如果只停留在“隔离/权限”的名词解释,很难落到可审计的治理动作。一个更工程化的办法是用最小威胁建模骨架把它们对齐:
• 典型攻击链 :诱导决策 → 尝试读取敏感信息 → 尝试外传 → 尝试持久化写入。
1. 读取控制可通过 Read deny 规则收敛敏感路径面。
2. 写入控制默认限定在工作目录,跨目录修改需要许可。
3. 出网控制通过代理与域名限制,新增域名触发权限请求。
4. 行为控制可通过 hooks 的 PreToolUse 与 PermissionRequest 实施 allow / deny / ask 策略 29。
6. Skills 与 MCP:竞合还是协同?
在 Anthropic 的生态中,Model Context Protocol (MCP) 和 Skills 是两个经常被混淆的概念。澄清两者的关系对于架构设计至关重要 3。
6.1 核心差异对比
Model Context Protocol (MCP)
本质定义
过程性知识 (Procedural Knowledge)
连接与能力 (Connections & Capabilities)
关注点
"怎么做" (How-to)
"用什么" (What-with)
载体
本地文件系统 (Markdown + Scripts)
客户端-服务器架构 (Client-Server Protocol)
可移植性
上下文影响
适用场景
6.2 协同架构:Skill 作为编排者
最强大的架构并非二选一,而是将两者结合。Skills 应该作为 MCP 工具的编排者 24。
从“系统边界”的角度,二者的角色可以更硬核地定义为一条边界契约:
• MCP 是工具面(Tool Plane) :解决连接、鉴权、数据访问与可观测,让“工具调用”成为可实现、可治理的能力。
• Skills 是流程面(Flow Plane) :解决意图映射、步骤编排、异常策略与输出规范,让“工作流”成为可版本化、可审计的模块。
两者之间靠的是接口契约(contract) ,而不是靠模型猜:输入输出结构、错误语义、超时边界、权限语义都应该显式化。
实战案例:企业级故障排查 Agent
• 部署 Prometheus MCP Server -> 提供 query_metrics()。
• 部署 Kubernetes MCP Server -> 提供 get_logs()。
• 注意: MCP Server 不知道什么是“故障”,它只知道如何获取数据。
• 创建一个 incident-response Skill。
• Step 1: 调 Prometheus MCP 查 CPU。
• Step 2: 若 CPU > 80%,调 Kubernetes MCP 抓日志。
• Step 3: 运行本地 scripts/log_parser.py 分析堆栈。
这种架构完美地实现了“能力”与“智慧”的解耦。MCP 负责修路(连接数据),Skills 负责开车(执行任务)。
契约与失败模式: MCP 提供工具能力面,Skill 提供流程编排面。为避免系统在异常情况下发散,建议对 MCP 调用定义返回契约与失败策略,并至少覆盖以下四类常见失败模式:
1. 工具超时 :设置超时与重试上限(建议包含退避),超过上限则快速失败并进入降级/人工介入点。
2. 工具返回不稳定或 schema 漂移 :对关键字段做结构校验(必要时做版本钉住),遇到漂移则降级到“只读展示原始返回 + 提示人工确认”。
3. 权限被拒绝 :定义清晰的降级路径(例如只读模式、最小可用结果),并把“需要人工批准的点”显式提示给用户。
4. 数据不可用或不一致 :优先返回可解释的错误分级(可重试/不可重试),必要时允许返回“陈旧但可用”的缓存结果,并提示一致性风险。
无论哪一类失败,都建议把关键工具调用写入可审计的执行记录(工具名、参数摘要、目标资源、结果/错误、重试次数、是否触发权限请求),便于排障与治理。Skills 的渐进披露机制也适合把契约说明放入独立文件,在需要排障时再加载。
7. 高级代理模式:递归、分叉与自进化
掌握了基础架构后,我们可以利用 Skills 构建更高级的代理行为。
7.1 上下文分叉(Context Forking)
在处理极度复杂的任务(如“重构整个后端 API”)时,主会话的上下文往往会被成百上千次的尝试、错误和调试信息填满。这会导致模型“疲劳”,且容易遗忘最初的目标。
context: fork 是解决这一问题的杀手级特性 10。它的工作流如下:
代码库 子代理 (Forked Context) 主会话 (Main Thread) 代码库 子代理 (Forked Context) 主会话 (Main Thread) 主会话暂停等待 子代理销毁,中间错误日志丢弃 主会话仅接收成功结果,保持上下文纯净 激活 Skill (context: fork) 独立的上下文环境 (Clean Slate) 尝试修改代码 报错 (Error) 修复并重试 (Retry) 测试通过 (Success) 返回最终结果 (Result Only)
• 机制: 当该 Skill 被激活时,Claude 会创建一个临时的、隔离的“平行宇宙”(子代理)。
• 流程: 子代理在这个隔离环境中进行所有的脏活累活(运行测试、修复 Bug、再运行测试)。
• 合并: 只有最终的成功结果(或精炼的失败报告)会被返回给主会话。所有中间过程的 Token 都会被丢弃。
• 应用: 这类似于 Git 的 Feature Branch 工作流。主分支(主会话)永远保持干净,所有的开发噪音都限制在临时分支(子代理)中。
7.2 递归与组合(Composability)
更稳妥的表述是:Claude 可以在同一会话中按需激活多个 Skills,通过编排形成组合工作流。这类“元技能(Meta-Skills)”更像是一种编排策略:是否允许嵌套式调用、以及调用链如何受权限与运行时影响,应以实际运行时与权限设置为准 26。 例如,构建一个 software-architect Skill,它的指令不是直接写代码,而是:
1. 调用 requirement-analysis Skill 分析文档。
2. 调用 database-design Skill 生成 Schema。
3. 调用 api-scaffolding Skill 生成代码框架。
这种组合性使得代理系统的能力呈现指数级增长,而非线性叠加。
7.3 自进化技能(Self-Improving Skills)
利用文件系统的持久化特性,我们可以构建具有“长期记忆”的 Skill 27。
2. 如果用户驳回了审查意见(Feedback)。
3. Skill 自动调用脚本,将用户的反馈追加写入到 resources/review_guidelines.md 文件中。
4. 下一次运行时,Skill 会读取更新后的指南。
• 意义: 这实现了真正的“在岗学习”(On-the-job Learning),代理随着使用次数的增加,会越来越契合特定团队的偏好,而无需重新训练模型。
8. 开发与调试指南
8.1 调试技巧
开发 Skill 时,黑盒测试是痛苦的。Claude Code 提供了 --debug 标志 5。启用后,开发者可以看到:
• Skill Loading Logs: 查看哪些 Skill 的 Frontmatter 解析失败(通常是 YAML 缩进错误)。
• Score & Match: 查看模型对 Skill 描述的语义匹配分数,从而优化 description 字段。
• Execution Trace: 查看脚本执行的完整 stdout/stderr 输出,而不仅仅是模型总结后的结果。
可通过 claude --debug 与 /context 观察哪些元数据进入上下文以及字符预算告警。
8.2 Token 经济学优化
在编写 Skill 时,要时刻牢记 Token 是金钱,更是延迟。
• 精简元数据: description 字段会被注入到所有会话中。保持其简练、精准。避免使用“这是一个非常棒的工具”这类废话,直接写“当用户需要 X 时使用” 11。
• 延迟加载资源: 不要把所有可能的错误代码定义都写在 SKILL.md 里。将它们放入 resources/errors.json,并在指令中写“遇到未知错误代码时,查询 resources/errors.json”。这能将上下文占用减少 90% 以上 5。
8.3 跨平台兼容性
尽管 Claude Code 提供了统一的接口,但底层的 Shell 环境可能不同(Bash on Linux/Mac vs PowerShell on Windows)。
• 最佳实践: 尽量使用 Python 或 Node.js 编写 scripts/ 中的逻辑,因为它们具有良好的跨平台特性。如果必须使用 Shell 脚本,请确保在 Windows 环境下有 WSL 或 Git Bash 支持,或者提供 .bat 和 .sh 双版本脚本。
结语
Claude Skills 不仅仅是一个新功能,它是 AI 代理工程化的重要一步。它将软件工程中成熟的模块化、封装、版本控制和权限管理理念引入了生成式 AI 领域。通过将“知识”文件化、将“能力”脚本化、将“连接”协议化(MCP),我们终于拥有了一套能够构建可维护、可扩展、且安全的企业级智能代理的完整工具链。
对于每一位技术领导者而言,现在的战略重点不应再仅仅是打磨一句完美的提示词,而应该是着手构建属于自己组织的 Skill Library 。这套沉淀了企业独特流程、知识和工具的技能库,将成为 AI 时代最核心的数字资产。
数据引用说明
本文档中引用的技术细节、参数指标及架构图解均基于以下研究资料:
• 2 Claude Skills 动态加载机制与元数据扫描架构。
• 5 Skill 目录结构、YAML Frontmatter 规范及最佳实践。
• 1 上下文窗口经济学与 Token 消耗分析。
• 17 沙箱环境(Sandboxing)、网络隔离与权限模型。
• 3 MCP 与 Skills 的架构对比与协同模式。
• 14 监督者-执行者(Supervisor-Executor)工作流模式。
• 30 子代理(Subagents)与上下文分叉(Context Forking)相关能力与配置。
• 12 Claude Code CLI 运行时环境特性。
引用链接
[1] https://www.reddit.com/r/ClaudeAI/comments/1qbc30u/claude\_code\_skills\_subagents\_feel\_misaligned\_what/: https://www.reddit.com/r/ClaudeAI/comments/1qbc30u/claude_code_skills_subagents_feel_misaligned_what/ [2] https://www.reddit.com/r/ClaudeAI/comments/1phyfk4/how\_do\_you\_actually\_use\_claude\_code\_in\_your/: https://www.reddit.com/r/ClaudeAI/comments/1phyfk4/how_do_you_actually_use_claude_code_in_your/ [3] https://www.reddit.com/r/ClaudeCode/comments/1p377ti/be\_careful\_with\_people\_spreading\_claude\_code/: https://www.reddit.com/r/ClaudeCode/comments/1p377ti/be_careful_with_people_spreading_claude_code/