1.2. Claude Skills 的架构设计哲学是一切的基础

个人经历引入：从“指令集”到“能力体”

2025 年夏天，我接手了一个已经运行半年的 Claude 项目。它不是代码仓库里的某个模块，而是散落在 Notion、Slack 频道、甚至某位离职同事的聊天记录里的“提示词遗产”。整理这些碎片花了我整整两周，其中最长的一段系统提示超过 4000 个 token，没人敢删，因为没人能解释清楚里面每一句话都承担着什么作用——这就是典型的“祖传代码”困境。

2026 年初，我在一个全新的项目里尝试了 Claude Skills。我用 skill init 生成了第一个骨架，把那些提示词按模块拆成了独立的 Skill 包。两周后，一个新加入的同事花了一个下午就读懂了整个体系，因为他不需要在脑海中对几百个变量做模拟运算——每个 Skill 都自带边界、测试用例和版本记录。

这不是效率工具的升级，这是认知模型的重构。Claude Skills 的架构设计哲学之所以是“一切的基础”，是因为它定义的不是“怎么用 AI”，而是“AI 的可组合单元应该长什么样”。理解这个哲学，你就能设计出真正可维护的技能体系；不理解它，你的 Skills 不过是用 YAML 重新包装了一遍 Prompt。

对比表格：传统 Prompt vs. Claude Skills

这张表的核心信息不是“Skills 更强大”，而是 Skills 重新定义了“能力”的最小管理单元。在传统模式下，Prompt 是一段意图描述，执行时依赖模型的上下文记忆与推理能力；在 Skills 架构下，一个 Skill 是带着执行体（脚本）、边界（元数据）和证明（测试）的完整能力包。这意味着你可以像管理微服务一样管理 AI 的能力——独立部署、独立测试、独立废弃——而不必担心牵一发而动全身。

核心洞察：用建筑设计理解 Skills 的层级哲学

如果你觉得“架构设计哲学”这个词太抽象，我们可以用建筑领域来类比。一个建筑师面对的需求是“造一栋能容纳 500 人的办公楼”。如果他用传统 Prompt 工程的思维，他会给施工队写一份长达 50 页的建造说明书；如果他改用 Skills 架构的思维，他会把建筑拆成可组合的功能单元——外立面、暖通系统、消防通道——每个单元有独立的施工图纸、材料清单和验收标准。

这就是 Skills 设计哲学的核心：从被动描述转变为主动封装，再进化为独立交付的能力单元。

第一层：被动描述（传统 Prompt）

你告诉模型：“当你遇到 X 情况时，应该优先考虑 Y 原则，参考 Z 文档”。这相当于在建造说明书里写了一句“外墙应采用隔音材料”。至于具体用什么材料、厚度多少、如何验证隔音效果——全靠施工队（即模型）临场判断。这种模式的致命弱点在于知识的隐性与上下文依赖：你需要整个施工队都完整阅读说明书才能协作，而且一旦遇到说明书未覆盖的边缘情况，判断标准就会因人而异。

第二层：主动封装（Skill 的声明式配置）

Skill 的 SKILL.md 文件用 YAML 前置信息定义了它的名称、描述、触发条件、依赖的 MCP 工具、执行权限。这就相当于给外立面这个功能单元配备了独立的材料清单、施工规范和检测方法。在施工时，施工队不需要阅读整栋楼的所有文档，他们只需要知道“外立面”这个模块能做什么、需要什么输入、产出什么结果。渐进式披露机制保证了系统只在必要时才加载完整指令——上下文里只保留模块的“接口描述”，而非实现细节。

# SKILL.md 前置信息示例
name: pdf-processing
description: Extract, merge, and redact PDF documents
triggers:
  - "extract text from pdf"
  - "merge pdf files"
  - "redact sensitive information"
tools:
  - mcp/pdf-toolkit
permissions:
  - file_read
  - file_write

第三层：独立交付（可组合的能力包）

当每个 Skill 都带着自己的脚本（可执行的操作体）、资源文件（模板、词典、配置文件）和测试用例时，它就从一个“功能描述”变成了一个“可交付的组件”。你可以把这个 Skill 移交给另一个团队，配上一句“它能处理所有 PDF 相关的操作”——而接手方不需要理解 pdfminer 的版本兼容性或正则表达式的匹配逻辑。这正是容器化思想在 AI 领域的映射：每个 Skill 是一个“能力容器”，对外暴露明确的接口，对内封装复杂的实现。

经验框

在实际项目中，我犯过一个典型的错误：把多个不相关的功能塞进同一个 Skill 里，比如在一个 document-tools 包里同时处理 PDF、Markdown 和表格转换。当 PDF 解析逻辑需要升级时，Markdown 相关的部分被误改，整个 Skill 的测试全部红掉。教训很直观：一个 Skill 应该只做一类事，且把它做到可以独立测试、独立废弃的程度。如果你发现自己需要用“和”来命名一个 Skill，那它可能已经越界了。

子节一：能力包的三层结构——描述、脚本、资源

Claude Skills 的物理结构由三个层级组成，每一层承载着明确的职责。理解这三层之间的边界，是设计可维护 Skill 的第一步。

第一层：SKILL.md——声明与描述

SKILL.md 是一个 Skill 的入口文件，它承担三个角色：

1. 元数据载体：通过 YAML 前置信息声明 Skill 的名称、描述、触发词、权限需求和依赖的 MCP 工具。这是 Skill 的“接口面”——Agent 在决定加载哪个 Skill 时，只读取这部分内容。

2. 行为说明书：主体内容用自然语言描述 Skill 的执行逻辑、限制条件和最佳实践。传统 Prompt 的所有“智慧”都应该保留在这里，但要经过清晰的结构化组织：先讲目标，再讲步骤，最后列出边界情况和错误处理策略。

3. 测试锚点：可以在 SKILL.md 中指定测试文件路径或内嵌测试用例描述，为自动化验证提供入口。

第二层：Scripts——可执行的执行体

scripts/ 目录存放的是真正执行的代码，而不是“告诉 AI 如何一步步操作”的指令。这其中包含关键的哲学转变：从依赖推理生成操作，到直接执行确定性操作。

举个例子，传统 Prompt 在处理“从 PDF 中提取文本”时，它需要指导 Claude 调用某个 API，然后解释返回的 JSON 结构，再做格式化处理——每一步都消耗 Token，并可能在中途产生误解。而在 Skills 架构下，scripts/extract_text.py 是一个确定性脚本，Claude 只需要判断“现在需要提取文本”，调用这个脚本，拿到结果后继续推理。确定性操作不应该浪费推理资源，这是 Skills 设计的成本优化原则。

核心建议框

脚本的设计原则：每个脚本应该只完成一个原子操作，且输入输出应该是纯函数式的——相同的参数总是产生相同的结果（或在文件系统中产生相同副作用后返回明确的状态码）。避免把多个业务逻辑串在同一脚本里，这会让你在复用和测试时付出高额重构成本。

第三层：Resources——参考资料与静态资产

resources/ 目录存放的是不参与执行但辅助决策的静态内容：模板文件、配置规范、设计规范、词典、参考文档片段。它的核心价值在于将领域知识固化到 Skill 内部，减少模型对外部知识的实时依赖。

例如，一个负责“生成会议纪要”的 Skill，可以在 resources/ 下存放企业的摘要模板、常用缩写词典、部门名称映射表。当 Skill 被激活时，这些资源作为上下文注入，而无需每次 Prompt 中都重复这些信息。这种设计让 Claude 从一个“通用推理引擎”变成一个“带着定制知识包的领域助手”。

三层结构的边界感决策表：

子节二：运行时生命周期——加载、解析、执行

理解 Skill 从“被声明”到“被 Agent 调用”的完整链路，是排查问题和优化性能的基础。以下是 Claude Skills 的运行时生命周期，分为四个阶段。

阶段一：发现与注册

当开发者通过 skill add 命令安装 Skill 或将其放入项目目录时，Claude 的 Agent 框架会扫描 .skill/ 目录结构，读取每个子目录下的 SKILL.md 的 YAML 前置信息（名称、描述、触发词），生成一个能力索引。这个索引只包含接口信息，不加载脚本或资源，因此即使有上百个 Skill 也不会显著增加启动成本。

阶段二：触发与权限检查

当用户发出请求（例如“把这份 PDF 的文字提取出来并存为 Markdown”）时，Agent 根据关键词和语义分析匹配能力索引。如果匹配到 pdf-processing Skill，系统会进行权限检查：该 Skill 是否声明了 file_read 和 file_write 权限？当前会话是否已授权这些权限？权限不足时，Agent 会抛出明确的错误信息而非尝试绕过限制——这是安全沙箱的第一道防线。

阶段三：上下文注入与脚本调用

权限检查通过后，Agent 将 SKILL.md 的完整主体指令注入当前上下文窗口。如果 Skill 依赖 resources/ 下的文件，这些内容也会被加载（但遵循渐进式披露原则，只在相关性被确认后才加载）。当执行逻辑达到“需要脚本干预”的节点时，Agent 调用 scripts/ 下的对应文件，并等待返回结果。

阶段四：结果消费与反馈循环

脚本执行完毕后，Claude 将输出结果作为新的上下文继续推理。这意味着 Skill 不仅是一个单向的工具调用，它还能修改后续的思考方向。例如，文本提取脚本返回后，Claude 发现输出中包含了目录结构，它可以自动决定是否需要调用另一个“目录格式化”脚本。

用户请求: "提取 PDF 的文字并存为 Markdown"
  →
Agent 匹配: pdf-processing Skill
  →
权限检查: file_read ✓ | file_write ✓
  →
加载: SKILL.md 主体指令 + resources/template.md
  →
执行: scripts/extract_text.py (返回纯文本)
  →
推理: 检测到目录结构，触发格式化逻辑
  →
执行: scripts/format_markdown.py
  →
返回: 最终 Markdown 文件

子节三：设计理念——可组合、可发现、可验证

这三个理念不是口号，而是 Claude Skills 架构中每个设计决策背后的驱动原则。

可组合性：Skill 应能像乐高积木一样拼装

Anthropic 设计 Skills 时没有采用“一个大 Skill 解决一类问题”的模式，而是鼓励扁平化的目录组织：一个 Skill 就是一个原子功能。这样的设计让多个 Skill 的组合变得可能——你可以用 pdf-processing 提取内容，用 content-qa 检查质量，用 i18n 做翻译，再用 publish-blog 发布，而无需定制一个“全流程处理系统”。

可组合的关键在于输入输出的标准化。每个 Skill 通过 SKILL.md 声明它的输入类型和输出格式（通常是纯文本或结构化 JSON），这样上一个 Skill 的输出可以无缝成为下一个 Skill 的输入。这是 ETL 管道思想在 AI 领域的迁移——每个“能力节点”只负责数据的产生与消费，编排逻辑交给 Agent 的推理层。

可发现性：让 Agent 自动找到合适的 Skill

传统 Prompt 中，用户需要手动告诉模型“你应该按照 XX 标准来写报告”。在 Skills 架构下，SKILL.md 的 YAML 前置信息中的 description 和 triggers 字段，让 Agent 可以自动匹配当前任务最适合的 Skill。这种机制类似于 SEO——你通过精准的描述和关键词，让 Agent 的调度器能在数毫秒内找到正确的工具。

在实践中，这意味着描述需要具备“触发精确性”：不要写“这是一个处理文档的 Skill”，而应该写“当用户要求从 PDF、DOCX 或 TXT 中提取文本内容时，激活此 Skill”。模糊的描述会让 Skill 在不该加载时被加载，浪费 Token 并干扰推理。

可验证性：让 Skill 从“实验品”进化到“生产件”

这是 Skills 架构中最容易被低估的优势。传统 Prompt 的“质量测试”依赖人工评估——“这个回答好不好”“这次的格式对不对”——每次修改 Prompt 都需要重新人工验证。Skills 设计则引入了自动化测试：通过 SKILL.md 中指定的测试用例（或在独立的测试脚本中），你可以断言“输入 X 时，Skill 的输出必须包含 Y”或“脚本 Z 的返回码必须为 0”。

截至当前调研资料，Anthropic 官方 Skills 仓库中超过 80% 的一级 Skill 包含明确的测试用例或验证脚本——这暗示着一个明确的信号：在生产环境中，没有测试的 Skill 等同于没有测试的微服务，迟早会引发事故。可验证性不是“锦上添花”，而是“生产就绪”的必要条件。

适合谁/不适合谁

从这一节的架构解析中，你可以判断自己是否已经准备好将 Skills 作为核心工作流：

适合立即投入学习并推广 Skills 架构的开发者：

• 你的 Prompt 已经超过 2000 个 token，且包含多个“如果...那么...”的条件分支。
• 你的团队中有超过 2 个人在使用/维护同一套 Prompt，且版本差异已经开始出现。
• 你依赖外部工具（API、脚本、数据库）来完成任务，且这些调用逻辑零散分布在 Prompt 中。
• 你需要向非技术人员交付“AI 能力包”，但不希望他们看到内部逻辑。

可以从 Prompt 工程缓缓迁移的开发者：

• 你的所有工作都在一个笔记本或单次对话中完成，不需要跨会话复用。
• 你的 Prompt 短小精悍且只服务于你个人的某个固定任务。
• 你已经有一整套成熟的自动化测试体系覆盖你的 Prompt 行为。

“缓缓迁移”不是贬低——而是说 Skills 这套架构在简单场景下可能显得“过度设计”。但当你的 Prompt 开始让你感到“不敢动”时，你就不再是这个分类里的用户了。

在下一章中，我们将对比 OpenAI Agents SDK 与 Claude Skills 两种实现路径。从架构哲学上看，它们分别代表了对“可组合 AI 能力”的两种不同解读——一种强调 Agent 层面的编排，另一种强调能力包的标准化封装。理解这两者的设计差异，能让你在面对不同生态时做出最优选型。