# 第11章 技能系统与插件架构

> "好的架构让增加功能变简单，伟大的架构让移除功能也一样简单。"
> -- 《架构整洁之道》改编

**学习目标：**
- 掌握 Claude Code 技能（Skill）的定义、加载和执行机制的完整生命周期
- 理解从用户级到管理级的技能分层策略及其安全含义
- 学会创建自定义技能的完整流程和最佳实践
- 了解插件系统的缓存优先加载模型和安全边界
- 掌握技能组合使用的模式和反模式

---

## 11.1 技能系统架构

Claude Code 的技能系统是一个多层次的扩展机制。它允许用户通过 Markdown 文件定义可复用的 prompt 模板，也允许开发者通过 TypeScript 代码注册编译时内置的技能。整个系统的设计目标是：**零配置可用，有配置强大**。

这就像一套厨师的工具箱：内置的刀具和锅具（内置技能）可以应对大部分烹饪需求，但当你需要制作特定菜系时，可以添加专用的工具（自定义技能）。而且，这些工具可以按层级管理——家庭厨房（用户级）、餐厅厨房（项目级）、连锁餐饮标准（管理级）。

### 11.1.1 内置技能清单

内置技能（Bundled Skills）是编译进 CLI 二进制文件的技能，对所有用户开箱即用。它们在启动时通过 `initBundledSkills()` 统一注册。

注册入口函数根据功能标志决定加载哪些技能。技能分为两类：

- **核心技能**：始终注册，如 `verify`、`debug`、`simplify`、`remember`、`batch`、`stuck` 等
- **Feature-gated 技能**：通过功能门控，仅在对应功能标志启用时注册，如 `loop`（AGENT_TRIGGERS）、`claude-api`（BUILDING_CLAUDE_APPS）、`schedule`（AGENT_TRIGGERS_REMOTE）

核心内置技能的完整清单如下：

| 技能名称 | 用途 | 用户可调用 | 典型使用场景 |
|---------|------|-----------|------------|
| `update-config` | 配置 settings.json 的各项设置 | 是 | 修改权限规则、环境变量、默认模型 |
| `keybindings-help` | 键盘快捷键自定义帮助 | 是 | 查看和自定义按键绑定 |
| `verify` | 验证代码变更的正确性 | 是 | 提交前的最终验证、CI 前的本地检查 |
| `debug` | 调试辅助，提供诊断思路 | 是 | 定位 bug 根因、分析错误堆栈 |
| `simplify` | 代码简化与重构审查 | 是 | 消除重复代码、降低圈复杂度 |
| `skillify` | 将 prompt 转换为可复用的技能 | 是 | 将一次性的 prompt 模板化 |
| `remember` | 记忆管理（CLAUDE.md 条目） | 是 | 添加项目规范、团队约定 |
| `batch` | 批量文件处理 | 是 | 批量重命名、批量格式化 |
| `stuck` | 帮助模型走出困境 | 是 | 模型陷入循环时的"解围"指令 |
| `lorem-ipsum` | 生成占位内容 | 是 | UI 开发时的占位文本 |

```mermaid
graph TD
    subgraph 代码质量层
        V["verify"]
        S["simplify"]
        D["debug"]
    end
    subgraph 工作流层
        B["batch"]
        ST["stuck"]
        SK["skillify"]
    end
    subgraph 配置层
        UC["update-config"]
        R["remember"]
        KH["keybindings-help"]
    end
    subgraph FG["Feature-gated 层（需特定功能标志）"]
        L["loop<br/>(TRIGGERS)"]
        CA["claude-api<br/>(APPS)"]
        SC["schedule<br/>(REMOTE)"]
    end

    style 代码质量层 fill:#e3f2fd,stroke:#1976D2,color:#1565C0
    style 工作流层 fill:#e8f5e9,stroke:#388E3C,color:#2E7D32
    style 配置层 fill:#fff3e0,stroke:#F57C00,color:#E65100
    style FG fill:#fce4ec,stroke:#C62828,color:#B71C1C
```

### 11.1.2 内置技能注册机制

每个内置技能通过注册函数注册，接收一个技能定义对象，包含以下关键字段：名称、描述、别名、使用场景提示、参数提示、允许的工具列表、模型指定、是否禁用模型调用、是否用户可调用、运行时门控回调、生命周期钩子、执行上下文（inline 或 fork）、关联的智能体、引用文件集合，以及最关键的 prompt 生成器函数。

其中最关键的几个字段：

- prompt 生成器：延迟执行的 prompt 生成器，仅在技能被调用时才运行
- `files`：可选的引用文件集合，首次调用时提取到磁盘，允许模型通过 Read/Grep 访问
- `isEnabled`：运行时门控回调，如 `/loop` 技能每次调用时检查相关功能是否启用
- `context: 'fork'`：标记技能在独立子进程中执行

#### 文件提取的安全设计

文件提取采用了精巧的惰性单例模式，使用 `??=` 操作符确保并发调用共享同一个提取 Promise，避免竞态条件。文件写入使用 `O_NOFOLLOW | O_EXCL` 标志防止符号链接攻击，目录权限设置为 `0o700`，文件权限设置为 `0o600`。

这些安全措施的含义：

| 安全措施 | 保护的攻击向量 | 工作原理 |
|---------|-------------|---------|
| `O_NOFOLLOW` | 符号链接劫持 | 如果路径是符号链接则打开失败 |
| `O_EXCL` | TOCTOU 竞态 | 文件必须不存在，确保是新建而非覆盖 |
| `0o700` 目录 | 目录遍历 | 只有所有者可以访问目录 |
| `0o600` 文件 | 文件泄露 | 只有所有者可以读写文件 |
| `??=` 单例 | 竞态条件 | 并发调用共享同一个 Promise |

> **为什么技能需要引用文件？**
>
> 某些技能（如 `verify`）在执行时需要参考额外的文档或配置。这些文件被编译进二进制文件中（不作为独立的磁盘文件存在），但在技能首次被调用时需要提取到磁盘。这样设计有两个好处：第一，技能的分发不需要额外的文件管理；第二，文件在提取时有完整的安全检查。
>
> 可以把它想象成"软件附带的说明书"——不需要时它不占地方（嵌入在二进制中），需要时才展开到桌面上（提取到临时目录）。

### 11.1.3 技能加载引擎

所有文件系统上的技能（非内置）由统一的加载引擎加载。这是一个会话内缓存的异步函数。

加载引擎的核心流程如下：

```mermaid
flowchart TD
    A["启动"] --> B["getSkillDirCommands(cwd)"]
    B --> C{"bare mode?"}
    C -->|"Yes"| C1["只加载 --add-dir 指定的路径"]
    C -->|"No"| D["并行加载五个来源"]
    D --> D1["[1] managedSkillsDir 管理策略级"]
    D --> D2["[2] userSkillsDir 用户级 ~/.claude/skills/"]
    D --> D3["[3] projectSkillsDirs 项目级 .claude/skills/"]
    D --> D4["[4] additionalDirs --add-dir 额外目录"]
    D --> D5["[5] legacyCommands 旧版 /commands/ 目录"]
    D1 --> E
    D2 --> E
    D3 --> E
    D4 --> E
    D5 --> E
    E["合并 + 按文件路径去重 (realpath)"] --> F["分离条件技能 (paths frontmatter) 和无条件技能"]
    F --> G["返回无条件技能列表"]

    style A fill:#3498db,stroke:#2471a3,color:#fff
    style G fill:#2ecc71,stroke:#27ae60,color:#fff
```

去重策略使用 `realpath` 解析符号链接得到规范路径，然后按首次出现的来源保留。这避免了通过符号链接或重叠的父目录导致的重复加载。

> **为什么需要去重？**
>
> 考虑这样的目录结构：
> ```
> /home/user/projects/my-app/        ← 项目目录
> /home/user/projects/my-app/symlink ← 指向 .claude/skills/ 的符号链接
> ```
>
> 如果不做 `realpath` 解析，同一个技能目录可能通过两条路径被加载两次：一次通过原始路径 `.claude/skills/my-skill/`，一次通过符号链接 `symlink/my-skill/`。这会导致技能被注册两次，可能产生冲突或重复执行。`realpath` 解析确保无论通过什么路径访问，最终都指向同一个物理位置。

---

## 11.2 技能定义格式

### 11.2.1 Markdown Frontmatter 配置

文件型技能以目录形式组织，每个技能是一个名为 `skill-name/` 的目录，其中包含一个 `SKILL.md` 文件。这是唯一的目录结构格式。

`SKILL.md` 支持 YAML frontmatter 配置。解析逻辑支持的字段包括：

```yaml
---
name: my-skill-display-name
description: 这是一个示例技能
when_to_use: 当用户需要执行某操作时使用
arguments: arg1 arg2 arg3
argument-hint: "[arg1] [arg2] [arg3]"
allowed-tools:
  - Bash
  - Read
  - Write
model: claude-sonnet-4-20250514
effort: high
user-invocable: true
disable-model-invocation: false
context: fork
agent: code-builder
version: "1.0"
paths:
  - "src/**/*.ts"
  - "lib/**/*.js"
hooks:
  pre:
    - command: npm run lint
  post:
    - command: echo "done"
shell: bash
---

# 技能正文

这是技能的主要内容，支持 Markdown 格式。
可以使用 $ARGUMENTS 引用用户输入的参数。
使用 $1, $2 引用位置参数。
使用 ${CLAUDE_SKILL_DIR} 引用技能目录。
使用 ${CLAUDE_SESSION_ID} 引用当前会话 ID。
```

#### 字段详解与最佳实践

| 字段 | 类型 | 必填 | 说明 | 最佳实践 |
|------|------|------|------|---------|
| `name` | string | 否 | 技能显示名称 | 省略时使用目录名，建议使用 kebab-case |
| `description` | string | 是 | 技能描述 | 简洁明了，一句话说清功能 |
| `when_to_use` | string | 否 | 使用场景描述 | 帮助模型自动选择合适的技能 |
| `arguments` | string | 否 | 参数名列表 | 用空格分隔，命名参数增强可读性 |
| `allowed-tools` | list | 否 | 允许的工具 | 遵循最小权限原则，只列出必要工具 |
| `model` | string | 否 | 使用的模型 | 只读任务用 haiku，复杂任务用 inherit |
| `context` | string | 否 | 执行上下文 | fork 用于耗时任务，inline 用于快速操作 |
| `paths` | list | 否 | 条件激活路径 | 用于按文件类型自动激活技能 |
| `hooks` | object | 否 | 生命周期钩子 | pre/post 命令用于自动化检查 |

一个完整的技能创建流程示例：

```
~/.claude/skills/
  my-code-review/
    SKILL.md              ← 技能定义文件（必须）
    review-checklist.md   ← 附属文件，模型可按需读取
    examples/
      good-pattern.md     ← 良好模式示例
      bad-pattern.md      ← 反模式示例
```

### 11.2.2 参数替换机制

技能的 prompt 内容支持灵活的参数替换：

**位置参数**：`$ARGUMENTS` 替换为完整参数字符串；`$ARGUMENTS[0]`、`$ARGUMENTS[1]` 替换为索引参数；`$0`、`$1` 是其简写形式。

**命名参数**：当 frontmatter 定义了 `arguments: foo bar` 时，`$foo` 和 `$bar` 分别映射到对应位置的用户输入值。

替换逻辑按顺序执行：先替换命名参数，再替换索引参数，然后替换完整参数，最后若无占位符则追加参数文本。

```
参数替换执行顺序：

  输入：/my-skill hello world

  Step 1: 命名参数替换
    arguments: "greeting name"
    $greeting → "hello"
    $name → "world"

  Step 2: 索引参数替换
    $1 → "hello"（$0 是技能名本身）
    $2 → "world"
    $ARGUMENTS[0] → "hello"
    $ARGUMENTS[1] → "world"

  Step 3: 完整参数替换
    $ARGUMENTS → "hello world"

  Step 4: 无占位符追加
    如果 prompt 中没有使用任何 $ 占位符
    → 将参数文本追加到 prompt 末尾
```

此外，技能正文还支持 Shell 命令内联执行和环境变量替换。在 prompt 生成器中，除了参数替换，还会：

1. 添加技能根目录前缀：`Base directory for this skill: ${baseDir}`
2. 替换 `${CLAUDE_SKILL_DIR}` 为技能目录的绝对路径
3. 替换 `${CLAUDE_SESSION_ID}` 为当前会话 ID
4. 对非 MCP 技能执行 Shell 命令内联展开（安全考虑：MCP 技能来自远端，不执行其内嵌 Shell 命令）

> **安全边界：为什么 MCP 技能不能执行 Shell 命令？**
>
> MCP 技能来自外部服务器，而 Shell 命令可以执行任意系统操作。如果允许 MCP 技能中的 Shell 命令内联展开，一个恶意的 MCP 服务器可以在技能 prompt 中注入 `$(rm -rf /)` 这样的命令。因此，系统在 `LoadedFrom` 类型为 `mcp` 时跳过 Shell 命令展开，这是一个关键的安全边界。
>
> 这是一个经典的"信任边界"问题——本地技能文件由用户创建和管理（可信），而 MCP 技能来自网络（不可信）。安全策略应该根据来源的可信程度而有所不同。

### 11.2.3 LoadedFrom 类型

技能的来源通过 `LoadedFrom` 类型标识，包含六种来源：旧版命令目录（commands_DEPRECATED）、新版技能目录（skills）、插件提供（plugin）、企业管理策略（managed）、内置编译（bundled）和 MCP 服务器提供（mcp）。

这个类型不仅用于追踪来源，还直接影响安全策略。例如，来自 MCP 的技能不会执行 Shell 命令内联，因为 MCP 技能来自不可信的远端服务器。

```mermaid
graph LR
    subgraph 来源["LoadedFrom 类型与安全策略映射"]
        direction TB
        B["bundled — 信任等级：最高<br/>Shell 内联：允许 / 文件提取：安全提取"]
        M["managed — 信任等级：高<br/>Shell 内联：允许 / 文件提取：安全提取"]
        S["skills — 信任等级：中<br/>Shell 内联：允许 / 文件提取：安全提取"]
        P["plugin — 信任等级：中<br/>Shell 内联：允许 / 文件提取：安全提取"]
        CD["commands_DEPRECATED — 信任等级：中<br/>Shell 内联：允许 / 文件提取：安全提取"]
        MCP["mcp — 信任等级：低<br/>Shell 内联：禁止 / 文件提取：N/A"]
    end

    B --> M --> S --> P --> CD --> MCP

    NOTE["安全策略根据来源信任等级递减"]

    style B fill:#2ecc71,stroke:#27ae60,color:#fff
    style M fill:#27ae60,stroke:#1e8449,color:#fff
    style S fill:#f39c12,stroke:#d68910,color:#fff
    style P fill:#f39c12,stroke:#d68910,color:#fff
    style CD fill:#e67e22,stroke:#d35400,color:#fff
    style MCP fill:#e74c3c,stroke:#c0392b,color:#fff
    style NOTE fill:#fff3e0,stroke:#f39c12,color:#333
```

---

## 11.3 技能加载路径

### 11.3.1 分层加载策略

`getSkillsPath` 函数清晰地定义了各来源的路径映射，根据来源类型（policySettings、userSettings、projectSettings、plugin）返回对应的技能目录路径。

各层级说明：

**管理策略级（Managed / Policy）**：由企业管理员通过集中配置下发。路径为 `{managedPath}/.claude/skills/`。可通过 `CLAUDE_CODE_DISABLE_POLICY_SKILLS` 环境变量禁用。

**用户级（User）**：存储在用户主目录 `~/.claude/skills/`。跨所有项目可用。需要 `userSettings` 来源启用且不受 `pluginOnly` 策略限制。

**项目级（Project）**：存储在项目目录 `.claude/skills/`。仅在该项目上下文中生效。支持嵌套目录发现（见下节）。

**额外目录（Additional）**：通过 `--add-dir` CLI 参数指定的额外目录中的 `.claude/skills/` 子目录。

**旧版命令目录（Legacy Commands）**：`.claude/commands/` 目录，兼容旧格式。单文件 `.md` 和目录格式 `SKILL.md` 均支持。该来源标记为 `commands_DEPRECATED`。

```mermaid
graph TD
    A["管理策略级 (Managed)<br/>路径: {managedPath}/.claude/skills/<br/>企业标准，最高优先级"]
    B["项目级 (Project)<br/>路径: .claude/skills/<br/>项目特定技能"]
    C["用户级 (User)<br/>路径: ~/.claude/skills/<br/>个人偏好技能"]
    D["插件级 (Plugin)<br/>路径: {plugin-dir}/commands/<br/>插件提供的技能"]
    E["内置级 (Bundled)<br/>编译进二进制文件<br/>开箱即用的核心技能"]

    A -->|"覆盖"| B
    B -->|"覆盖"| C
    C -->|"覆盖"| D
    D -->|"覆盖"| E

    style A fill:#e74c3c,stroke:#c0392b,color:#fff
    style B fill:#f39c12,stroke:#d68910,color:#fff
    style C fill:#3498db,stroke:#2471a3,color:#fff
    style D fill:#9b59b6,stroke:#7d3c98,color:#fff
    style E fill:#bdc3c7,stroke:#7f8c8d,color:#333
```

### 11.3.2 动态技能发现

除了启动时的静态加载，Claude Code 还支持在会话运行时动态发现技能。当模型通过 Read、Write、Edit 等工具访问文件时，系统会沿文件路径向上查找 `.claude/skills/` 目录。

核心函数 `discoverSkillDirsForPaths` 实现了动态技能发现机制：

```mermaid
flowchart TD
    A["文件操作触发: Read(src/sub/deep/file.ts)"]
    B["从 src/sub/deep/ 开始向上遍历至 cwd"]
    C["检查每层是否存在 .claude/skills/ 目录"]
    D["跳过 gitignored 目录"]
    E["收集新发现的目录（按深度排序，最深的优先）"]
    F["addSkillDirectories() 加载并合并到 dynamicSkills Map"]

    A --> B --> C --> D --> E --> F

    style A fill:#3498db,stroke:#2471a3,color:#fff
    style F fill:#2ecc71,stroke:#27ae60,color:#fff
```

关键的安全设计：被 `.gitignore` 忽略的目录中的技能会被自动跳过，防止 `node_modules/pkg/.claude/skills/` 这类路径被静默加载。

> **反模式警告：不要在 node_modules 中放置技能**
>
> 虽然 `.gitignore` 过滤提供了安全防线，但依赖它作为唯一的安全措施是不够的。如果一个 npm 包在 `.claude/skills/` 中放置了技能文件，而该目录碰巧不在 `.gitignore` 中，这些技能会被自动加载。建议在项目中明确将 `**/.claude/skills/` 添加到 `.gitignore`，只保留根目录的 `.claude/skills/`。

> **实际使用场景：Monorepo 中的项目特定技能**
>
> 在 Monorepo 结构中，每个子项目可能有自己的技能需求。动态技能发现机制完美地解决了这个问题：
>
> ```
> my-monorepo/
> ├── packages/
> │   ├── frontend/
> │   │   └── .claude/skills/
> │   │       └── component-gen/
> │   │           └── SKILL.md    ← 前端组件生成技能
> │   ├── backend/
> │   │   └── .claude/skills/
> │   │       └── api-gen/
> │   │           └── SKILL.md    ← API 端点生成技能
> │   └── shared/
> │       └── .claude/skills/
> │           └── type-gen/
> │               └── SKILL.md    ← 共享类型生成技能
> ```
>
> 当模型操作 `packages/frontend/` 下的文件时，会自动发现前端的组件生成技能；操作 `packages/backend/` 下的文件时，会自动发现 API 生成技能。这种"按位置激活"的模式极大地减少了技能选择的心智负担。

### 11.3.3 条件技能

带有 `paths` frontmatter 的技能不会立即激活，而是存入 `conditionalSkills` Map。当模型操作的文件路径与 `paths` 模式匹配时，该技能才会被激活。

匹配使用 gitignore 风格的模式，通过 `ignore` 库实现。当文件路径与条件技能的 paths 模式匹配时，该技能会被激活并存入动态技能集合。已激活的条件技能名称会被永久记录，即使后续清空缓存也不会重新变为条件状态。

```mermaid
flowchart TD
    A["启动时加载技能列表"] --> B{"有 paths 字段?"}
    B -->|"No"| C["立即可用"]
    B -->|"Yes"| D["存入 conditionalSkills Map"]
    D --> E["模型操作文件<br/>Read/Write/Edit"]
    E --> F{"文件路径匹配 paths 模式？"}
    F -->|"No"| G["不激活"]
    F -->|"Yes"| H["激活技能<br/>存入 dynamicSkills + 永久标记已激活"]
```

> **为什么已激活的条件技能需要永久标记？**
>
> 假设你定义了一个条件技能 `paths: ["src/**/*.ts"]`，当模型第一次读取 `src/foo.ts` 时被激活。如果后来因为缓存清理导致它被移回条件状态，那么除非模型再次读取匹配的文件，否则这个技能就"消失"了。但此时模型可能正在基于这个技能的指导执行任务，技能的突然消失会导致行为不一致。永久标记确保一旦激活，技能在整个会话期间都保持可用。

---

## 11.4 插件系统

### 11.4.1 插件目录结构

插件是比技能更高层级的扩展单元。一个插件可以包含技能、agents、hooks 等多种组件。其目录结构通常包含：

```
my-plugin/
├── plugin.json           ← 插件清单（可选）
├── commands/             ← 自定义 slash 命令
│   ├── build.md
│   └── deploy.md
├── agents/               ← 自定义 AI agents
│   └── test-runner.md
└── hooks/
    └── hooks.json        ← Hook 配置
```

插件清单 `plugin.json` 包含插件的元信息：

| 字段 | 说明 | 用途 |
|------|------|------|
| name | 插件名称 | 显示和引用 |
| version | 版本号 | 兼容性检查 |
| description | 描述文本 | 用户识别 |
| commands | 命令目录路径 | 发现自定义命令 |
| agents | 智能体目录路径 | 发现自定义智能体 |
| hooks | Hook 配置路径 | 生命周期钩子 |

插件的发现来源按优先级排列：

1. **Marketplace 插件**：通过 `plugin@marketplace` 格式在 settings 中配置
2. **Session-only 插件**：通过 `--plugin-dir` CLI 参数或 SDK plugins 选项加载

> **交叉引用：** 插件提供的智能体（agents/）使用与第9章中自定义智能体相同的 Markdown 格式。区别在于来源——自定义智能体来自 `.claude/agents/` 目录，插件智能体来自插件的 `agents/` 目录，两者的优先级不同。

### 11.4.2 缓存优先加载策略

插件加载采用缓存优先策略以避免重复的文件系统 I/O。缓存优先函数优先从缓存返回已加载的插件数据，仅在缓存为空时才执行实际的磁盘读取。

整个加载流程：

```mermaid
flowchart TD
    A["收集所有插件来源<br/>marketplace / session-only / builtin"] --> B["对每个插件目录：<br/>检查缓存"]
    B -->|"命中"| C["直接返回"]
    B -->|"未命中"| D["解析 plugin.json 清单"]
    D --> E["加载 commands/ 目录中的技能"]
    D --> F["加载 agents/ 目录中的智能体"]
    D --> G["验证 hooks 配置并 解析变量"]
    D --> H["收集错误（不中断加载）"]
    I["存入缓存"]
    I --> J["返回 PluginLoadResult<br/>plugins: Plugin[]<br/>errors: LoadError[]"]

    style A fill:#3498db,stroke:#2471a3,color:#fff
    style C fill:#f39c12,stroke:#d68910,color:#fff
    style D fill:#2ecc71,stroke:#27ae60,color:#fff
    style I fill:#1abc9c,stroke:#16a085,color:#fff
    style J fill:#e67e22,stroke:#d35400,color:#fff
```

> **设计洞察：为什么"收集错误而不中断"？**
>
> 插件加载采用"尽力而为"策略——即使某个插件的一个组件加载失败（比如一个命令的 Markdown 格式错误），其他组件仍然可以正常加载。这避免了"一个坏苹果毁了整桶"的问题。错误被收集到 `PluginLoadResult.errors` 中，可以在后续进行诊断和修复。
>
> 这种容错设计在插件系统中非常重要。想象一下，如果因为一个第三方插件的格式错误导致整个 Claude Code 无法启动，用户体验将是灾难性的。

### 11.4.3 MCP 技能的间接注册

MCP 服务器也可以提供技能。为了避免循环依赖，MCP 技能的构建函数通过一个中间注册模块间接获取。技能加载模块初始化时注册构建函数，MCP 技能模块需要时再获取。这是一个经典的"发布-查找"（publish-lookup）模式，在依赖图中插入一个叶子节点来打破循环。不使用动态 import 的原因是：在打包的二进制文件中，非字面量的动态 import 会因路径解析失败而报错。

```
依赖关系与循环打破：

  正常依赖链（会产生循环）：
  ┌──────────┐     ┌──────────┐     ┌──────────┐
  │  skills   │────▶│   mcp    │────▶│  skills   │  ← 循环！
  │  module   │◀────│  module  │◀────│  module   │
  └──────────┘     └──────────┘     └──────────┘

  使用中间注册模块打破循环：
  ┌──────────┐     ┌──────────┐     ┌──────────┐
  │  skills   │────▶│ registry │◀────│   mcp    │
  │  module   │     │  module  │     │  module   │
  └──────────┘     └──────────┘     └──────────┘
       │                                  │
       │  publish(buildFn)                │  lookup(buildFn)
       └──────────┐         ┌────────────┘
                  ▼         ▼
            ┌──────────────────┐
            │  中间注册模块      │  ← 依赖图的叶子节点
            │  (无自身依赖)      │
            └──────────────────┘
```

> **为什么不使用动态 import？**
>
> Claude Code 的二进制文件是通过打包工具（如 esbuild）将所有 TypeScript 模块编译合并而成的。动态 import 使用字符串变量作为路径时，打包工具无法在编译时确定要包含哪些模块，导致路径解析失败。"发布-查找"模式通过在编译时就确定所有依赖关系，避免了运行时的动态解析问题。

---

## 11.5 创建自定义技能完整教程

本节通过一个完整的案例，展示从零开始创建一个实用技能的全过程。

### 案例：创建一个 API 端点生成技能

**目标：** 创建一个技能，当用户输入 `/gen-api GET users` 时，自动生成完整的 REST API 端点代码，包括路由、控制器、类型定义和测试。

#### Step 1: 创建技能目录

```bash
mkdir -p ~/.claude/skills/gen-api
```

#### Step 2: 编写 SKILL.md

```yaml
---
name: gen-api
description: 生成 REST API 端点的完整代码骨架
when_to_use: 当用户需要创建新的 API 端点或 CRUD 操作时
arguments: method resource
argument-hint: "[GET|POST|PUT|DELETE] [resource-name]"
allowed-tools:
  - Read
  - Write
  - Grep
  - Glob
model: inherit
effort: high
user-invocable: true
---

# API 端点生成器

为资源 $resource 创建 $method 方法的 REST API 实现。

## 上下文收集

首先执行以下调查步骤：

1. 使用 Grep 查找现有的路由定义模式
2. 使用 Read 查看一个已有的路由文件作为参考
3. 使用 Glob 查找类型定义的位置
4. 使用 Grep 查找现有的测试文件结构

## 生成规范

基于调查结果，生成以下文件：

### 1. 路由定义
- 文件位置：参考现有路由文件的模式
- 包含请求验证中间件
- 包含认证/授权检查

### 2. 类型定义
- Request body 类型
- Response 类型
- Query 参数类型

### 3. 控制器逻辑
- 输入验证
- 业务逻辑
- 错误处理
- 响应格式化

### 4. 测试文件
- 正常路径测试
- 边界条件测试
- 错误处理测试

## 注意事项

- 遵循项目中已有的代码风格和模式
- 使用项目中已有的错误处理工具
- 如果项目使用 ORM，使用对应的查询语法
```

#### Step 3: 测试技能

启动 Claude Code 后输入 `/gen-api GET users`，验证：
- 技能是否被正确识别和加载
- 参数替换是否正确（`$method` = "GET"，`$resource` = "users"）
- 生成的代码是否符合项目既有模式

#### Step 4: 迭代优化

根据使用反馈持续优化：
- 如果发现模型经常遗漏某个步骤，在 prompt 中增加更强的指令
- 如果生成的代码风格不一致，在 prompt 中加入更具体的风格要求
- 如果需要支持更多参数，扩展 `arguments` 字段

### 技能组合使用的最佳实践

技能不是孤立使用的——它们可以与其他技能、智能体和工具组合形成强大的工作流。

#### 模式一：技能链

```
技能链示例：API 开发工作流

  /gen-api POST orders     → 生成 API 骨架
       │
       ▼
  /verify                   → 验证生成的代码
       │
       ▼
  /remember "使用 RESTful 路由命名"  → 记录项目约定
```

#### 模式二：条件技能 + 智能体

```
条件技能 + 智能体组合：

  1. 定义条件技能（paths: ["src/api/**/*.ts"]）
     → 只在 API 文件上激活

  2. 自定义智能体引用该技能
     → 智能体在处理 API 任务时自动使用技能

  3. 技能中引用附属文件
     → 技能目录下的模式文件作为参考
```

#### 模式三：技能 + Hook

```yaml
# SKILL.md
---
hooks:
  pre:
    - command: npm run type-check
  post:
    - command: npm run test -- --related
---

# 技能内容
生成代码前先运行类型检查（pre hook），
完成后运行相关测试（post hook）。
```

> **反模式警告：不要创建"万能技能"**
>
> 一个技能应该做一件事并做好。如果你发现一个技能的 prompt 超过了 200 行，考虑将它拆分为多个技能。例如，不要创建一个"全栈开发"技能，而是创建"API 生成"、"前端组件生成"、"测试生成"三个独立的技能。
>
> 原因：技能越大，模型执行时的不确定性越高。小而专注的技能更容易调试、更容易复用、更容易与其他技能组合。

---

## 实战练习

### 练习 1：创建一个自定义项目级技能

在项目根目录创建 `.claude/skills/code-review/SKILL.md`：

```yaml
---
description: 执行代码审查，关注安全性、性能和可维护性
arguments: file_path
allowed-tools:
  - Read
  - Grep
  - Glob
paths:
  - "src/**/*.ts"
  - "src/**/*.tsx"
---

对文件 $file_path 进行全面代码审查。

检查以下方面：
1. 安全漏洞（XSS、注入、敏感数据泄露）
2. 性能问题（不必要的循环、内存泄漏风险）
3. 可维护性（命名、复杂度、重复代码）
4. 错误处理的完整性

输出结构化的审查报告。
```

**扩展挑战：** 在技能目录下创建一个 `review-checklist.md` 附属文件，包含详细的审查检查清单，让技能 prompt 引用这个文件。

### 练习 2：创建一个带命名参数的用户级技能

在 `~/.claude/skills/generate-api/SKILL.md` 创建技能：

```yaml
---
description: 生成 REST API 端点的样板代码
arguments: method resource_name
allowed-tools:
  - Write
  - Read
---

为资源 '$resource_name' 创建 $method 方法的 REST API 实现。

生成以下文件：
1. 路由定义
2. 请求/响应类型
3. 控制器逻辑
4. 基本测试
```

使用：`/generate-api POST user`

**思考题：** 如果用户输入 `/generate-api` 而不带任何参数会发生什么？如何改进技能定义来处理参数缺失的情况？

### 练习 3：探索技能加载的调试日志

运行 `CLAUDE_CODE_DEBUG=1 claude` 启动会话，观察技能加载的调试输出，了解当前环境中加载了哪些来源的技能。

**检查清单：**
- 确认内置技能是否全部加载
- 检查是否有旧版命令目录的兼容加载
- 查看条件技能的激活情况
- 验证去重策略是否正常工作

### 练习 4：创建一个带生命周期钩子的技能

创建一个技能，在执行前自动运行 lint 检查，在执行后自动运行相关测试。思考：
- pre hook 失败时应该如何处理？
- post hook 的输出如何影响技能结果？
- 如何在 hook 中引用技能的参数？

### 练习 5：设计一个条件技能系统

为一个 React + TypeScript 项目设计以下条件技能：

1. 当操作 `src/components/` 下的文件时，激活"组件生成"技能
2. 当操作 `src/hooks/` 下的文件时，激活"Hook 生成"技能
3. 当操作 `src/api/` 下的文件时，激活"API 集成"技能
4. 当操作 `*.test.*` 文件时，激活"测试辅助"技能

思考：这些技能之间是否有重叠？如何避免技能之间的冲突？

---

## 关键要点

1. **分层架构**：技能来源从 managed -> user -> project -> plugin -> bundled 逐层覆盖，企业策略具有最高优先权。每一层都有独立的路径和安全策略。

2. **安全优先**：MCP 技能（`loadedFrom === 'mcp'`）不执行 Shell 命令内联；内置技能的文件提取使用 `O_NOFOLLOW | O_EXCL` 防止符号链接攻击；gitignored 目录中的技能被自动跳过。安全策略根据来源信任等级递减。

3. **惰性加载**：内置技能的引用文件在首次调用时才提取到磁盘；条件技能在匹配文件模式时才激活；动态技能在文件操作触发路径扫描时才被发现。这种惰性策略优化了启动性能和内存使用。

4. **去重策略**：使用 `realpath` 解析符号链接得到规范路径，按首次出现保留，避免重复加载。这解决了符号链接和重叠父目录导致的问题。

5. **循环依赖解决**：通过中间注册模块的"发布-查找"模式，在依赖图中插入叶子节点打破循环。选择这种模式而非动态 import 是因为二进制打包的限制。

6. **参数系统的灵活性**：支持 `$ARGUMENTS`（完整参数）、`$ARGUMENTS[N]`/`$N`（位置参数）、命名参数（`$foo`）三级替换，加上 `${CLAUDE_SKILL_DIR}` 和 `${CLAUDE_SESSION_ID}` 环境变量。替换顺序确保了参数名不会与位置索引冲突。

7. **插件作为扩展单元**：插件比技能更高层级，可以包含技能、智能体和钩子。缓存优先加载和容错错误收集确保了插件的可靠性和性能。

8. **技能组合模式**：技能可以与其他技能、智能体和 Hook 组合使用。保持技能小而专注，通过组合实现复杂工作流。