mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-18 14:25:51 +00:00
2b1953ce8a
移除 TypeScript 代码、源码路径和 16 个 frontmatter 字段枚举， 聚焦 Prompt 即能力的核心哲学、inline vs fork 的上下文权衡、 Safe Properties 正向安全设计和条件激活的按需发现。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
124 lines
5.1 KiB
Plaintext
124 lines
5.1 KiB
Plaintext
---
|
||
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 定义
|