mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-15 12:53:31 +08:00
072e5bcc48
Add GitHub-compatible slugify (github-slugger algorithm) to VitePress config so heading anchor IDs are consistent across both platforms. Update all inline anchor links in 22 doc files accordingly.
394 lines
12 KiB
Markdown
394 lines
12 KiB
Markdown
# Claude Code Skills 系统 — 使用指南
|
||
|
||
> Skills 是 Claude Code 的扩展能力引擎，让你用 Markdown 文件定义专属的自动化工作流。
|
||
|
||
<p align="center">
|
||
<a href="#一什么是-skills">Skills 是什么</a> · <a href="#二六种-skill-来源">六种来源</a> · <a href="#三skill-定义格式">定义格式</a> · <a href="#四调用方式">调用方式</a> · <a href="#五执行上下文">执行上下文</a> · <a href="#六条件激活">条件激活</a> · <a href="#七权限控制">权限控制</a> · <a href="#八快速参考">快速参考</a>
|
||
</p>
|
||
|
||
|
||
|
||
---
|
||
|
||
## 一、什么是 Skills？
|
||
|
||
Skills 是 Claude Code 的**可扩展能力插件系统**。每个 Skill 是一个 Markdown 文件（含 YAML frontmatter），定义了一段专门的提示词和行为配置，让 Claude 在特定场景下执行专业化的工作流。
|
||
|
||
核心能力：
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| 专业化工作流 | 定义代码审查、TDD、调试等标准流程 |
|
||
| 工具权限控制 | 限制 Skill 只能使用指定的工具 |
|
||
| 模型切换 | 为不同 Skill 指定不同的模型 |
|
||
| 执行隔离 | Fork 模式在子代理中独立运行 |
|
||
| 条件激活 | 只在操作特定文件时才激活 |
|
||
| Hook 注入 | Skill 调用时自动注册生命周期钩子 |
|
||
|
||
---
|
||
|
||
## 二、六种 Skill 来源
|
||
|
||
|
||
|
||
Claude Code 从 6 个不同来源加载 Skills，按优先级从高到低：
|
||
|
||
### 1. Bundled（内置 Skills）
|
||
|
||
编译到 CLI 二进制中，所有用户可用。以 TypeScript 定义，通过 `registerBundledSkill()` 注册。
|
||
|
||
**当前内置 Skills：**
|
||
|
||
| Skill | 说明 | 特殊条件 |
|
||
|-------|------|----------|
|
||
| `/verify` | 验证代码变更 | — |
|
||
| `/debug` | 调试助手 | — |
|
||
| `/simplify` | 代码简化审查 | — |
|
||
| `/remember` | 记忆管理 | 需启用 auto-memory |
|
||
| `/batch` | 批量处理 | — |
|
||
| `/stuck` | 卡住时求助 | — |
|
||
| `/skillify` | 创建新 Skill | — |
|
||
| `/keybindings` | 自定义快捷键 | — |
|
||
| `/loop` | 定时循环任务 | AGENT_TRIGGERS 特性门控 |
|
||
| `/schedule` | 远程代理调度 | AGENT_TRIGGERS_REMOTE 特性门控 |
|
||
| `/claude-api` | Claude API 集成 | BUILDING_CLAUDE_APPS 特性门控 |
|
||
| `/dream` | 自动记忆整理 | KAIROS 特性门控 |
|
||
|
||
### 2. Managed（策略管理 Skills）
|
||
|
||
由组织策略控制，存放在 `<managed-path>/.claude/skills/`，适用于企业部署。
|
||
|
||
### 3. User（用户 Skills）
|
||
|
||
用户个人定义，存放在 `~/.claude/skills/`。
|
||
|
||
```
|
||
~/.claude/skills/
|
||
├── my-review/
|
||
│ └── SKILL.md ← 主 Skill 文件
|
||
├── deploy-check/
|
||
│ └── SKILL.md
|
||
└── ...
|
||
```
|
||
|
||
### 4. Project（项目 Skills）
|
||
|
||
项目级别定义，存放在 `.claude/skills/`，可提交到版本控制。
|
||
|
||
```
|
||
your-project/
|
||
└── .claude/
|
||
└── skills/
|
||
├── lint-fix/
|
||
│ └── SKILL.md
|
||
└── test-runner/
|
||
└── SKILL.md
|
||
```
|
||
|
||
### 5. Plugin（插件 Skills）
|
||
|
||
由已安装的插件提供。插件通过 manifest 的 `skillsPath` / `skillsPaths` 声明 Skills 目录。
|
||
|
||
命名格式：`{pluginName}:{skillName}`
|
||
|
||
```
|
||
例如：superpowers:code-reviewer
|
||
superpowers:brainstorming
|
||
```
|
||
|
||
### 6. MCP（MCP 服务器 Skills）
|
||
|
||
由连接的 MCP 服务器提供，命名格式：`mcp__server-name__prompt-name`。
|
||
|
||
**安全限制**：MCP Skills 为远程不受信来源，**禁止执行** `!`...`` 内联 shell 命令。
|
||
|
||
---
|
||
|
||
## 三、Skill 定义格式
|
||
|
||
### 目录结构
|
||
|
||
每个 Skill 是一个目录，包含一个 `SKILL.md` 文件：
|
||
|
||
```
|
||
skill-name/
|
||
└── SKILL.md ← 文件名必须是 SKILL.md（大小写不敏感）
|
||
```
|
||
|
||
### Frontmatter 完整字段
|
||
|
||
```yaml
|
||
---
|
||
name: 我的技能 # 显示名称（可选，默认用目录名）
|
||
description: 这个技能做什么 # 描述（必填，缺少时自动从内容提取）
|
||
when_to_use: 什么时候该用这个技能 # 使用场景说明（可选）
|
||
version: 1.0.0 # 版本号（可选）
|
||
|
||
# ── 调用控制 ──
|
||
user-invocable: true # 用户能否通过 /skill-name 调用（默认 true）
|
||
disable-model-invocation: false # 禁止模型通过 Skill tool 调用（可选）
|
||
argument-hint: "<文件路径>" # 参数提示（可选）
|
||
|
||
# ── 执行配置 ──
|
||
context: inline # 执行上下文：inline（默认）或 fork（子代理）
|
||
agent: general-purpose # fork 时使用的代理类型（可选）
|
||
model: sonnet # 模型覆盖：haiku / sonnet / opus / inherit（可选）
|
||
effort: high # 思考力度：low / medium / high / max（可选）
|
||
allowed-tools: "Bash, Read" # 允许使用的工具（逗号分隔或 YAML 列表）
|
||
shell: bash # Shell 类型：bash（默认）或 powershell
|
||
|
||
# ── 条件激活 ──
|
||
paths: "src/**/*.ts, test/**/*.ts" # Glob 模式，只在匹配文件被操作时激活
|
||
|
||
# ── 生命周期 Hook ──
|
||
hooks:
|
||
PreToolUse:
|
||
- matcher: "Bash"
|
||
hooks:
|
||
- command: "echo 'Before bash'"
|
||
once: true # 仅执行一次
|
||
---
|
||
|
||
# Skill 正文内容
|
||
|
||
这里是 Markdown 格式的提示词，Claude 调用此 Skill 时会看到这些内容。
|
||
|
||
支持的特殊语法：
|
||
- `${CLAUDE_SKILL_DIR}` — 展开为 Skill 所在目录
|
||
- `${CLAUDE_SESSION_ID}` — 展开为当前会话 ID
|
||
- `$ARGUMENTS` / `${ARG1}` — 参数替换
|
||
- !`shell command` — 内联 Shell 命令执行
|
||
```
|
||
|
||
### Frontmatter 字段速查表
|
||
|
||
| 字段 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `name` | string | 目录名 | 显示名称覆盖 |
|
||
| `description` | string | 自动提取 | Skill 简述 |
|
||
| `when_to_use` | string | — | 使用场景描述 |
|
||
| `user-invocable` | boolean | true | 用户能否输入 /name 调用 |
|
||
| `disable-model-invocation` | boolean | false | 禁止模型调用 |
|
||
| `context` | `inline` \| `fork` | inline | 执行上下文 |
|
||
| `agent` | string | general-purpose | fork 时代理类型 |
|
||
| `model` | string | 继承 | 模型覆盖（haiku/sonnet/opus） |
|
||
| `effort` | string \| int | — | 思考力度 |
|
||
| `allowed-tools` | string \| list | 全部 | 允许工具白名单 |
|
||
| `paths` | string \| list | — | 条件激活 Glob 模式 |
|
||
| `shell` | `bash` \| `powershell` | bash | Shell 命令类型 |
|
||
| `hooks` | object | — | 生命周期 Hook 配置 |
|
||
| `argument-hint` | string | — | 参数提示文本 |
|
||
| `version` | string | — | 版本号 |
|
||
|
||
---
|
||
|
||
## 四、调用方式
|
||
|
||
|
||
|
||
### 方式一：用户斜杠命令
|
||
|
||
直接在终端输入 `/skill-name`：
|
||
|
||
```
|
||
> /commit
|
||
> /review-pr 123
|
||
> /verify
|
||
```
|
||
|
||
**前提**：Skill 的 `user-invocable` 必须为 `true`。
|
||
|
||
### 方式二：模型自动调用
|
||
|
||
Claude 在对话中识别到合适的 Skill 时，通过 SkillTool 自动调用：
|
||
|
||
```
|
||
用户：帮我审查一下这段代码
|
||
Claude：[通过 SkillTool 调用 superpowers:code-reviewer]
|
||
```
|
||
|
||
**前提**：Skill 的 `disable-model-invocation` 不能为 `true`。
|
||
|
||
### 方式三：嵌套调用
|
||
|
||
一个 Skill 执行过程中可以触发另一个 Skill：
|
||
|
||
```
|
||
/verify → 内部调用 → /simplify
|
||
```
|
||
|
||
遥测中通过 `invocation_trigger: 'nested-skill'` 追踪。
|
||
|
||
### 调用优先级
|
||
|
||
当同名 Skill 存在于多个来源时，按以下顺序解析（先匹配先用）：
|
||
|
||
```
|
||
1. Bundled（内置） ← 最高优先级
|
||
2. Built-in Plugin（内置插件）
|
||
3. Skill Dirs（用户/项目目录）
|
||
4. Workflow Commands
|
||
5. Plugin Commands（插件命令）
|
||
6. Plugin Skills（插件技能）
|
||
7. Built-in Commands（内建命令） ← 最低优先级
|
||
```
|
||
|
||
---
|
||
|
||
## 五、执行上下文
|
||
|
||
### Inline 模式（默认）
|
||
|
||
Skill 内容**展开到当前对话**中，Claude 直接看到提示词并在同一上下文中执行。
|
||
|
||
```yaml
|
||
context: inline # 默认值，可省略
|
||
```
|
||
|
||
**特点：**
|
||
- 共享父对话的 token 预算
|
||
- 可以访问对话历史上下文
|
||
- `allowedTools` 限制当前轮次可用工具
|
||
- `model` 覆盖当前轮次使用的模型
|
||
|
||
### Fork 模式（子代理）
|
||
|
||
Skill 在**隔离的子代理**中运行，拥有独立的 token 预算和上下文。
|
||
|
||
```yaml
|
||
context: fork
|
||
agent: general-purpose # 可选，指定代理类型
|
||
```
|
||
|
||
**特点：**
|
||
- 独立的 token 预算，不消耗父对话额度
|
||
- 隔离的对话上下文
|
||
- 可指定不同的 agent 类型（如 `Bash`、`general-purpose`）
|
||
- 执行完成后提取结果返回父对话
|
||
- 支持进度汇报（`onProgress` 回调）
|
||
|
||
### 两种模式对比
|
||
|
||
| 特性 | Inline | Fork |
|
||
|------|--------|------|
|
||
| Token 预算 | 共享父对话 | 独立预算 |
|
||
| 上下文访问 | 完整对话历史 | 仅 Skill 提示词 |
|
||
| 结果返回 | 直接在对话中 | 提取文本嵌入 tool_result |
|
||
| 适用场景 | 简短指导、扩展上下文 | 长任务、独立运算 |
|
||
| 工具限制 | contextModifier 修改 | modifiedGetAppState |
|
||
|
||
---
|
||
|
||
## 六、条件激活
|
||
|
||
Skill 可以通过 `paths` frontmatter 实现**按需激活**，只在操作匹配文件时才对模型可见。
|
||
|
||
### 配置方式
|
||
|
||
```yaml
|
||
---
|
||
name: TypeScript 修复
|
||
description: 修复 TypeScript 类型错误
|
||
paths: "src/**/*.ts, test/**/*.ts"
|
||
---
|
||
```
|
||
|
||
### 工作原理
|
||
|
||
```
|
||
1. 启动时加载所有 Skill
|
||
2. 带 paths 的 Skill 存入 conditionalSkills Map（不暴露给模型）
|
||
3. 当用户操作文件时（Read/Write/Edit）
|
||
4. activateConditionalSkillsForPaths() 用 ignore 库匹配
|
||
5. 匹配成功 → 移入 dynamicSkills Map → 模型可见
|
||
6. 一旦激活，在会话内持续有效
|
||
```
|
||
|
||
### 动态发现
|
||
|
||
除了条件激活，Skills 还支持**运行时发现**：
|
||
|
||
```
|
||
1. 用户操作某个深层目录中的文件
|
||
2. discoverSkillDirsForPaths() 从文件路径向上遍历
|
||
3. 寻找 .claude/skills/ 目录（不超过 cwd）
|
||
4. 跳过 .gitignore 忽略的目录
|
||
5. 发现新目录 → addSkillDirectories() → 加载并注册
|
||
```
|
||
|
||
---
|
||
|
||
## 七、权限控制
|
||
|
||
### 自动允许
|
||
|
||
如果 Skill 只包含"安全属性"（无 `allowedTools`、无 `hooks`、无 `fork`），将**自动获准**执行，无需用户确认。
|
||
|
||
### 手动确认
|
||
|
||
包含工具限制、Hook 或 fork 执行的 Skill，首次调用时会提示用户：
|
||
|
||
```
|
||
Execute skill: my-custom-skill
|
||
Allow? (y)es / (n)o / (a)lways allow / (d)eny
|
||
```
|
||
|
||
### 权限规则
|
||
|
||
| 规则类型 | 格式 | 说明 |
|
||
|----------|------|------|
|
||
| 精确允许 | `Skill:commit` | 允许执行 commit Skill |
|
||
| 前缀允许 | `Skill:review:*` | 允许所有 review: 前缀的 Skill |
|
||
| 精确拒绝 | `Skill:dangerous` 设为 deny | 拒绝执行 |
|
||
| 前缀拒绝 | `Skill:untrusted:*` 设为 deny | 拒绝所有 untrusted: 前缀 |
|
||
|
||
**处理顺序：** deny 规则 → allow 规则 → 安全属性检查 → 询问用户
|
||
|
||
---
|
||
|
||
## 八、快速参考
|
||
|
||
### 创建一个 Skill
|
||
|
||
```bash
|
||
# 1. 创建目录
|
||
mkdir -p ~/.claude/skills/my-skill
|
||
|
||
# 2. 创建 SKILL.md
|
||
cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'
|
||
---
|
||
name: 我的技能
|
||
description: 一个示例 Skill
|
||
user-invocable: true
|
||
---
|
||
|
||
# 技能内容
|
||
|
||
你好，这是我的自定义 Skill。
|
||
EOF
|
||
```
|
||
|
||
### 常用操作
|
||
|
||
| 操作 | 方法 |
|
||
|------|------|
|
||
| 创建 Skill | `~/.claude/skills/<name>/SKILL.md` |
|
||
| 项目级 Skill | `.claude/skills/<name>/SKILL.md` |
|
||
| 调用 Skill | 终端输入 `/skill-name` |
|
||
| 查看可用 Skills | 终端输入 `/skills` |
|
||
| 用 AI 创建 Skill | `/skillify` |
|
||
| 限制工具 | frontmatter 添加 `allowed-tools` |
|
||
| Fork 执行 | frontmatter 添加 `context: fork` |
|
||
| 条件激活 | frontmatter 添加 `paths: "src/**"` |
|
||
|
||
### Skill 可用性矩阵
|
||
|
||
| 来源 | 用户可调用 | 模型可调用 | 支持 Fork | 支持 Hook |
|
||
|------|-----------|-----------|----------|----------|
|
||
| Bundled | 依定义 | 依定义 | 是 | 是 |
|
||
| Managed | 是 | 是 | 是 | 是 |
|
||
| User | 是（默认） | 是 | 是 | 是 |
|
||
| Project | 是（默认） | 是 | 是 | 是 |
|
||
| Plugin | 依配置 | 依配置 | 是 | 是 |
|
||
| MCP | 依配置 | 依配置 | 是 | 否（安全限制） |
|