第3章：Skills 工程实践

在使用 Claude Code 处理重复性工程任务时，常见问题是：每次新建会话，都需要重新注入一批固定上下文。

例如在生成支付模块 API 文档时，模型需要提前了解以下约束：

• 接口设计遵循 RESTful 规范
• 文档格式采用 OpenAPI 3.0
• 错误码对齐公司内部标准
• 示例数据需要真实有效
• 输出内容需要包含中英双语

这些信息本身并不会频繁变化，但如果只依赖普通对话上下文，每次开启新会话都需要重新说明。即使在同一会话中，当任务从“生成 API 文档”切换到“代码质量审查”时，也需要重新定义代码审查标准，例如审查优先级、输出格式、问题严重等级等。

类似问题也会出现在其他领域。例如进行财务分析时，模型可能需要固定加载毛利率计算公式、行业基准数据、分析口径以及报告模板。若这些知识无法被结构化复用，每次任务都需要重复输入相同背景信息。

CLAUDE.md 可以解决一部分项目级记忆问题，例如项目结构、编码规范、常用命令等。但它更适合承载通用项目上下文，无法很好地处理“按任务类型自动加载特定知识”的需求。

Skills 的作用，就是将某一类任务所需的知识、流程、规范和输出格式封装成可复用能力。这样，当用户触发特定任务场景时，Claude 可以自动加载对应 Skill，例如：

• 提到“API 文档”时，自动应用 RESTful、OpenAPI 3.0、错误码规范和双语输出要求
• 提到“代码审查”时，自动应用审查维度、严重等级和输出模板
• 提到“财务分析”时，自动应用财务指标公式、行业基准和报告结构

因此，Skills 可以理解为一种面向任务场景的上下文封装机制。它比普通提示词更稳定，比项目级记忆更精细，适合沉淀可重复使用的专业工作流。

3.1 从 CLAUDE.md 到 Skills: 知识的两个维度

3.1 从 CLAUDE.md 到 Skills：知识的两个维度

CLAUDE.md 和 Skills 解决的是两类不同的上下文管理问题。

CLAUDE.md 适合存放项目级通用规范，例如：

• 项目整体约束
• 代码缩进、命名规范、目录结构
• 常用命令

这类信息需要在当前项目中始终生效，因此通常会常驻上下文，并在每次会话中加载。它的优势是稳定、统一，但缺点也很明显：无论当前任务是否需要，这些内容都会持续占用 Token。

Skills 则适合承载任务级或领域级知识，例如：

• API 文档生成规范
• 代码审查流程
• 财务分析公式、行业基准和报告模板

**这些知识并不需要在所有任务中始终存在。只有当用户执行特定任务时，**例如“生成 API 文档”“代码审查”“财务分析”，对应知识才需要被加载。

因此，CLAUDE.md 解决的是“项目通用规则常驻”的问题，而 Skills 解决的是“专业知识按需加载”的问题。

从知识组织角度看，CLAUDE.md 更像项目的基础规则层，适合放置所有任务都必须遵守的内容；Skills 更像可复用的 SOP，用来封装某类任务的执行方法、判断标准、输入输出格式和辅助资源。

Claude Code 对 Skills 的定义可以概括为：Skill 是一个包含指令的文件夹，用于教 Claude 如何处理特定任务或工作流。

这里有两个关键点。

第一，Skill 是“文件夹”，Skill绝不仅仅是一段 Prompt 或一个简单的配置项，它是一个完整的工程化目录，可以容纳复杂的代码库、详尽的领域文档、多样的模板，甚至可执行的脚本。

第二，Skill 的目标是“教会”Claude 执行某类任务。它不是简单地限制模型行为，而是把某个任务场景中的流程、标准、资源和输出要求结构化封装起来，使 Claude 在触发该任务时能够自动采用对应的工作模式。

可以简单理解为：

CLAUDE.md 用来定义项目规则，Skills 用来封装专业任务能力。

前者解决“所有任务都要遵守什么”，后者解决“遇到某类任务时应该怎么做”。

3.2 解剖一个 Skill: 骨骼与纹理

3.2.1 目录结构

下面是一个典型的 Skill 目录结构。

api-doc-generator/     ← Skill 名称（kebab-case，短横线分隔，像文件名一样清晰）
├── SKILL.md           ←【核心骨架】必需的主技能文件（注意：大小写必须精确匹配）
├── scripts/           ←【手脚】可选的可执行脚本，让 Skill 能主动“做”事
│   └── detect-routes.py  ← 如自动扫描代码库发现路由
├── reference/      ←【记忆库】可选的按需加载参考文档，不占常驻内存
│   ├── openapi-patterns.md  ← 只有生成文档时才读取的规范
│   └── error-codes.md       ← 只有处理错误时才查阅的码表
└── templates/      ←【模具】可选的输出模板，确保产出格式统一
    └── endpoint-doc.md  ← 定义 API 文档长什么样

“这些看似烦琐的‘清规戒律”，实则是工程实践中用血泪换来的防错机制。

文件名：SKILL.md：唯一的“触发器”。文件名必须采用全大写文件名：SKILL.md，其他形式统统无效。Claude 的加载器在扫码文件时，执行的是精确字符串匹配，而非模糊搜索。

目录名：kebab-case：跨平台的“通用语”。目录名采用全小写 + 短横线的形式（如 api-doc-generator），至多64个字符，字符集限制为[a-z0-9-]。**不能存在空格、下画线、大写字母、首尾横线和连续横线。**这是为了抹平操作系统的差异。Windows 操作系统不区分大小写，Linux 操作系统严格区分。kebab-case 是互联网时代的“世界语”，它保证了你的 Skills 在任何环境、任何工具链中都能被无损识别。

禁放 README.md：纯净的“指令空间”。Skills 目录内严禁放置 README.md。人类阅读的文档应放置在父目录中。这一点至关重要。当 Claude 激活一个 Skill 时，它会贪婪地读取目录下的 Markdown 文件作为上下文。SKILL.md 包含的是给 Claude 看的指令。而 README.md 通常包含的是给人类看的介绍。如果将 README.md 混在里面，会干扰 Claude 对指令内容的理解，引人不必要的噪声。

命名中立：不要包含 “claude” 或 “anthropic” 。name 字段中不得包含品牌词。Skills 是一种通用的知识封装格式，它的生命力在于开放性。保持品牌中立，是为了让知识本身流动起来，而不是成为某个产品的附属品。

3.2.2 YAML 前置元数据: Skill 的“身份证”

SKILL.md 顶部的 YAML Frontmatter 定义了 Skill 的身份标识与行为边界。完整字段说明如下。

---
name: api-doc-generator
  #【唯一标识符】最多 64 个字符
  # 若省略，默认使用目录名

description: >
  Generate API documentation from source code. Use when
  the user asks to "write API docs", "document endpoints", or
  "create OpenAPI specs".
  Supports Express, FastAPI, and Spring Boot.
  #【触发描述】最多 1024 个字符
  # 若省略，默认使用 SKILL.md 正文的第一段

argument-hint: "[source directory] [output format]"
  #【参数提示】在 “/” 菜单中显示
  # 帮助用户了解 Skill 接受的输入格式

disable-model-invocation: true
  #【禁用模型自动调用】设为 true 时，禁止 Claude 自动调用
  # 用户必须通过 “/skill-name” 手动触发
  # 默认值: false

user-invocable: false
  #【用户可调用性】设为 false 时，从 “/” 菜单中隐藏
  # 但 Claude 仍可自动调用
  # 默认值: true

allowed-tools:
  - Read
  - Grep
  - Glob
  - Write
  - Bash(python:*)
  #【工具白名单】精确控制 Skill 执行时可调用的工具及其权限范围

model: haiku
  #【指定模型】设定该 Skill 使用的模型
  # 建议简单任务使用 Haiku，以提升响应速度并降低成本

context: fork
  #【执行上下文】设为 “fork” 时，将在隔离的子智能体中执行
  # 确保不污染主对话上下文

agent: Explore
  #【子智能体类型】当 context 设为 “fork” 时生效
  # 可选值: Explore、Plan、general-purpose 或自定义 Agent

hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - command: echo "$TOOL_INPUT" >> audit.log
  #【生命周期事件钩子】定义 Skill 激活期间的事件处理逻辑
  # 仅在 Skill 激活状态下生效
---

这些字段可划分为三大逻辑组，分别对应 Skills 设计的3个核心维度：触发机制、权限控制与运行时环境。

• 身份字段（触发机制）：包含 name、description、argument-hint。它们定义了“Skill 是什么”，负责向 Claude 和用户清晰传达 Skill 的功能定位及调用方式，是触发逻辑的基础。

• 权限字段（权限控制）：包含 disable-model-invocation、user-invocable、allowed-tools、model。它们规定了“谁能调用”以及“能做什么”，通过限制调用来源、可用工具及指定模型，构建起严格的安全与资源边界。

• 执行字段（运行时环境）：包含 context、agent、hooks。它们决定了“在哪里执行”以及“执行过程中发生什么”，用于配置隔离环境、子智能体类型及生命周期事件钩子，确保任务在预期的上下文中运行。掌握这3个维度，即掌握了 Skills 架构设计的完整框架。

disable-model-invocation 和 user-invocable 控制的是两个不同的调用入口：

• disable-model-invocation: true 表示禁止 Claude 自动触发该 Skill，只能由用户通过 /skill-name 手动调用。适合代码提交、服务部署等有副作用或高风险的操作。默认值是 false。

• user-invocable: false 表示该 Skill 不出现在 / 菜单中，用户不能手动调用，但 Claude 仍可自动调用。适合纯知识型或辅助型 Skill，避免菜单过于杂乱。默认值是 true。

• 默认情况下(两个都不写)，Skill 既可被 Claude 自动调用，也可被用户手动调用。

3.3 渐进式披露: 知识的投资回报率

与 CLAUDE.md 不同的是，Skill 是按需加载的。

Skills 系统最巧妙的设计核心——渐进式披露（ProgressiveDisclosure）。

3.3.1 图书馆模型

这里可以用一座图书馆作类比。想象你走进一座图书馆寻找资料。你绝不会一次性读完所有藏书，而是遵循一套高效的检索流程——先浏览图书分类编目定位分类，再提取目标书籍查阅图书目录，最后仅精读所需章节。

Skills系统正是采用了类似的三层渐进式披露模型（见下图），以极低的 Token 成本实现海量知识的按需
调用。

该模型在实际应用中带来的性能提升是显著的。以一个完整的财务分析Skill（总计 5300 Token）为例，其文件构成如下表所示。

数据显示，绝大多数请求仅需部分资源。当用户询问“毛利率怎么算”时，ClaudeCode只需要加载 SKILL.md（定位路由）和 profitability.md（获取公式），总计约1800 Token。其他3个文件（合计 3500 Token）完全保留在磁盘上，零消耗。这是“按需投放知识”的核心经济学优势：用最小的上下文成本，换取最大的知识覆盖范围。

3.3.2 description 的预算机制

渐进式披露的第一层级，即所有 Skill 的 description（描述），是以常驻方式注入 Claude 上下文中的。这意味着它们必须共同瓜分一个有限的 Token 预算，构成了系统的“人口瓶颈”。

Claude Code 官方的规则：description 总预算上限为上下文窗口总量的2%，若未指定或计算异常，默认固定为16000个字符。

该预算由所有已安装的 Skill 平分，而非按需分配。

计算公式：单个 Skill 可用字符数 = 总预算/ Skill 的总数（如果某个 Skill 的 description 超过 可用的字符数，那它会被排除）

假设你安装了20个 Skill，在默认16000个字符的预算下，每个 description 平均只能分到800个字符。如果某个 Skill 的 description 超过800个字符，它将被静默排除。

Claude Code 完全不知道该 Skill 的存在，既不会在扫描阶段看到它，更无法在后续步骤中加载它。对用户而言，这个 Skill 仿佛 “消失” 了。

针对 description 预算的限制，这里有 3 个关键的实操技巧，能帮你避开陷阱，灵活掌控系统。

• 技巧 1：在 SkilI 配置中设置 disable-model-invocation: true。该 Skill的 description 不会被注入上下文中。
• 技巧 2：运行诊断命令 /context 可查看是否有超出预算的 Skill 被“静默排除”。
• 技巧 3：通过调整环境变量 SLASH_COMMAND_TOOL_CHAR_BUDGET，你可以手动扩大预算池。

这个预算机制揭示了一条核心的工程哲学：不要盲目创建 Skill，而要追求“少而精”的架构设计。

当你发现需要安装超过 20 个 Skill 时，这通常是一个信号，提示你需要重新审视架构策略。

• 合并同类项。将多个零碎的 Skill 合并为一个综合性的 Skill。
• 隐藏内部工具。将纯内部调用的子任务标记为 disable-model-invocation: true，减少对预算的占用。
• 采取“Token 投资”回报率思维。将 description 中的每一个字符视为一笔昂贵的“Token 投资”，投入精准，就换来高效的检索和准确的执行；投入浪费，不仅浪费自身的预算配额，而且挤占其他 Skill 的生存空间。

3.4 触发机制: Claude Code 如何抉择 Skills 的调用

Skills 的触发机制是整个系统中最为关键，也是最需要深入理解的核心环节。它直接决定了 Skill 能否在恰当时机被激活。这一点甚至比 Skill 的内容本身的优劣更为重要。毕竟，若无法成功触发，再精彩的内容也将形同虚设。

3.4.1 双通道激活机制

每个 Skill 均支持两种激活路径。

1.显式调用

用户在对话中输入 /skill-name，Claude Code 即刻加载并执行对应 Skill。此方式类似于终端命令，具有明确、直接且无歧义的特点。若 Skill 定义了 argument-hint，用户还可携带参数进行调用，如 /commit fix login bug 或 /review src/auth/login.ts

2.语义匹配

Claude 在深入理解用户意图后，自主研判哪个 Skill 与当前任务最为契合，从而自动加载。在日常应用中，这正是 Skills 的核心价值所在。用户仅需要描述需求，Claude 便会在幕后智能决策是否调用以及如何调用最合适的 Skill。整个过程对用户完全透明，实现了“所想即所得”的无缝体验。

3.4.2 description — Skills 的灵魂

语义匹配机制完全依赖于 description 字段。该字段并非人类阅读的说明性文字，而是 Claude 在决策 “是否调用此 Skill” 时所依据的唯一信号。

Claude Code 推荐的 description 撰写结构公式如下。

[功能定义]（做什么）+［触发场景］（何时用）+［核心能力]（能做什么）

理解上述公式的最好途径，是通过对比“低效”与“高效”的写法。以下展示了两种写法的对比。

# 过于模糊，导致 Claude 无法判断使用时机
description: Helps with projects.

# 过于技术化，缺失用户视角的触发关键词
description: Implements the Project entity model with hierarchical relationships.

# 仅描述功能，未界定触发场景
description: Generates API documentation.

# 正确示范：特点是表述清晰、涵盖具体触发场景、详述核心能力
description: Generate API documentation from Express,FastAPI,or Spring Boot source code. Use when user asks to "write source code", "document endpoints", "create OpenAPI specs", or mentions "Swagger". Supports route detection，request/response schema extraction, and authentication requirement marking. 

description 字段设有1024个字符的上限。这一空间并不宽裕，因此需要字斟句酌、精心选词。

一个高效实用的写作策略可分为以下3步。

第1步：定义核心能力（What）。用一句话精准概括该 Skill“能做什么”，确定其基本功能定位。

第2步：明确触发场景（When）。使用 Use when user.. 句式，详细列举各种可能触发该 Skill 的用户指令、短语或关键词，提高语义匹配的命中率。

第3步：划定排除范围（Not For）。（可选但推荐）如果该 Skill 容易被误触发，务必加上 Not for…，明确指出其不适用的场景，以优化决策的准确性。

你撰写的 description，其核心受众是 Claude，而非人类读者。人类阅读文档时倾向于扫描标题、浏览结构，快速抓取大意；而 Claude 阅读 description 字段时是在进行深度的语义匹配。它需要捕捉用户意图的细微差别。为了提升触发准确率，你必须在 description 中穷尽用户可能使用的各种表达方式。

例如，针对“生成 API 文档”这一需求，用户可能会说 “生成API文档”、”编写接口文档”、 “输出OpenAPI 规范”、 “帮我写个 Swagger”。这些不同的表述都应显式地包含在 description 中。同义词库越丰富，语义匹配的覆盖面就越广，触发的准确率也就越高。

3.4.3 防止过触发与欠触发

在实践中，Skills 的触发机制常面临两种典型的失效模式。理解并修复这些问题，是优化 Claude 表现的关键。

1.欠触发

现象：Skill 本应被调用，但没有被调用。

数据警示：Vercel 的评测数据显示，若缺乏明确指引，Agent 有 56% 的概率完全不会去查看可用的 Skills。

根本原因：description 写得过于技术化或学术化，与用户自然的口语化表述之间存在巨大的语义鸿沟。

修复策略：“翻译”用户语言。在 description 中大量加入用户常用的表达词汇，涵盖领域术语的同义词、口语化说法，甚至是常见但不准确的表述（例如，很多用户混淆“Swagger”和“OpenAPI”，两者都需要写入)。

2.过触发

现象：Skill 在不该被调用的场景下被错误激活。

根本原因：description 定义得过于宽泛，包含了太多高频通用词汇，导致匹配阈值过低。

修复策略：引人负向约束。明确划定边界，使用 Not for.. 句式排除干扰项。

示例： “Not for general code questions or debugging. Only for structured documentation generation.”（不适用于通用代码问题或调试，仅用于结构化文档生成。)要测试一个 Skill 的触发是否准确，可以构建一个包含10～20个测试用例的验证集，同时覆盖“应触发”和“不应触发”两类场景。

以下是一个实用的测试模板示例。

应该触发的测试用例：
- "帮我生成 src/api/ 的接口文档"        → 期望触发
- "写一份 OpenAPI 规范"               → 期望触发

- "document the REST endpoints"       → 期望触发
- "帮我写 Swagger"                    → 期望触发

不应该触发的测试用例：
- "帮我 debug 这个 API 调用"           → 不应触发
- "这个接口为什么返回 500？"           → 不应触发
- "优化一下这个 API 的性能"            → 不应触发

验收标准是：针对相关任务触发率，应达到90%以上，针对无关任务误触发率，应控制在 5% 以下。

3.4.4 参考型 Skill 与任务型 Skill：两种 Skill 哲学

在 Skill 的设计哲学中，disable-model-invocation 字段不仅仅是一个简单的开关，它定义了两种截然不同的 Skill 交互模式：参考型与任务型。

1.参考型 Skill

配置：默认行为。

核心逻辑：“按需加载的知识库”。Claude 会根据对话上下文自动判断是否需要该类 Skill。description 是触发条件，直接注入 Claude 的上下文，用于语义匹配。

使用场景：提供知识、规范、框架或标准。用户不需要感知 Skill 的存在，Claude 会在合适时机自动“翻开手册”。

示例：API 设计规范、代码审查清单、行业标准文档。

2.任务型 Skill

配置：显式设置 disable-model-invocation: true。

核心逻辑：“受控的执行工具”。Claude 无法自动触发，必须由用户通过 /skill-name 命令手动调用。description 不注入 Claude 的上下文，仅作为用户在命令行中选择 Skill 时的识别说明。

使用场景：具有副作用的操作，需要用户明确授权才能执行。

示例：/commit（提交代码）、/deploy（部署应用）、/notify（发送通知）。

那么如何判断一个任务应该设计成参考型 Skill 还是任务型 Skill？

可以用一个简单的 “最坏情况测试” 来做决定，”如果 Claude 自动执行这个任务，最坏的情况是什么？”

如果答案让你感到紧张，例如，自动提交了未测试的代码、自动部署了包含 bug 的版本、自动删除了生产数据、自动发送了错误的通知，必须选择任务型 Skill。请加上 disable-model-invocation: true。把控制权牢牢握在用户手中，只有当用户显式输入 /skill-name 时才执行。

如果答案无关痛痒，例如，多展示了一段参考文档、多提供了一条建议、稍微增加了一点儿 Token 消耗，可以选择参考型 Skill。让 Claude 根据上下文智能判断，按需自动加载，为用户提供无缝的知识辅助。

核心原则：“副作用” 越大，控制权越要收紧。对于任何可能改变系统状态、造成不可逆后果的操作，永远不要信任 Claude 的自动判断。”

3.5 SKILL.md 正文：是路由器，不是仓库

理解了 Frontmatter 的触发机制和权限控制后，现在进人 SKILL.md 正文的设计核心。这是 Skills 真正发挥作用的地方。

3.5.1 路由器思维

一个常见的误区是将 SKILL.md 视为“知识仓库”，试图将所有相关信息堆砌其中。正确的设计思维应将其定位为路由器：文件自身仅包含核心流程与路由表，而详尽的知识内容则分散存储于被引用的文件中。

路由设计的核心技巧在于构建“快速参考”（Quick Reference）表格。该表格能以极低的 Token（大概3行仅需50 Token），清晰地向 Claude 指引 5个关键维度的路由条件。

3.5.2 契约式引用

在 SKILL.md 中引用辅助文件时，切勿只罗列路径。应当建立一份明确的“契约”，确保 Claude 清晰知晓3个核心要素：触发时机（何时加载）、资源位置（去哪查找）以及预期产出（获取何物）。

以下示例展示了“弱引用”与“契约式引用”的写法。

# 弱引用：缺乏上下文（Claude 无法判断何时该加载此文件，缺乏行动指令）
See `reference/revenue.md` for more details.

# 契约式引用：明确条件 + 路径 + 内容预期
## Revenue Analysis
When the user asks about revenue growth, ARPU, or revenue composition:
  → Load `reference/revenue.md` for calculation formulas and industry benchmarks.

这一设计理念与子智能体流水线中的“交接契约”一脉相承：下游消费者不仅需要知道上游的位置，更必须明确上游能提供什么。

3.5.3 500 行法则

Claude Code 建议将 SKILL.md 的篇幅控制在500行以内。

为何设定为500行？这是因为500行代码等于2000~3000 Token，是单个 Skill 激活后合理的上下文开销。将其与 Claude 的 System Prompt 及当前对话历史累加，能确保总 Token 数维持在可控范围内。若超过500行，通常意味着你将 ‘参考资料’ 与 ‘路由指令’ 混淆了，此时的应对策略并非继续扩充内容，而是立即进行重构。

下表列出了当 Skills 内容过载时的重构信号及对策。

3.6 allowed-tools: 知识约束行动

allowed-tools 是 Skills 安全架构中的核心字段。它不仅仅是一份权限清单，更体现了一项深层设计原则：知识应当约束行动。

具体的权限配置应基于 Skills 对业务逻辑的“认知”。

代码审查 Skills：审查过程仅需读取代码，严禁修改，因此仅授予只读工具。

文档生成 Skills：需要创建新文件，但绝不应篡改既有文件，因此仅授予写入（Write）权限，但明确禁止编辑（Edit）权限。

测试运行 Skills：仅需要执行特定的测试命令，因此精确限制可执行的 Bash 命令，防止任意命令注入。

3.6.1 权限设计模板

以下是针对不同 Skill 类型的 allowed-tools 配置最佳实践。这些配置体现了最小权限原则，确保每个 Skill 仅拥有完成其特定任务所需的最低限度工具权限。

# 审计类Skill：严格只读
allowed-tools:
  - Read
  - Grep
  - Glob

# 生成类Skill：可写不可改
allowed-tools:
  - Read
  - Grep
  - Glob
  - Write

# 分析类Skill：只读 + 特定脚本
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(python:*)

# 执行类Skill：受控命令白名单
allowed-tools:
  - Read
  - Bash(git status:*)
  - Bash(git add:*)
  - Bash(git commit:*)
  - Bash(npm test:*)

3.6.2 Bash 的精细控制语法

Bash 工具支持通过前缀匹配机制，实现对可执行命令的细粒度管控。其核心语法为 Bash(prefix:*)，其中 prefix 指定允许的命令前缀，*作为通配符代表后续参数。

权限控制示例如下。

Bash(git:*)              # 允许所有以 git 开头的子命令
Bash(git log:*)          # 仅允许 git log 及其参数，禁止 git push 等危险操作
Bash(npm test:*)         # 仅允许运行测试命令，防止误执行 npm install 或 npm publish
Bash(python:*)           # 允许所有 Python 脚本执行
Bash(./scripts/*:*)      # 允许执行 scripts/ 目录下的特定脚本

当 Claude 尝试执行 Bash 命令时，系统会进行前置校验。

• 提取前缀：获取用户请求执行的完整命令字符串。
• 匹配规则：检查该命令是否匹配 prefix 开头。

执行决策：若匹配成功，则放行执行；若匹配失败，则直接拒绝，并返回权限错误。

遵循权限最小化原则（Principle of Least Privilege）是构建安全 Skills 的基石。以下是关于 allowed-tools 配置的正反案例对比。

# 精确授权：只明确列出任务所需的具体命令子集
# 场景：代码提交 Skill
# 策略：仅允许 status、add、commit 3个特定子命令
allowed-tools:
- Bash(git status:*)
- Bash(git add:*)
- Bash(git commit:*)

# 过度授权：使用全局通配符等同放弃所有防线
# 场景：错误的通用配置
# 风险：允许执行任意 Shell 命令
allowed-tools:
- Bash(*)

Bash(*)在安全性上几乎等价于未设置 allowed-tools。这意味着
Claude Code 获得了宿主机的完整 Shell 权限。对于像 /deploy 这样的高危任务型 Skill，这种配置是致命的。一旦模型被提示注入攻击权限，攻击者可利用此权限窃取密钥、删除生产数据或植入后门。

3.7 参数传递与动态注入

Skills 不仅是静态指令，更支持运行时参数传递与上下文预注入，使其行为能够根据调用场景进行动态调整。

3.7.1 $ARGUMENTS 和位置参数

当用户通过 /skill-name arg1arg2 调用 Skills 时，可在 SKILL.md 正文中引用下表所示的变量。

一个引用示例如下。

---
name: migrate-component
description: Migrate a component between frameworks
argument-hint: "[component] [from] [to]"
disable-model-invocation: true
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

当执行调用 /migrate-component SearchBar React Vue 时，Claude 实际接收到的指令为“Migrate the SearchBar component from React to Vue. Preserve all existing behavior and tests.”。

3.7.2 动态上下文注入

这是 Skills 系统中最具威力且独一无二的特性。!`command` 语法允许在将 SKILL.md 发送给 Claude 之前，先在 Shell 环境中执行指定命令，并将命令的输出结果直接内联替换到 Prompt 中，再交给 Claude。

“动态上下文注入”的意思是：Claude 在执行任务前，系统先自动收集当前项目状态，然后把这些状态作为上下文一起发给 Claude。

一个示例如下。

## Current Context (Auto-detected)

Current branch:
!`git branch --show-current`

Recent commits:
!`git log origin/main..HEAD --oneline 2>/dev/null || echo "No commits"`

Files changed:
!`git diff --stat origin/main 2>/dev/null || git diff --stat HEAD~3`

前面的 ! 表示：不要把这行原样发给 Claude，而是先在 Shell 里执行这个命令，然后把执行结果填到这里。

所以下面这句什么意思？

Current branch: !`git branch --show-current`

git branch --show-current 意思是 查看当前 Git 分支名。假设你现在在这个分支 feature/auth 那这条命令执行后，就会输出 feature/auth

所以原来的：

Current branch: !`git branch --show-current`

会变成：

Current branch: feature/auth

当执行 /pr-create “Add auth” 命令时，Claude 实际接收到的已是填充了动态数据的 Prompt。

## Current Context (Auto-detected)

Current branch:
feature/auth

Recent commits:
a1b2c3d Add JWT middleware
d4e5f6g Add login endpoint

Files changed:
src/auth/middleware.ts | 45 +++
src/auth/login.ts      | 82 +++
2 files changed, 127 insertions(+)

这一设计的工程价值巨大。!`command` 特性未使用与使用的对比如下表所示。

Claude 在执行 !`command` 时会遵循严格的时序：先替换 $ARGUMENTS 变量，再执行 Shell 命令。这意味着用户的输入内容将被直接拼接到 Shell 命令中，若未加管控，极易受到 Shell 注入攻击。所以必须用 allowed-tools 限制 Skill 能执行的命令范围，避免它变成“用户想让它执行什么就执行什么”。

比如用户输入的不是：

Add auth

而是故意输入：

Add auth"; rm -rf .; echo "

那原来的模板：

git log --grep="$ARGUMENTS"

替换后可能就变成：

git log --grep="Add auth"; rm -rf .; echo ""

这就严重了。

Shell 会把它理解成三条命令：

git log --grep="Add auth" rm -rf . echo ""

其中：

rm -rf .

可能会删除当前目录下的文件。

这就是所谓的 Shell 注入攻击。

3.8 作用域与优先级

Skills 文件可部署于不同的层级，每个层级对应特定的生效范围与适用场景，具体如下表所示。

当多个来源存在同名的 Skill 时，系统将按照从高到低的优先级顺序进行解析与加载。

企业策略 > 个人配置（~/.claude/） > 项目配置（.claude/）> Plugin 内置

这一优先级顺序的设计逻辑严格遵循企业治理架构，确保了从“强制底线”到“个性化偏好”的有序过渡。

• 企业策略（不可逾越的底线）：企业级配置拥有最高权限，用于强制执行全局安全与合规策略。例如，安全审计类 Skill 必须强制检查 OWASP Top 10 漏洞，此类的关键规则绝不允许被项目级或个人配置覆盖，从而确保组织层面的安全红线不被突破。

• 个人配置（个性化效率工具）：位于个人目录的配置旨在满足开发者的个人习惯。例如，用户可以定义 /commit 命令，使其自动按照 conventional commit 规范生成提交消息，这种偏好仅作用于个人环境，不影响他人。

• 项目配置（业务场景定制）：位于项目根目录的配置，专为特定代码库服务。例如，某个前端项目可定制专属的组件文档生成 Skill，以适配其特有的技术栈和文档结构。

将 Skill 目录（.claude/skills/）纳入项目的 Git 版本控制，是实现团队知识零成本共享的最优解。

• 即插即用：团队新成员克隆代码库后，相关 Skill 自动生效，无需任何手动安装或配置步骤。

• 同步演进：随着项目选代，Skill 库可随代码一同更新，确保团队始终使用最新的工作流规范。

3.9 实战: 从零构建 3 类 Skill

理论阐述至此已臻完备，接下来我们将进人核心的工程实战环节。

在本节中，我们将通过 3 个复杂度递进的完整案例，手把手演示如何构建高价值的 Skill。这 3 个案例并非随意选取，而是精准对应了前面所述的 3 种典型应用场景。

3.9.1 参考型 Skill: 代码审查

某团队每日需要执行大量代码审查。为此，团队制定了以下内部约定。

优先级原则：优先关注安全问题，其次是性能问题，最后才是代码风格。

反馈要求：必须提供具体的修改建议，严禁仅指出问题而不给方案。

分级标注：每个问题均需标注严重等级。

鉴于相关规范散落在不同文档中，新人难以一次性掌握，现整理如下核心指南及目录结构。

目录结构如下。

code-reviewing/
├── SKILL.md              # 核心审查流程与标准
└── reference/
    └── severity-guide.md # 详细等级判定标准

SKILL.md 的核心内容如下。

---
name: code-reviewing
description: Performs structured code reviews following team standards. Checks security vulnerabilities, performance issues, and code quality in priority order. Use when user asks to "review code", "do a code review", "check this PR", "audit this function", or provides code and asks for feedback.
allowed-tools:
  - Read
  - Grep
  - Glob
---

# 代码审查流程

你是一名资深代码审查员。执行审查时，请严格遵循以下优先级顺序

## 第一优先级：安全检查

发现以下安全问题应立即报告：
- SQL 注入风险：如直接拼接 SQL 字符串、未使用参数化查询
- XSS 漏洞：未转义的用户输入直接输出至 HTML
- 敏感信息硬编码：包括密码、密钥、Token、数据库连接字符串等
- 权限验证缺陷：如缺失认证中间件、存在越权访问逻辑

## 第二优先级：性能问题

- N+1 查询：循环内频繁调用数据库
- 索引缺失：高频查询字段未建立索引
- 重复计算：循环内存在可提升至循环外的不变量计算
- 内存泄漏风险：如未关闭的连接、持续增长的缓存等

## 第三优先级：代码质量

- 函数过长：超过 50 行且无合理理由
- 命名不规范：变量或函数命名含义不清
- 错误处理缺失：如空的 catch 块、异常被静默吞掉
- 代码重复：违反 DRY 原则

## 输出格式规范

每个发现的问题必须包含以下 4 项要素：
- 严重等级：Critical/ Major/ Minor
- 问题描述：具体阐述问题所在
- 文件位置：file_path:line_number
- 修改建议：提供具体的代码修正方案或解决策略

若未发现任何问题，请明确回复“通过审查”，并简述已检查的主要方面

注：详细的等级判断标准请参见 `reference/severity-guide.md`。

该 Skill 的设计聚焦三大核心要点。

• 只读权限保障：仅开发 Read、Grep、Glob 工具，从机制上杜绝审查过程中意外修改代码的风险。

• 优先级排序策略：严格遵循“安全 > 性能 > 质量”的审查顺序，确保关键隐患优先被发现，避免遗漏。

• 结构化输出规范：统一采用 “严重等级+问题描述+文件位置+修改建议” 的输出格式，保证每次审查结果的一致性与可追溯性。

3.9.2 任务型 Skill: 智能提交

开发者可能每日需要频繁提交代码（日均十余次），手动撰写 commit message 既耗时又容易不规范。为此，我们设计了以下任务型 Skill。鉴于该操作具有副作用（直接修改 Git 历史），系统设定为必须由用户主动触发，严禁自动执行。

---
name: committing
description: Quick git commit with auto-generated or specified message
argument-hint: "[optional: commit message]"
disable-model-invocation: true
allowed-tools:
  - Bash(git status:*)
  - Bash(git add:*)
  - Bash(git commit:*)
  - Bash(git diff:*)
model: haiku
---

# Task: Create a git commit

## Input Handling
If a message is provided: $ARGUMENTS
- Use that as the commit message
If no message is provided:
- Analyze the changes with `git diff --staged` (or `git diff` if nothing staged)
- Generate a concise, meaningful commit message

## Current State (Auto-detected)

Git status:
!`git status --short 2>/dev/null || echo "Not a git repository"`

Staged changes:
!`git diff --staged --stat 2>/dev/null || echo "Nothing staged"`

## Steps

1. Check `git status` to see current state
2. If nothing staged, run `git add .` to stage all changes
3. Review what will be committed with `git diff --staged`
4. Create commit with appropriate message
5. Show brief confirmation

## Commit Message Format

- Start with type: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
- Be concise but descriptive (max 72 chars for first line)
- Example: `feat: add user authentication with JWT`

## Output

Show a brief confirmation:
√ Committed: [commit message]
[number] files changed

上述 Skill 展示了多项高级特性的深度组合。

• 安全控制（disable-model-invocation: true）：强制禁用模型调用，确保执行过程纯粹依赖预设脚本，防止意外的 AI 推理介入。

• 动态参数（$ARGUMENTS）：支持灵活的参数传递机制，允许用户直接指定提交信息或留空以触发自动生成。

• 上下文预注入（!`command`）：利用 Shell 命令在执行前即时捕获并注入当前的 Git 状态。这使得 Claude 在启动时即拥有完整的上下文信息，不需要额外调用工具即可感知变更内容，显著提升了响应速度。

• 成本与性能优化（model:haiku）：指定使用轻量级模型（Haiku）。鉴于提交操作主要依赖规则匹配而非复杂推理，该配置在保证准确性的同时，有效降低了延迟与资源消耗。

一个使用示例如下。

# 自动生成提交信息（commit message）
/committing
# 指定提交信息
/committing fix: resolve login validation bug

3.9.3 复合型 Skill: 财务分析（渐进式披露完整案例）

本案例展示了一种高度模块化的渐进式披露架构。该设计通过分层解耦，实现了复杂任务的高效管理。

• 主控层：由主文件负责意图识别与流程路由。

• 知识层：由参考文件提供垂直领域的深度知识与基准。

• 规范层：由模板确保输出格式的高度一致性。

• 执行层：由脚本封装确定性的计算逻辑，消除幻觉风险。

目录结构如下。

financial-analyzing/
├── SKILL.md                         #【主控层】核心入口：负责意图识别与流程路由
│
├── reference/                       #【知识层】领域知识库
│   ├── revenue.md                   # 收入分析：公式定义、行业基准与关键指标
│   ├── costs.md                     # 成本分析：成本结构、分摊逻辑与基准
│   └── profitability.md             # 盈利分析：利润率计算模型与评估标准
│
├── templates/                       #【规范层】输出标准化
│   └── analysis_report.md           # 分析报告：结构化模板，确保交付物格式统一
│
└── scripts/                         #【执行层】确定性计算
    └── calculate_ratios.py          # 计算引擎：执行精确的财务比率运算，避免模型计算误差

SKILL.md 的核心内容如下。

---
name: financial-analyzing
description: Analyze financial data, calculate financial ratios, and generate analysis reports. Use when the user asks about revenue, costs, profits, margins, ROI, financial metrics, or needs financial analysis of a company or project.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(python:*)
---

# Financial Analysis Skill

You are a financial analyst. Help users analyze financial data, calculate key metrics, and generate insightful reports.

## Quick Reference

|  Analysis Type   |  When to Use      |    Reference               |
|------------------|-------------------|-----------------------------|
| Revenue Analysis | 收入、营收、销售额   | `reference/revenue.md`      |
| Cost Analysis    | 成本、费用、支出    | `reference/costs.md`         |
| Profitability    | 利润、毛利率、净利率 | `reference/profitability.md` |

## Analysis Process

### Step 1: Understand the Question
- What financial aspect is the user asking about?
- What data do they have available?

### Step 2: Gather Data
- Request necessary financial data from user
- Or read from provided files/sources

### Step 3: Calculate Metrics
For specific formulas and calculations:
- Revenue metrics → see `reference/revenue.md`
- Cost metrics → see `reference/costs.md`
- Profitability metrics → see `reference/profitability.md`

To run calculations programmatically:
```bash
python scripts/calculate_ratios.py <data_file>
```

### Step 4: Generate Report
Use the template in `templates/analysis_report.md` for structured output.

## Output Guidelines
1. Always show your calculations
2. Explain what each metric means in plain language
3. Provide context (industry benchmarks when available)
4. Give actionable recommendations
5. Never make up financial data — ask for clarification if incomplete

上述 SKILL.md 仅约 200 行，完全符合 “500行法则”。

其中的“快速参考”（Quick Reference）表格充当了路由器的角色：当 Claude 识别到 “毛利率” 时，能直接定位至 reference/profitability.md 获取公式，不需要加载收入与成本相关的冗余文件。此外，calculate_ratios.py 脚本封装了确定性计算的逻辑，使 Claude 不需要执行易出错的浮点数运算，只需要调用脚本即可获取精确结果。

这是 “渐进式披露” 理念的完整体现：以最小的 Token 投入，实现任务完成质量的最优化。

3.10 Skills 的4种设计模式

从工程实践中，我们提炼出 4 种经过验证的 Skill 设计模式（见下图)。这些模式并非互斥，成熟的 Skills 系统通常会组合运用多种模式。

• 模板驱动模式：利用预定义模板严格约束输出格式。该模式适用于周报、事故报告、审查报告等需要标准化输出的场景。在此模式下，Claude 的输出将严格遵循模板结构，确保结果具备可预期性、可对比性，并支持自动化后处理。

• 脚本增强模式：将确定性计算逻辑封装为脚本，由模型调用执行而非自行推导。该模式适用于财务计算、正则匹配、数据转换等场景。相较于大模型推理，脚本执行更精准、更节省 Token 且更具可复现性。一条经验法则是：如果发现自己在 SKILL.md 中编写公式使 Claude 运行计算，请立即停止一该逻辑应当被移至脚本中。

• 知识分层模式：依据使用频率对知识进行分层组织。遵循“80/20法则”（即80%的请求仅需要20%的核心内容），将高频知识内联至 SKILL.md，而低频知识则置于引用文件中按需加载。这正是“渐进式披露”理念的模式化总结。

• 工具隔离模式：通过 allowed-tools 机制严格界定 Skill 的能力边界。这属于安全设计范畴，而非单纯的功能设计，其核心价值在于明确“禁止做什么”，这往往比定义“能做什么”更为关键。例如，审计类 Skill 不授予写入权限，生成类 Skill 不授予修改权限。

3.11 测试与迭代

写完 Skill 就结束了吗？当然没有。Skill 是活文档，需要持续打磨。

Claude Code 官网推荐了 3 类核心测试方法，以确保 Skill 的健壮性。

• 触发测试：准备 10 个应触发 Skill 的问题和 10 个不应触发的问题，以验证 Claude 判断的准确率。目标是，相关任务触发率需要高于90%，而无关任务误触发率应低于 5%

• 功能测试：验证 Skill 加载后的执行质量。检查点包括输出格式是否符合预期、检查项是否完整覆盖、边界情况是否得到妥善处理。

• 性能对比：针对同一任务，分别在 “有 Skill” 和 “无 Skill” 两种状态下各执行 5 次，对比 Token 消耗量、用户修正次数以及最终输出质量。

如果你发现自己反复手动修正 Claude 的输出（例如，每次都要提醒它 “记得标注认证要求” ），这是 SKILL.md 正文需要更新的明确信号。将修正逻辑直接写入 SKILL.md，下次就不会发生同类错误。

这个选代过程与传统软件的 bug 修复循环完全一致：发现问题→定位原因（description 不精确？步骤遗漏？格式定义模糊？）→ 修复文档 → 验证效果。

Claude Code 还提供了一个名为 skill-creator 的专用 Skill，它能协助你从自然语言描述中生成 SKILL.md 的初始版本。指令示例如下。

Use the skill-creator skill to help me build a skill for [your use case]

该工具的存在本身揭示了一个重要事实：Skills 系统已经足够成熟，实现了“自举”，即利用 Skills 系统自身来构建新的 Skill。

3.12 从软件工程看 Skills

正如子智能体一样，Skills 也是一个全新的概念。它的核心本质，是将软件工程中历经验证的经典智慧，迁移并适配到 AI Agent 的知识架构之中。

1.关注点分离（Separation of Concerns）

核心理念：“授人以鱼，不如授人以渔”。Skills 将解决问题的方法、步骤与经验沉淀为可复用的结构化资产，而非仅提供一次性答案。这使得 Agent 从依赖 “临时灵感” 转变为能够稳定复现高质量工作流。

三层架构职责划分如下。

• CLAUDE.md：全局规则（项目背景、通用规范）。

• Skills：专业工作流（特定领域的复杂逻辑封装）。

• 子智能体：任务执行（动态规划与实时操作）。

工程师警示：严禁将所有逻辑塞入 CLAUDE.md。如同在软件开发中将所有代码写在 main 函数中一样，这会导致上下文冗余、维护困难且难以扩展。

2.依赖倒置（Dependency Inversion）

核心机制：面向接口编程，而非面向实现编程。

Claude 不直接依赖 Skill 的具体内部实现（如具体的脚本或 Prompt 细节），而是依赖其抽象接口（即 description 和输出契约）。只要保持接口契约不变，开发者可以随时替换、重构或升级 Skill 的内部逻辑。

对 Claude 和用户来说，这种变化是完全透明的，极大地降低了系统的耦合度。

3.缓存优化与情性加载

核心策略：渐进式披露 = 按需加载。

“渐进式披露”是一种典型的惰性加载（Lazy Loading）策略。系统不在启动时预加载所有知识库，而是在首次需要特定技能时才加载相关资源。

这与Web开发中的代码分割（Code Splitting）和数据库中的延迟加载的思想异曲同工：在正确的时间加载正确的资源，从而最小化初始开销，提升响应速度。

4.最小权限原则

安全基石：allowed-tools 是安全经典在 AI 领域的直接映射。

仅授予 Skill 完成其职责所恰好足够的权限，不多也不少。如同 Linux 操作系统中使用 hmod 精确控制文件读写执行权限、AWS 中使用 IAM Policy 精细限定服务访问范围。

明确 “不能做什么” 比定义 “能做什么” 更能保障系统安全，防止恶意代码或幻觉导致的越权操作。

5.开放标准

生态愿景：声明式、自包含、知识本位。

Anthropic 将 Skills 作为 Agent Skills 的开放标准（agentskills.io）规范推广。自 2025 年 12 月发布以来，已有超过 27 个 Agent 平台（包括 OpenAI Codex CLI、Google Gemini CLI、Cursor、GitHub Copilot 等）提供原生支持。

Skills 成功的三大本质属性如下。

• 声明式（Declarative）：纯 Markdown 格式，任何大模型均可读取和理解，无黑盒二进制。

• 自包含（Self-contained）：一个文件夹即包含全部所需，复制即安装，无需复杂的依赖管理。

• 知识本位（Knowledge-Centric）：核心价值在于内容本身而非特定格式，不绑定单一平台。

开发者在 Claude Code 中精心设计的 Skill，理论上可以无缝迁移至任何支持该标准的 AI 平台，真正实现了“一次编写，到处运行”。

这不仅仅是一个关于产品特性的故事，而是一个关乎行业标准的故事。你所学到的，不只是“如何在 Claude Code 中配置某项功能”，而是“如何为 AI Agent 生态构建标准化的知识包”。

本章小结

Skills 直击开发者日常痛点：如何让 Claude 永久铭记专业工作范式，从而避免在每次对话中重新“教学”。在 Claude Code 的五层架构中，Skills 位居知识层，上承工具层（定义“能做什么”），下启智能体层（决定“谁来做”）。它向下通过 allowed-tools 约束工具行为，向上利用 skills 字段为子智能体注入专业知识，并与 CLAUDE.md 形成互补（前者常驻生效，后者按需调用）。

理解这套机制，关键在于把握四大核心设计。

• 渐进式披露：实现知识的按需加载。从始终驻留上下文的 description，到触发时加载的 SKILL.md 正文，再到执行中动态读取的引用文件。这一机制在多数场景下可节省 50%～98% 的 Token 消耗。

• 语义触发：确保专业能力在恰当时机自动激活。其中，description 是此机制的灵魂：它并非供人类阅读的说明书，而是辅助 Claude 决策的“语义指纹”。

• 安全约束：通过 allowed-tools 将知识限定在安全的行动边界内，实现“知行合一”的安全设计。

• 动态注入：借助参数传递（$ARGUMENTS）与命令执行（!`command`），赋予 Skill 依据运行时上下文灵活应变的能力。

从更宏观的视角审视，Skills 实质上是人类组织数十年知识管理经验的数字化映射。在此体系中，SKILL.md 等同于部门 SOP 首页，reference/ 对应企业知识库，templates/ 即标准化输出模板，而 scripts/ 则是自动化工具集——这些角色在任一成熟企业中皆能找到精准对标。

更为关键的是，Skills 通过开放标准（agentskills.io）规范，将这一映射从企业内部拓展至行业层面：它推动知识管理从企业级的 “SOP” 跃升为行业级的 “ISO 标准”，确保 Skills 的知识价值不再受制于单一平台，而是成为整个生态的通用资产。