Claude Code Skill（技能）完全指南

Claude Code Skill（技能）完全指南

一、什么是 Skill？

Skill（技能） 是 Claude Code 的扩展机制，让你能够自定义 Claude 的行为和能力。简单来说，skill 就像是给 Claude 写的"操作手册"------当你在特定场景下需要 Claude 按照特定方式工作时，skill 就会自动激活。

graph TB
    subgraph no_skill ["没有 Skill"]
        A1[用户提问] --> B1["Claude 通用回答"]
    end

    subgraph with_skill ["有 Skill"]
        A2[用户提问] --> B2["Skill 自动激活"]
        B2 --> C2["按照 Skill 指引回答"]
        C2 --> D2["专业、定制化的结果"]
    end

Skill 的核心作用

作用	说明
扩展能力	让 Claude 掌握特定领域的知识或工作流程
标准化流程	确保每次执行任务都遵循相同的步骤和规范
提高效率	避免重复输入相同的指令和上下文
团队协作	可以将 skill 提交到版本控制，让整个团队共享

二、Skill 的工作原理

Skill 的工作流程可以用下图概括：

sequenceDiagram
    participant U as 用户
    participant CC as Claude Code
    participant S as Skill 文件
    participant C as Claude 模型

    U->>CC: 发起请求（如：/deploy 或问问题）
    CC->>S: 读取 SKILL.md
    S->>CC: 返回指令内容
    CC->>C: 发送用户请求 + Skill 内容
    C->>CC: 按照 Skill 指引生成响应
    CC->>U: 返回结果

Skill 的存放位置

不同的存放位置决定了 skill 的作用范围：

graph TD
    subgraph priority ["优先级（从高到低）"]
        E["Enterprise企业级] --> P[Personal个人级"]
        P --> PR["Project项目级"]
        PR --> PL["Plugin插件级"]
    end

    subgraph paths ["路径"]
        EP["~/.claude/settings.json(managed settings)"]
        PP["~/.claude/skills//SKILL.md"]        PRP[".claude/skills//SKILL.md(项目根目录)"]        PLP["/skills//SKILL.md"]    end    E -.-> EP    P -.-> PP    PR -.-> PRP    PL -.-> PLP

位置	路径	适用范围
Enterprise	托管设置中配置	组织内所有用户
Personal	~/.claude/skills/<name>/SKILL.md	你的所有项目
Project	.claude/skills/<name>/SKILL.md	当前项目
Plugin	<plugin>/skills/<name>/SKILL.md	安装了该插件的项目

三、如何使用 Skill

3.1 内置 Skill（Bundled Skills）

Claude Code 自带了几个实用的内置 skill：

graph LR
    subgraph builtin [内置 Skills]
        A["/simplify代码审查优化"]
        B["/batch批量并行任务"]
        C["/debug调试日志分析"]
        D["/loop循环执行任务"]
        E["/claude-apiAPI 文档加载"]
    end

Skill	用途	示例
/simplify	审查代码质量、复用性和效率	/simplify 或 /simplify focus on memory efficiency
/batch	并行执行大规模代码变更	/batch migrate src/ from Solid to React
/debug	分析当前会话的调试日志	/debug 或 /debug connection timeout issue
/loop	按间隔循环执行提示词	/loop 5m check if the deploy finished
/claude-api	加载 Claude API 参考文档	自动激活（检测到 SDK 导入时）

3.2 调用方式

有两种方式触发 skill：

flowchart TB
    subgraph direct ["方式一：直接调用"]
        A1["/skill-name [参数]"] --> B1["精确控制何时触发"]
    end

    subgraph auto ["方式二：自动激活"]
        A2[用户提问] --> B2{匹配 Skill 描述?}
        B2 -->|是| C2["Skill 自动加载"]
        B2 -->|否| D2["常规回答"]
    end

示例：

# 直接调用
/deploy production
/fix-issue 123
/explain-code src/auth/login.ts

# 自动激活（Claude 根据 description 判断）
"帮我解释这段代码是怎么工作的"  # 可能激活 explain-code skill

四、如何创建自定义 Skill

4.1 基础结构

每个 skill 是一个目录，核心文件是 SKILL.md：

my-skill/
├── SKILL.md           # 必需：主指令文件
├── reference.md       # 可选：详细参考文档
├── examples/          # 可选：示例目录
│   └── sample.md
└── scripts/           # 可选：脚本文件
    └── validate.sh

4.2 SKILL.md 文件格式

---
# === Frontmatter（YAML 配置）===
name: my-skill                    # Skill 名称（用于 /my-skill 调用）
description: 描述何时使用此 skill # Claude 用于判断是否自动激活
argument-hint: [issue-number]     # 参数提示（显示在自动补全中）
disable-model-invocation: true    # 禁止 Claude 自动激活（只能手动调用）
user-invocable: false             # 从菜单隐藏（只能由 Claude 激活）
allowed-tools: Read, Grep          # 限制可用的工具
context: fork                     # 在子代理中运行
agent: Explore                    # 指定子代理类型
---

# === Markdown 内容（指令）===
这里是 Claude 执行此 skill 时需要遵循的指令...

4.3 创建第一个 Skill

让我们创建一个简单的 skill，让 Claude 用可视化和类比的方式解释代码：

# 第一步：创建目录
mkdir -p ~/.claude/skills/explain-code

# 第二步：创建 SKILL.md 文件
# 路径：~/.claude/skills/explain-code/SKILL.md

---
name: explain-code
description: 用可视化和类比的方式解释代码。当用户问"这是怎么工作的"或需要代码解释时使用。
---

解释代码时，请遵循以下格式：

1. **类比开场**：用日常生活中的例子比喻代码的作用
2. **流程图解**：用 ASCII 艺术展示代码结构或流程
3. **逐步讲解**：逐步说明代码在做什么
4. **注意事项**：指出常见的陷阱或误解

保持解释的口语化。对于复杂概念，使用多个类比帮助理解。

# 第三步：测试
# 方式一：直接调用
/explain-code src/auth/login.ts

# 方式二：自动激活（Claude 判断）
"这段代码是怎么工作的？"

4.4 参数传递

Skill 支持接收参数：

---
name: fix-issue
description: 修复 GitHub Issue
disable-model-invocation: true
---

修复 GitHub Issue #$ARGUMENTS，遵循我们的编码规范。

步骤：
1. 阅读 Issue 描述
2. 理解需求
3. 实现修复
4. 编写测试
5. 创建提交

调用方式：/fix-issue 123，$ARGUMENTS 会被替换为 123。

也可以按位置访问参数：

---
name: migrate-component
description: 迁移组件到新框架
---

将 $ARGUMENTS[0] 组件从 $ARGUMENTS[1] 迁移到 $ARGUMENTS[2]。
# 或使用简写：$0, $1, $2

保留所有现有行为和测试。

调用方式：/migrate-component SearchBar React Vue

五、高级用法与最佳实践

5.1 控制激活方式

graph TB
    subgraph config [配置选项]
        A["默认行为"] --> A1["用户可调用Claude 可自动激活"]
        B["disable-model-invocation: true"] --> B1["仅用户可调用防止意外触发"]
        C["user-invocable: false"] --> C1["仅 Claude 可激活后台知识型"]
    end

何时使用哪种配置：

场景	配置	原因
部署流程	disable-model-invocation: true	不希望 Claude 自动触发部署
提交代码	disable-model-invocation: true	需要人工确认时机
遗留系统知识	user-invocable: false	是知识而非可执行命令
代码风格指南	默认	Claude 在写代码时自动应用

5.2 动态上下文注入

使用 ``!`command``` 语法在 skill 执行前运行 shell 命令：

---
name: pr-summary
description: 总结 Pull Request 变更
allowed-tools: Bash(gh *)
---

## PR 上下文
- PR diff: !`gh pr diff`
- PR 评论: !`gh pr view --comments`
- 变更文件: !`gh pr diff --name-only`

## 任务
总结这个 Pull Request...

执行流程：

sequenceDiagram
    participant U as 用户
    participant S as Skill
    participant Sh as Shell
    participant C as Claude

    U->>S: /pr-summary
    S->>Sh: 执行 !`gh pr diff`
    Sh->>S: 返回 PR diff 内容
    S->>Sh: 执行 !`gh pr view --comments`
    Sh->>S: 返回评论内容
    S->>C: 发送完整的 PR 信息
    C->>U: 返回总结

5.3 在子代理中运行

设置 context: fork 让 skill 在隔离的子代理中运行：

---
name: deep-research
description: 深度研究某个主题
context: fork
agent: Explore
---

深度研究 $ARGUMENTS：

1. 使用 Glob 和 Grep 查找相关文件
2. 阅读并分析代码
3. 总结发现，引用具体文件

5.4 最佳实践

graph TD
    A[Skill 最佳实践] --> B[保持简洁]
    A --> C[拆分文件]
    A --> D[明确描述]
    A --> E[合理限制]

    B --> B1["SKILL.md 控制在 500 行以内"]
    C --> C1["详细文档放入单独文件"]
    D --> D1["description 决定何时激活"]
    E --> E1["使用 allowed-tools 限制权限"]

具体建议：

1. 保持 SKILL.md 简洁 - 主文件控制在 500 行以内，详细参考放入独立文件
2. 写好 description - 这是 Claude 判断是否激活 skill 的依据
3. 拆分关注点 - 复杂 skill 可以用多个文件组织
4. 限制工具权限 - 只读 skill 使用 allowed-tools: Read, Grep, Glob
5. 防止意外触发 - 有副作用的操作设置 disable-model-invocation: true

六、实用 Skill 示例

示例 1：代码审查 Skill

# ~/.claude/skills/review-code/SKILL.md

---
name: review-code
description: 审查代码变更，关注安全性、性能和可维护性
allowed-tools: Read, Grep, Glob
---

# 代码审查清单

审查以下方面的代码变更：

## 安全性
- [ ] SQL 注入风险
- [ ] XSS 漏洞
- [ ] 敏感数据暴露
- [ ] 认证/授权问题

## 性能
- [ ] N+1 查询
- [ ] 不必要的循环
- [ ] 内存泄漏风险

## 可维护性
- [ ] 代码可读性
- [ ] 命名规范
- [ ] 注释充分性
- [ ] 测试覆盖

$ARGUMENTS

示例 2：Git 提交 Skill

# ~/.claude/skills/smart-commit/SKILL.md

---
name: smart-commit
description: 智能生成 Git 提交信息
disable-model-invocation: true
---

根据当前变更生成提交信息：

## 变更分析
!`git diff --cached --stat`
!`git diff --cached`

## 要求
1. 使用 Conventional Commits 格式
2. 主题行不超过 50 字符
3. 正文说明为什么做这个变更
4. 如果是破坏性变更，添加 BREAKING CHANGE

生成提交信息后，询问是否确认提交。

示例 3：项目文档生成 Skill

# .claude/skills/gen-docs/SKILL.md

---
name: gen-docs
description: 为代码生成文档
---

为指定文件或目录生成文档：

## 目标
$ARGUMENTS

## 文档格式要求

### 函数文档
```typescript
/**
 * 函数描述
 * @param paramName - 参数说明
 * @returns 返回值说明
 * @example
 * // 使用示例
 */

组件文档

• 用途说明
• Props/API
• 使用示例
• 注意事项

请阅读代码后生成对应的文档。

### 示例 4：测试覆盖率检查 Skill

```yaml
# ~/.claude/skills/check-coverage/SKILL.md

---
name: check-coverage
description: 检查测试覆盖率并报告未覆盖的代码
allowed-tools: Bash(npm *), Bash(yarn *), Read
---

## 运行测试覆盖率

!`npm test -- --coverage --coverageReporters=json --coverageReporters=text`

## 分析报告

1. 总结整体覆盖率
2. 列出覆盖率低于 80% 的文件
3. 指出关键业务逻辑是否被覆盖
4. 建议需要添加测试的代码路径

目标文件：$ARGUMENTS

总结

graph TB
    subgraph concept [Skill 核心概念]
        A[SKILL.md 文件] --> B[YAML Frontmatter]
        B --> C[Markdown 指令]
    end

    subgraph key_config [关键配置]
        D[name: 调用名称]
        E[description: 自动激活依据]
        F[disable-model-invocation: 控制触发]
        G[allowed-tools: 权限限制]
    end

    subgraph usage [使用场景]
        H[标准化工作流]
        I[团队共享知识]
        J[自动化复杂任务]
        K[扩展 Claude 能力]
    end

Skill 是 Claude Code 最强大的扩展机制之一。通过创建和组织 skill，你可以：

• 标准化团队工作流 - 将最佳实践固化为可复用的技能
• 提升效率 - 避免重复输入相同的上下文和指令
• 扩展能力 - 让 Claude 掌握特定领域的知识和流程
• 保障安全 - 通过权限控制防止意外操作

开始创建你的第一个 skill 吧！

---

相关资源

• Skills 官方文档
• Subagents 子代理
• Plugins 插件系统
• Hooks 钩子机制