Claude Code Skills 完整指南

基础

什么是 Skills？

Skills 是基于提示词（prompt）的扩展工具，本质上是一个 SKILL.md 文件，教会 Claude 如何完成特定任务。

📝

基于提示词

不是代码插件，而是结构化的指令文本，Claude 按照指令编排工作

⚡

斜杠调用

通过 /skill-name 快速触发，也可由 Claude 自动识别并调用

🌐

开放标准

遵循 Agent Skills 开放标准，可跨多种 AI 工具使用

🔧

能力丰富

可以调用工具、读写文件、启动子 Agent、并行执行任务

📦

灵活分发

个人、项目、团队、企业级四种作用域，通过文件或配置分发

🚀

即插即用

创建 SKILL.md 文件即可使用，无需编译构建安装

入门

调用方式

在 Claude Code 中输入斜杠加技能名即可调用。

▶ 基本语法

/skill-name [参数]

# 示例
/simplify                          # 审查并优化代码
/loop 5m /check-deploy             # 每5分钟检查部署状态
/claude-api                        # 加载 Claude API 参考
/fix-issue 123                     # 自定义skill + 参数
/migrate SearchBar React Vue      # 多参数传递

💡

自动调用：如果 Skill 的 description 与用户意图匹配，Claude 会自动触发该 Skill，无需手动输入斜杠命令。

开箱即用

内置 Skills

Claude Code 自带以下 Skills，可以直接使用。

命令	功能	适用场景
`/simplify`	审查已修改的代码，检查复用性、质量和效率问题并自动修复	代码审查
`/batch <指令>`	启动 5-30 个 Agent 在隔离的 git worktree 中并行执行大规模重构	大规模重构
`/loop [间隔] <指令>`	按指定间隔重复执行命令，默认 10 分钟	监控轮询
`/claude-api`	加载 Claude API / Anthropic SDK 参考文档	API 开发
`/debug [描述]`	读取调试日志，排查当前 Claude Code 会话问题	故障排查

📚

说明：内置 Skills 和自定义 Skills 调用方式完全一致。内置的只是预先编写好的提示词指令。

核心

创建自定义 Skill

只需三步：建目录、写文件、直接用。

1

选择存放位置

根据作用范围选择目录：

范围	路径	说明
个人全局	`~/.claude/skills/<name>/SKILL.md`	所有项目可用
项目级	`.claude/skills/<name>/SKILL.md`	仅当前项目
企业级	通过 managed settings 部署	全组织用户

2

编写 SKILL.md

包含 YAML frontmatter（配置）和 Markdown 正文（指令）：

---
name: deploy
description: 部署应用到生产环境
argument-hint: [环境名称]
---

部署应用到 $ARGUMENTS 环境：

1. 运行 npm test 确保测试通过
2. 执行 npm run build 构建应用
3. 推送到部署目标
4. 验证部署成功，输出访问地址

3

调用使用

保存后立即可用，无需安装或重启：

/deploy production

📁 Skill 目录结构

一个 Skill 可以包含辅助文件：

my-skill/ ├── SKILL.md # 主指令文件（必需） ├── template.md # 模板文件 ├── examples/ │ └── sample.md # 示例输出 └── scripts/ └── helper.py # 辅助脚本

配置

Frontmatter 配置详解

SKILL.md 顶部的 YAML 区域控制 Skill 的行为。

---
name: skill-name                # 显示名（默认取目录名）
description: 描述               # 功能描述（自动调用的依据）
argument-hint: [arg1] [arg2]   # 自动补全提示

# 调用控制
disable-model-invocation: true  # 仅用户可调用（禁止自动触发）
user-invocable: false           # 仅 Claude 自动调用（用户不可见）

# 运行控制
allowed-tools: Read, Grep       # 允许使用的工具（免确认）
model: claude-opus              # 指定模型
context: fork                   # 在隔离子 Agent 中运行
agent: Explore                  # 子 Agent 类型
hooks: ...                      # 此 Skill 的专属 Hooks
---

🔒 调用控制

默认：用户和 Claude 都可调用
disable-model-invocation: true
仅 / 斜杠手动触发
user-invocable: false
背景知识型，自动注入上下文

⚙ 运行控制

allowed-tools 跳过工具确认弹窗
context: fork 隔离运行不污染主上下文
agent: Explore 使用探索型子 Agent
model 指定用 opus / sonnet / haiku

⚠️

优先级规则：当不同作用域存在同名 Skill 时，企业级 > 个人 > 项目。企业设置始终优先。

参数

参数传递

Skill 支持灵活的参数引用方式。

🎯 参数引用语法

语法	说明	示例
`$ARGUMENTS`	全部参数（字符串）	`/deploy production --force` → `"production --force"`
`$ARGUMENTS[0]` 或 `$0`	第一个参数	→ `"production"`
`$ARGUMENTS[1]` 或 `$1`	第二个参数	→ `"--force"`

示例 SKILL.md

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

将 $0 组件从 $1 迁移到 $2。
保留所有现有行为和测试。

调用方式

/migrate SearchBar React Vue

# $0 = SearchBar
# $1 = React
# $2 = Vue

💡

如果 SKILL.md 内容中没有使用 $ARGUMENTS，Claude Code 会自动在末尾追加 ARGUMENTS: <用户输入>。

进阶

高级用法

动态上下文注入、嵌入命令输出等高级技巧。

💻 动态上下文 —— 嵌入 Shell 命令输出

使用 !`command` 语法，在 Skill 发送给 Claude 之前执行命令，将输出替换到文本中：

---
name: pr-summary
description: 总结 PR 变更
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

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

根据以上信息总结变更内容和潜在影响...

🔓 背景知识型 Skill

设置 user-invocable: false 让 Skill 仅作为背景知识自动注入，用户不可见：

---
name: legacy-context
user-invocable: false
description: 旧系统架构说明
---

旧后端使用 SOAP 协议...
数据库采用 Oracle 11g...
服务间通过 MQ 通信...

🎯 并行子 Agent

/batch 启动多个隔离 worktree 中的 Agent 并行工作：

/batch 将所有 .jsx 文件
迁移为 .tsx，添加类型注解

# Claude 会：
# 1. 扫描所有 .jsx 文件
# 2. 启动 5-30 个 Agent
# 3. 各自在 worktree 中工作
# 4. 汇总结果

实战

完整示例

一些实用的自定义 Skill 参考。

🚀 示例 1：部署 Skill

---
name: deploy
description: 部署应用到指定环境
argument-hint: [staging|production]
disable-model-invocation: true
allowed-tools: Bash(npm *, git *)
---

部署应用到 $0 环境：

1. 运行 `npm test` 确保所有测试通过
2. 运行 `npm run build` 构建生产版本
3. 检查 git 状态，确保工作区干净
4. 如果是 production，先确认用户同意
5. 执行部署命令
6. 验证部署成功并输出访问地址

调用：/deploy production

🔎 示例 2：代码审查 Skill

---
name: review
description: 审查当前分支的代码变更
context: fork
allowed-tools: Bash(git *), Read, Grep
---

## 当前变更
!`git diff main --stat`

## 审查要求
按以下维度审查所有变更：

- **安全性**：是否存在注入、XSS、信息泄露
- **性能**：是否有 N+1 查询、内存泄漏风险
- **可维护性**：命名是否清晰、是否过度抽象
- **测试**：新功能是否有对应测试覆盖

输出格式：对每个文件给出 ✓/⚠/✗ 评级和说明。

📑 示例 3：API 规范 Skill（背景知识型）

---
name: api-conventions
description: 项目 API 设计规范
user-invocable: false
---

编写 API 时必须遵守以下规范：

- RESTful 命名：GET /users, POST /users, PUT /users/:id
- 统一错误格式：{ code, message, details }
- 请求校验使用 zod schema
- 分页参数：page + pageSize，响应包含 total
- 认证使用 Bearer Token，放在 Authorization header
- 所有时间字段使用 ISO 8601 格式

此 Skill 不会出现在斜杠菜单中，当 Claude 检测到你在写 API 时会自动应用这些规范。

🛠 示例 4：定时监控 Skill

# 用内置 /loop 配合自定义 skill
/loop 5m /check-deploy

# check-deploy 的 SKILL.md：
---
name: check-deploy
description: 检查部署状态
allowed-tools: Bash(curl *)
---

检查部署状态：
1. 调用 `curl -s https://api.example.com/health`
2. 如果返回非 200，立即报告异常
3. 如果连续 3 次正常，输出"部署稳定"