---
title: "Skills 技能系统"
description: "Prompt 即能力。Skill 不是代码，而是高质量的 Prompt + 权限配置的声明式封装。理解加载链路、两条执行路径和条件激活机制。"
keywords: ["Skills", "技能加载", "Prompt 即能力", "条件激活"]
---

## 核心洞见：Prompt 即能力

Skill 的核心设计哲学：**复杂任务的关键不在代码逻辑，而在 Prompt 质量**。

一个代码审查 Skill 不需要审查引擎，只需告诉 AI "审查什么、按什么顺序、输出什么格式"。Skill 把这种"经验"封装为可复用的 Markdown 文件。

| | Tool | Skill |
|---|---|---|
| 粒度 | 单个原子操作（读文件、执行命令） | 完整工作流（代码审查、创建 PR） |
| 本质 | TypeScript 执行逻辑 | Prompt + 权限配置的声明式封装 |
| 创建 | 需要写代码 | 写 Markdown 文件即可 |

## Skill 的来源

| 来源 | 路径 | 特点 |
|------|------|------|
| **内置命令** | 硬编码 | `/commit`、`/compact` 等 70+ 命令 |
| **Bundled Skills** | 编译时打包 | 延迟解压，享有不可截断特权 |
| **磁盘 Skills** | `.claude/skills/` | 最重要的来源，支持多层级 |
| **MCP Skills** | MCP Server 提供 | 远程内容，禁止内联 shell 命令 |
| **Legacy Commands** | `.claude/commands/` | 向后兼容旧格式 |

### 多层级磁盘加载

```
管理策略: $MANAGED_DIR/.claude/skills/     （企业管理）
用户全局: ~/.claude/skills/                 （个人偏好）
项目级:   .claude/skills/                   （团队共享）
附加目录: --add-dir 指定的路径              （额外来源）
```

每个 Skill 是一个 `skill-name/SKILL.md` 目录。加载时解析 YAML frontmatter 提取配置。

### 安全边界

MCP Skills 的 Prompt 内容**禁止执行内联 shell 命令**。因为远程内容不可信——如果允许，恶意 MCP Server 就可以通过 Skill 注入执行任意命令。

## Frontmatter 配置

一个 SKILL.md 的完整配置：

```yaml
---
name: code-review
description: 系统性代码审查
when_to_use: "用户说审查代码、找 bug"
allowed-tools:
  - Read
  - Grep
  - Glob
context: fork              # 执行模式：inline | fork
model: opus                # 模型覆盖
effort: high               # 努力级别
paths:                     # 条件激活
  - "src/**/*.ts"
---
```

- `when_to_use` — AI 根据此描述自动匹配用户意图
- `allowed-tools` — 限制 Skill 可用的工具白名单
- `context` — 控制执行模式（见下文）
- `paths` — 条件激活，只在操作匹配文件时出现

## 两条执行路径

### Inline 模式（默认）

Skill 的 Prompt 内容被注入为用户消息，在主对话流中继续执行。AI "穿上"了 Skill 的经验，但仍在同一个对话中。

**优点**：共享主对话的完整上下文，可以引用之前的讨论。
**缺点**：Skill 的中间过程会污染主对话的上下文。

### Fork 模式（`context: fork`）

Skill 在独立子 Agent 中执行，拥有独立的 token 预算和工具权限。执行完成后只返回最终结果，中间过程不保留。

**优点**：不污染主对话，适合长时间运行的任务。
**缺点**：子 Agent 看不到主对话的完整上下文。

**设计考量**：大多数 Skill 使用 inline 模式就够了——它们需要主对话的上下文。Fork 模式适合"重型"任务（如完整的代码审查），这些任务的中间步骤很多，留在主对话中会浪费大量 token。

## 权限模型

Skill 有五层权限检查：

```
Deny 规则 → 远程 Skill 自动放行 → Allow 规则 → Safe Properties 白名单 → Ask 用户确认
```

**Safe Properties 白名单**是一个包含 30 个安全属性名的列表。任何不在白名单中的属性都会触发权限请求。这是**正向安全**设计——未来新增的属性默认需要权限，而非默认允许。

## Prompt 预算

Skill 列表注入 System Prompt 时有严格预算（约上下文窗口的 1%）：
1. 优先保留 bundled Skills 的完整描述
2. 非 bundled Skills 按剩余预算均分
3. 预算不足时只保留名称

**设计考量**：Skill 列表只是让 AI "知道有什么可用"。完整的 Skill Prompt 在 AI 选择后才加载，不需要全部塞进 System Prompt。

## 条件激活

带有 `paths` 模式的 Skill 在加载时不会立即可用。只有当被操作的文件路径匹配模式时，该 Skill 才被激活。

一个只在 `*.test.ts` 上激活的测试 Skill，平时完全不可见，只有当 AI 读取或编辑测试文件时才会出现。

**设计洞察**：这解决了"Skill 泛滥"问题——项目可能定义了几十个 Skill，但一次对话通常只需要其中几个。条件激活让 Skill 按需出现，而不是全部堆在 AI 面前让它选择。

## 使用频率排名

Skill 的排序使用指数衰减算法：一周前的使用权重减半。这确保常用的 Skill 排在前面，但偶尔用的老 Skill 也不会完全沉底。

## 接下来

- **Hooks** — 理解 Skill 中可以使用的 Hook 机制
- **MCP 配置** — 理解 MCP Skills 的来源
- **自定义 Agent** — 理解 Skill 中指定的 Agent 定义