如何编写Claude Code Skills

发表于 分类于
本文字数： 4.5k 阅读时长 ≈ 4 分钟

如何编写Claude Code Skills

Claude Code 的 Skills 是一种强大的扩展机制，允许开发者创建可复用的指令集，通过斜杠命令快速调用。本文将详细介绍 Skills 的概念、结构和编写技巧。

1. 什么是 Skill

Skill（技能）是 Claude Code 中的一种扩展机制，它本质上是一组预定义的指令集，可以让 AI 代理执行特定的任务。通过 Skills，你可以：

  • 封装常用的工作流程
  • 标准化代码生成模板
  • 自动化复杂的开发任务
  • 团队共享最佳实践

调用方式：

1
2
3
4
5
# 通过斜杠命令调用
/skill-name

# 带参数调用
/skill-name arg1 arg2

2. Skill 包含哪些部分

一个完整的 Skill 由以下部分组成：

2.1 目录结构

1
2
3
4
5
6
7
8
my-skill/
├── SKILL.md          # 必需：指令 + 元数据
├── README.md         # 可选：人类可读描述
├── metadata.json     # 可选：发布用扩展元数据
├── references/       # 可选：文档、指南、API 参考
├── examples/         # 可选：示例输出
├── scripts/          # 可选：可执行代码
└── assets/           # 可选：模板、图片、数据文件

2.2 核心文件 - SKILL.md

SKILL.md 是 Skill 的核心，包含两部分：

Frontmatter（元数据）：

1
2
3
4
---
name: my-skill
description: "What this skill does and when to use it."
---

指令内容： 具体的执行步骤和要求。

2.3 元数据字段说明

字段 类型 必需 说明
name string 是 1-64字符，小写字母+连字符，必须匹配文件夹名
description string 是 1-1024字符，描述功能和使用场景
license string 否 许可证信息
compatibility string 否 环境要求
metadata object 否 附加元数据（author, version等）

高级字段（Claude Code 特有）：

字段 说明
disable-model-invocation 设为 true 时仅用户可调用，agent 不能自动调用
user-invocable 设为 false 时从菜单隐藏，仅 agent 可加载
allowed-tools 预批准的工具列表，如 Read Grep Glob
context 设为 fork 在子 agent 上下文中运行
agent 子 agent 类型：Explore、Plan

3. 如何创建一个初始 Skill

3.1 基本步骤

  1. 创建文件夹： 在 .claude/skills/ 目录下创建以 skill 名称命名的文件夹
1
mkdir -p .claude/skills/hexo-deploy
  1. 创建 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
---
name: hexo-deploy
description: "Deploy Hexo blog to GitHub Pages. Covers build and deploy workflow."
---

# Hexo Deploy Skill

部署 Hexo 博客到 GitHub Pages。

## 步骤

1. 清理旧文件：
```bash
hexo clean
```

2. 生成静态文件：
```bash
hexo generate
```

3. 部署到 GitHub：
```bash
hexo deploy
```

## 注意事项

- 确保 `_config.yml` 中的 deploy 配置正确
- 部署前建议先本地预览
  1. 测试 Skill： 在 Claude Code 中输入 /hexo-deploy 测试

3.2 完整示例

以下是一个代码审查 Skill 的示例：

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
---
name: code-review
description: "Review code for best practices and potential issues."
license: MIT
compatibility: Requires git
allowed-tools: Read Grep Glob
metadata:
  author: your-name
  version: "1.0.0"
---

# Code Review Skill

## 审查内容

1. **代码风格**
   - 命名规范
   - 代码格式
   - 注释质量

2. **潜在问题**
   - 安全漏洞
   - 性能问题
   - 错误处理

3. **最佳实践**
   - 设计模式
   - 单一职责
   - 代码复用

## 输出格式

```markdown
## 审查结果

### 优点
- [列出优点]

### 问题
- [列出问题及建议]

### 建议
- [改进建议]
```

4. 怎样写出一个好的 Skill

4.1 Description 编写技巧

公式：

1
[产品] [核心功能]. Covers [关键主题]. Keywords: [关键词].

好的示例：

1
description: "Hexo blog deployment. Covers build, deploy, and preview. Keywords: Hexo, GitHub Pages, deployment."

差的示例：

1
2
description: "Helps with deployment."  # 太模糊
description: "A powerful deployment tool."  # 营销语言

规则：

  • 目标：80-150 字符
  • 包含触发关键词
  • 避免营销词汇（”powerful”, “comprehensive”）
  • 避免填充词（”this skill”, “use this for”）

4.2 保持 SKILL.md 简洁

关键规则： SKILL.md 不要超过 500 行。

解决方案：使用 Router 模式

对于复杂的 Skill，将详细内容放在 references/ 目录：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
---
name: complex-skill
description: "Complex skill with multiple topics."
---

# Complex Skill

本文件是路由文件，请根据需要阅读对应文档。

## 入门

- 新手？阅读：`references/getting-started.md`
- 快速设置？阅读：`references/quickstart.md`

## 按场景选择

### 功能 A
- 详细说明：`references/feature-a.md`

### 功能 B
- 详细说明：`references/feature-b.md`

4.3 使用变量和动态注入

变量替换：

1
2
3
4
5
6
7
8
9
10
---
name: pr-review
description: "Review pull request."
---

# PR Review

审查 PR: $ARGUMENTS

请分析代码变更并提供反馈。

动态上下文注入：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
---
name: pr-review
description: "Review pull request with diff context."
---

# PR Review

## PR 上下文

- PR diff: !`gh pr diff`
- 变更文件: !`gh pr diff --name-only`

## 任务

审查这个 PR 的代码变更...

4.4 工具限制

合理限制 Skill 可使用的工具，提高安全性：

1
2
3
4
5
6
7
8
# 只读分析
allowed-tools: Read Grep Glob

# Git 操作
allowed-tools: Bash(git:*)

# 特定命令
allowed-tools: Bash(npm:*) Bash(pnpm:*)

4.5 调用控制

根据使用场景设置调用权限：

场景 配置
用户和 agent 都可调用 默认，无需配置
仅用户手动调用 disable-model-invocation: true
仅 agent 后台调用 user-invocable: false

4.6 最佳实践清单

  • Name 使用小写字母和连字符，匹配文件夹名
  • Description 包含关键词，80-150 字符
  • SKILL.md 控制在 500 行以内
  • 复杂内容放入 references/ 目录
  • 合理使用变量和动态注入
  • 设置适当的工具限制
  • 添加示例和说明文档
  • 测试 Skill 的各种调用方式

5. 实战案例

案例 1：Hexo 文章发布 Skill

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
---
name: hexo-post
description: "Create and publish Hexo blog post. Covers frontmatter, tags, categories."
argument-hint: [title]
allowed-tools: Read Write Bash(hexo:*)
metadata:
  author: your-name
  version: "1.0.0"
---

# Hexo Post Skill

创建新的 Hexo 博客文章。

## 参数

- `$ARGUMENTS`: 文章标题

## 步骤

1. 创建新文章：
   ```bash
   hexo new "$ARGUMENTS"
   ```

2. 编辑 frontmatter：
   ```yaml
   ---
   title: $ARGUMENTS
   date: YYYY-MM-DD HH:MM:SS
   tags: [tag1, tag2]
   categories: [category]
   ---
   ```

3. 添加内容...

## 注意事项

- 标签使用小写
- 分类保持简洁
- 日期格式：YYYY-MM-DD HH:MM:SS

案例 2：代码重构 Skill

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
---
name: refactor-code
description: "Refactor code following best practices. Covers naming, structure, patterns."
allowed-tools: Read Write Edit Grep Glob
context: fork
agent: Explore
---

# Code Refactoring Skill

重构代码，遵循最佳实践。

## 重构内容

1. **命名优化**
   - 变量名清晰表达意图
   - 函数名体现功能
   - 类名使用名词

2. **结构调整**
   - 函数职责单一
   - 减少嵌套层级
   - 提取重复代码

3. **设计模式**
   - 识别可应用的模式
   - 保持简单优先

## 输出

```markdown
## 重构结果

### 变更列表
- [文件]: [变更说明]

### 改进点
- [改进说明]
```

总结

编写高质量的 Claude Code Skill 需要注意：

  1. 清晰的命名和描述 - 让用户和 agent 快速理解用途
  2. 合理的结构 - 核心指令简洁，详细内容分离
  3. 安全的工具限制 - 只授予必要的权限
  4. 良好的文档 - 示例和说明帮助理解
  5. 持续优化 - 根据使用反馈改进

通过遵循这些原则，你可以创建出强大、易用、安全的 Skills，提升开发效率。

参考资料

感谢您对本站的支持.