Claude Code Skills 完整指南

发表于 更新于 分类于 ，

一、基础概念

什么是 Skills？
Skills 是 Claude Code 的扩展机制，让你可以创建、管理和分享自定义能力。每个 Skill 是一个包含 SKILL.md 文件的目录，Claude 会将其添加到工具箱中。

核心价值：

  • 自动化重复任务
  • 添加领域专业知识
  • 强制执行代码标准和最佳实践
  • 加速项目脚手架和代码生成

二、文件结构

1
2
3
4
5
6
~/.claude/skills/<skill-name>/
├── SKILL.md          # 必需，主指令文件
├── templates/        # 可选，模板文件
├── examples/         # 可选，示例输出
├── scripts/          # 可选，脚本文件
└── docs/             # 可选，详细参考文档

Skills 存储位置：

位置 路径 适用范围
Enterprise 托管设置 组织内所有用户
Personal ~/.claude/skills/ 所有项目
Project .claude/skills/ 当前项目
Plugin <plugin>/skills/ 插件启用范围

三、SKILL.md 文件格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
name: my-skill
description: 这个 skill 的用途说明
argument-hint: [参数提示]
disable-model-invocation: false
user-invocable: true
allowed-tools:
  - Read
  - Glob
model: claude-sonnet-4-20250514
context: fork
agent: Explore
---

# Skill 内容

这里是 Claude 执行的具体指令...

Frontmatter 字段说明：

字段 必需 说明
name 否 显示名称，默认用目录名
description 推荐 用途说明，Claude 用于判断何时加载
argument-hint 否 参数提示，如 [issue-number]
disable-model-invocation 否 true 禁止自动加载
user-invocable 否 false 从 / 菜单隐藏
allowed-tools 否 授权工具列表，无需逐次确认
model 否 指定模型
context 否 设为 fork 在子代理中运行
agent 否 子代理类型：Explore、Plan、general-purpose

四、Skill 类型

1. 参考型（Reference Content）

  • 添加知识供 Claude 应用
  • 如：约定、模式、风格指南、领域知识
  • 在对话上下文中内联运行

2. 任务型（Task Content）

  • 提供特定操作的步骤指令
  • 如：部署、提交、代码生成
  • 通常设置 disable-model-invocation: true 仅手动触发

五、参数传递

1
2
3
4
5
6
7
8
9
10
11
# 使用 $ARGUMENTS 接收所有参数

修复 GitHub issue $ARGUMENTS...

# 使用索引访问特定参数

修复组件 $ARGUMENTS[0]，从 $ARGUMENTS[1] 迁移到 $ARGUMENTS[2]

# 简写形式

修复组件 $0，从 $1 迁移到 $2

可用变量：

  • $ARGUMENTS - 所有参数
  • $ARGUMENTS[N] 或 $N - 第 N 个参数
  • ${CLAUDE_SESSION_ID} - 当前会话 ID
  • ${CLAUDE_SKILL_DIR} - Skill 目录路径

六、进阶模式

1. 动态上下文注入

1
2
3
4
5
6
7
8
---
name: pr-summary
---

!gh pr diff $ARGUMENTS
!gh pr view $ARGUMENTS --json title,body

请总结以上 PR 内容...

!command 语法先执行 shell 命令，输出替换占位符。

2. 子代理运行

1
2
3
4
---
context: fork
agent: Explore
---
  • 创建隔离上下文
  • Skill 内容成为子代理的 prompt
  • 适合大规模代码库探索

3. 视觉输出生成

  • Skill 可捆绑运行 Python 等脚本
  • 生成交互式 HTML 文件
  • 如：依赖图、测试覆盖率报告、代码库可视化

七、内置 Bundled Skills

命令 用途
/simplify 代码简化，专注特定目标
/batch 并行执行 5-30 个独立任务单元
/debug 调试辅助
/loop 定时执行 prompt
/claude-api Claude API 相关帮助

八、权限控制

禁用所有 Skills：

1
/permissions deny Skill

允许/拒绝特定 Skills：

1
2
/permissions allow Skill(review)
/permissions deny Skill(deploy *)

隐藏单个 Skill：

1
disable-model-invocation: true

九、常见问题排查

问题 解决方案
Skill 未触发 检查 description 关键词、验证 skill 是否在列表中、尝试直接调用
触发太频繁 使 description 更具体、设置 disable-model-invocation: true
Claude 看不到所有 skills Skills 描述可能超出字符预算（默认 16000 字符），运行 /context 检查

十、最佳实践

  1. 清晰命名 - 使用描述性的 skill 名称
  2. 精确描述 - description 决定 Claude 何时自动加载
  3. 分离关注点 - 复杂 skill 用支持文件保持 SKILL.md 简洁
  4. 版本控制 - 项目级 skills 提交到 .claude/skills/
  5. 渐进增强 - 从 5-10 个 skills 开始，按需添加

十一、实用示例

示例1：代码解释 Skill

创建 ~/.claude/skills/explain-code/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
---
name: explain-code
description: 使用可视化图表和类比解释代码工作原理
---

当用户询问某段代码如何工作时：

1. 首先用简单的语言解释代码的核心目的
2. 使用类比将概念与日常事物联系起来
3. 创建一个 ASCII 图表展示数据流和控制流
4. 标注关键的决策点和数据转换
5. 提供一个具体的使用场景示例

格式：

## 概述

[一句话描述]

## 类比

[将代码比作日常事物]

## 流程图

[ASCII 图表]

## 关键点

- [要点1]
- [要点2]

## 示例场景

[具体场景描述]

示例2：Git 提交 Skill

创建 ~/.claude/skills/git-commit/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
---
name: commit
description: 生成符合规范的 Git 提交信息
argument-hint: [可选的提交类型]
disable-model-invocation: true
---

根据当前暂存的更改生成提交信息：

1. 运行 `git diff --staged` 查看更改
2. 分析更改类型（feat/fix/docs/style/refactor/test/chore）
3. 生成符合 Conventional Commits 规范的提交信息

提交信息格式：

```
<type>(<scope>): <subject>

<body>

<footer>
```

$ARGUMENTS

示例3：代码审查 Skill

创建 ~/.claude/skills/code-review/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
---
name: review
description: 对代码进行全面审查，检查安全、性能和最佳实践
allowed-tools:
  - Read
  - Glob
  - Grep
---

对指定的代码进行审查：

## 审查维度

### 安全性

- SQL 注入风险
- XSS 漏洞
- 敏感信息泄露
- 输入验证

### 性能

- 不必要的循环
- 内存泄漏风险
- N+1 查询问题
- 缓存机会

### 代码质量

- 命名规范
- 代码复杂度
- 重复代码
- 注释完整性

### 最佳实践

- 设计模式应用
- 错误处理
- 测试覆盖

## 输出格式

```
## 审查报告：[文件名]

### 发现的问题

| 级别  | 位置    | 问题 | 建议 |
| ----- | ------- | ---- | ---- |
| ERROR | line:42 | ...  | ...  |
| WARN  | line:58 | ...  | ...  |

### 优点

- ...

### 总体评分：X/10

```

$ARGUMENTS

十二、资源链接

官方资源：

社区资源：