Claude Code Skills 使用教程——从入门到进阶

, , , , ,

Claude Code Skills 使用教程——从入门到进阶

作者： CaoZH
版本： 2026-05-31
适用平台： Claude Code CLI / Claude Desktop

目录

  1. 什么是 Skills？
  2. 内置命令：开箱即用
  3. 安装社区技能
  4. 编写自己的技能
  5. SKILL.md 前端配置详解
  6. 技能类型与设计模式
  7. 技能存放位置与作用域
  8. 实战：一步步创建技能
  9. 调试与优化技能
  10. 常见问题

一、什么是 Skills？

Skills（技能）是 Claude Code 的能力扩展系统。本质上，它是一个包含 SKILL.md 文件的目录，该文件使用 YAML 前端配置 + Markdown 指令 告诉 Claude 如何完成特定任务。

Skills vs 其他概念

概念 是什么 区别
Skills SKILL.md 指令文件 教会 Claude 怎么做某事（流程、规范、知识）
CLAUDE.md 项目级记忆文件 告诉 Claude 项目的背景信息（不涉及流程）
MCP 服务器 外部服务连接器 给 Claude 新增能力（访问 API、数据库等）
Plugins 技能的打包单元 一个插件可以包含多个 Skills + MCP + Hooks
Hooks 生命周期脚本 在特定时机自动运行脚本（如保存时格式化）

两种技能来源

Skills 有两种来源：

  1. 社区安装的技能——通过插件市场安装（如 Superpowers、webapp-testing 等），详见第三章
  2. 自己编写的技能——手动创建 SKILL.md 文件放在 ~/.claude/skills/ 下，详见第四章

⚠️ 注意：Claude Code 的 /review、/plan、/compact 等斜杠命令是 CLI 内置功能，不属于 Skills 系统。Slash Commands 是手动调用的，Skills 是基于自然语言自动触发的，两者是不同的机制。

技能的工作机制

当你与 Claude 对话时，它会扫描所有已安装技能的 name 和 description（仅消耗约 100 tokens/技能 的上下文）。当对话内容匹配某个技能的描述时，Claude 会按需加载该技能的完整 SKILL.md 内容。

这意味着：

  • ✅ 装几十个技能也几乎不占上下文
  • ✅ 只有触发时才加载完整指令
  • ✅ 技能之间可以联动和组合

二、内置命令：开箱即用

Claude Code 自带了一套内置的斜杠命令（Slash Commands），安装后直接通过 / 前缀访问。这些是 CLI 内置功能，与 Skills（技能系统）是不同的概念——Skills 是 SKILL.md 文件驱动的自动触发工作流，而这里是手动调用的命令。

内置命令列表

会话与上下文管理

命令 功能 适用场景
/help 查看所有可用命令 首次使用、查找命令
/compact [焦点] 压缩上下文节省 token 上下文占用超过 70% 时
/clear 清空对话历史，重新开始 对话偏离主题
/context 可视化查看上下文使用情况 检查 token 消耗
/cost 查看 token 用量及费用明细 费用监控
/status 显示版本、连接状态和会话信息 检查环境
/resume 切换或恢复历史会话 继续上次工作
/rewind 回退到之前的检查点 纠正 AI 错误走向
/btw <问题> 提出旁侧问题，不增加主对话上下文 查文档、快速查询
/todos 列出当前对话中的待办事项 跟踪进度
/exit / Ctrl+D 结束会话 退出

开发与审查

命令 功能 适用场景
/review 自动代码审查 提交 PR 前、合并分支前
/security-review 安全审计 检查安全漏洞
/plan [描述] 进入 Plan 模式制定实施计划 复杂任务先规划再写代码
/loop [间隔] 在会话中设置循环任务 重复性操作
/batch 自动创建工作树进行大规模并行修改 同时改 5-30 个文件

配置与工具

命令 功能 适用场景
/model [模型] 切换模型（如 /model haiku） 根据任务复杂度选模型
/effort [等级] 设置推理深度：low/medium/high/max/auto 控制思考深度和成本
/init 创建项目 CLAUDE.md 记忆文件 新项目初始化
/memory 编辑 CLAUDE.md 更新项目背景
/config 交互式配置设置 调整 Claude Code 行为
/permissions 查看/更新工具权限 安全检查
/agents 管理自定义子代理 编排多代理工作流
/mcp 管理 MCP 服务器 添加数据库、API 等外部连接
/add-dir 添加额外工作目录 monorepo 多目录项目
/voice 语音模式（长按空格录音） 语音输入

用法示例

1
2
3
4
5
6
# 在 Claude Code 终端中直接输入
/review              # 审查当前更改（注意是 /review 不是 /code-review）
/security-review     # 安全审计
/plan "重构用户模块"  # 先规划再执行
/compact focus on auth  # 压缩上下文，聚焦认证模块
/rewind              # 回退到之前的状态

内置命令无需安装，开箱即用，但注意它们不是 Skills（技能系统）——你不能像覆盖自定义技能那样覆盖它们。想要扩展 Claude Code 的行为，应该通过编写自定义 Skills（见第四章）或自定义 Slash 命令（见第四章）来实现。

三、安装社区技能

Claude Code 使用 Plugin（插件）系统 来分发技能。社区技能托管在 GitHub 仓库中，可以被添加为”市场”（Marketplace）。

3.1 从官方市场安装

Anthropic 官方维护了一个技能市场：

1
2
3
4
5
6
# 第一步：添加市场源
/plugin marketplace add anthropics/skills

# 第二步：安装技能
/plugin install webapp-testing@anthropics-skills
/plugin install frontend-design@anthropics-skills

3.2 从社区仓库安装

1
2
3
4
5
6
7
8
9
10
11
12
# 添加 Superpowers 市场
/plugin marketplace add obra/superpowers

# 安装技能
/plugin install superpowers
/plugin install writing-plans@obra-superpowers

# 添加 Addy Osmani 的工程技能
/plugin marketplace add addyosmani/agent-skills
/plugin install spec-driven-development@addy-agent-skills
/plugin install code-review-and-quality@addy-agent-skills
/plugin install security-hardening@addy-agent-skills

3.3 常用社区市场

市场 来源 推荐技能
anthropics/skills 官方 webapp-testing, frontend-design, skill-creator
obra/superpowers 社区最热 brainstorming, writing-plans, execute-plan, TDD
addyosmani/agent-skills Google 工程师出品 spec-driven, code-review, security, performance
firecrawl/firecrawl-claude-plugin 网页抓取 firecrawl-build
composiohq/composio 应用集成 composio-connect

3.4 管理已安装的技能

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 查看所有已安装的插件
/plugin list

# 查看所有可用技能
/skills

# 启用/禁用某个技能
/plugin enable superpowers
/plugin disable superpowers

# 移除技能
/plugin remove superpowers

# 移除市场源
/plugin marketplace remove obra/superpowers

3.5 直接从 GitHub 手动安装

你也可以从 GitHub 直接下载技能：

1
2
3
4
5
6
# 克隆技能仓库
git clone https://github.com/obra/superpowers.git ~/.claude/skills/superpowers

# 或只安装其中某个子技能
mkdir -p ~/.claude/skills/my-tdd
cp superpowers/skills/test-driven-development/SKILL.md ~/.claude/skills/my-tdd/

四、编写自己的技能

这是最强大的部分——为你的团队或项目定制专属技能。

4.1 最简单的技能

创建一个文件 ~/.claude/skills/hello/SKILL.md：

1
2
3
4
5
6
7
8
9
10
---
name: hello
description: |
  一个测试技能。当用户说"你好"或"hello"时触发。
  打印欢迎信息并询问今天的工作内容。
---

# Hello Skill

当用户问候时，热情回应，并询问今天需要做什么。

重启 Claude Code 后，说”你好”就会触发这个技能。

4.2 实用技能示例：Git 提交规范

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: git-commit-convention
description: |
  当用户要求提交 Git commit 时使用。
  检查暂存区更改，生成符合 Conventional Commits 格式的提交信息。
  格式: type(scope): description
---

# Git Commit Convention

当需要提交代码时，遵循以下步骤：

1. 运行 `git diff --cached` 查看暂存区更改
2. 根据更改类型确定 commit type：
   - `feat`: 新功能
   - `fix`: Bug 修复
   - `docs`: 文档更改
   - `style`: 代码格式（不影响功能）
   - `refactor`: 重构
   - `test`: 测试相关
   - `chore`: 构建/工具
3. 生成格式: `type(scope): description`

示例：

feat(auth): add OAuth2 login support
fix(parser): handle null input in JSON parser
docs(readme): update installation instructions

1
2
3
4
5
6
```

### 4.3 更复杂的技能：带脚本和引用文件

技能目录可以包含多个文件：

~/.claude/skills/deploy-check/
├── SKILL.md # 核心指令
├── scripts/
│ └── check-health.sh # 健康检查脚本
└── references/
└── deployment-checklist.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

在 `SKILL.md` 中引用这些文件：

```markdown
---
name: deploy-check
description: |
  部署前的全面检查。当用户要求"部署"、"发布"或"deploy"时触发。
  运行健康检查脚本并核对部署清单。
---

# Deployment Pre-flight Check

部署前执行以下步骤：

## 1. 运行健康检查
执行脚本 `{skilldir}/scripts/check-health.sh` 并分析输出。

## 2. 核对部署清单
阅读 `{skilldir}/references/deployment-checklist.md`
逐项确认每个检查点。

## 3. 生成部署报告
汇总检查结果，标记通过/失败的项。

注意： {skilldir} 是 Claude Code 自动注入的变量，指向技能目录的路径。

五、SKILL.md 前端配置详解

YAML 前端配置（Frontmatter）是 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
---
# === 必需字段 ===
name: my-awesome-skill
description: |
  清晰描述技能做什么以及在何种情况下触发。
  好的描述是技能被正确调用的关键。

# === 触发控制 ===
when_to_use: |
  额外的触发条件说明，补充 description。
  描述越精准，误触发越少。

disable-model-invocation: true
# true: Claude 不会自动触发，只能用户手动 /command 调用
# 适用于破坏性操作或需要用户确认的技能

user-invocable: false
# false: 隐藏斜杠命令，只有 Claude 可以自动触发
# 适用于后台工作流，不需要用户主动调用的技能

# === 权限控制 ===
allowed-tools: "Read, Grep, Bash, Glob"
# 限制技能可使用的工具，用逗号分隔
# 常见值: Read, Grep, Glob, Bash, Write, Edit, Execute
# 默认为全部工具（不设置此字段时）
# 可细化: "Bash(python:*)" 表示只能运行 Python

# === 执行模式 ===
context: fork
# 不设置: 在主线对话中执行（默认）
# fork: 在独立的子代理中执行，隔离上下文
# 适用于长时间运行的任务，不影响主线对话

# === 生命周期钩子 ===
hooks:
  on_skill_start: echo "技能开始执行"
  on_skill_end: echo "技能执行完毕"
  on_error: |
    echo "出错时间: $(date)" >> /tmp/skill-errors.log

# === 其他 ===
model: claude-sonnet-4
# 覆盖当前使用的模型，特定技能用更合适的模型

argument-hint: "<文件名> [选项]"
# 为斜杠命令显示参数提示

version: 1.0.0
author: CaoZH
license: MIT
compatible-with: claude-code, codex, openclaw
---

关键字段详解

description —— 决定技能是否被触发

这是最重要的字段。Claude 在每次对话中只读 name 和 description，如果描述不够精准，技能永远不会被激活。

好的描述：

1
2
3
4
description: |
  处理 PDF 发票：解析发票 PDF，提取行项目，生成对账报告。
  在处理供应商发票或月度结算时使用。
  触发词：'process invoices'、'reconciliation'、'invoice PDF'

差的描述：

1
description: 处理文件

allowed-tools —— 安全沙箱

通过限制工具来防止误操作：

1
2
3
4
5
6
7
# 只读模式：查看文件，不能修改
allowed-tools: "Read, Grep, Glob"

# 只允许执行特定命令
allowed-tools: "Read, Bash(python:*,node:*)"

# 完全开放（不设置此字段即为默认）

context: fork —— 隔离执行

适合以下场景：

  • 长时间运行的批量操作：不阻塞主线对话
  • 高风险操作：即使子代理崩溃，主线对话不受影响
  • 并行任务：多个 skill 可以 fork 后并行执行

hooks —— 自动化钩子

支持三个生命周期事件：

钩子 触发时机 典型用途
on_skill_start 技能开始前 日志记录、环境准备
on_skill_end 技能完成后 清理、通知、统计
on_error 技能出错时 错误记录、告警

六、技能类型与设计模式

根据功能分类，Claude Code 技能通常有四种设计模式：

6.1 参考型（Reference Skill）

目的：提供知识背景，让 Claude 按特定风格工作。

1
2
3
4
5
6
7
8
9
10
11
12
---
name: react-best-practices
description: |
  React 开发最佳实践。当项目包含 React 代码时自动生效。
---
# React 编码规范

- 使用函数组件和 Hooks，避免 class 组件
- 使用 TypeScript 定义 Props 接口
- 组件文件命名: PascalCase.tsx
- 优先使用 React Query 管理服务端状态
- ...

特点：

  • 通常设置 disable-model-invocation: false（自动触发）
  • 不定义具体流程，只提供规范
  • 触发后 Claude 会自动按规范行事

6.2 工作流型（Workflow Skill）

目的：定义多步骤的执行流程。

1
2
3
4
5
6
7
8
9
10
11
12
---
name: api-endpoint-workflow
description: 当用户要求创建新的 API 端点时使用。
---
# 创建 API 端点流程

1. 定义请求/响应类型（DTO）
2. 编写 Controller/Handler
3. 编写 Service 层逻辑
4. 添加参数验证
5. 编写单元测试
6. 注册路由

特点：

  • 步骤明确、顺序执行
  • 每个步骤可能有验证条件
  • 适合重复性开发任务

6.3 斜杠命令型（Slash Command）

目的：用户主动触发，通常带有参数。

1
2
3
4
5
6
7
8
9
10
11
12
13
---
name: generate-component
user-invocable: true
disable-model-invocation: true
argument-hint: "<组件名> [选项]"
---
# 生成 React 组件

根据参数创建新的 React 组件，包含：
- 组件文件
- 样式文件（CSS Module）
- 测试文件
- Storybook stories

特点：

  • disable-model-invocation: true 防止自动触发
  • argument-hint 提示用户输入参数
  • 适合用户主动调用的工具

6.4 代理型（Agent Skill）

目的：在独立子代理中执行复杂任务。

1
2
3
4
5
6
7
8
9
10
11
---
name: dependency-audit
description: 依赖安全检查。当项目有 package.json 时周期性检查。
context: fork
---
# 依赖审计

在子代理中独立运行：
1. 运行 `npm audit` 或 `pip audit`
2. 分析报告，标记严重漏洞
3. 生成修复建议

特点：

  • context: fork 隔离执行
  • 适合耗时或计算密集的任务
  • 不干扰主对话

七、技能存放位置与作用域

技能可以放在不同的位置，决定其作用范围：

7.1 用户级（全局生效）

1
~/.claude/skills/<skill-name>/SKILL.md

放在此处的技能在所有项目中都可用。

7.2 项目级

1
<project-root>/.claude/skills/<skill-name>/SKILL.md

仅在该项目目录下生效。项目级技能优先级高于用户级。

7.3 团队级（通过 Git 共享）

将技能放在项目仓库中：

1
2
3
4
5
6
7
8
my-project/
├── .claude/
│   ├── skills/
│   │   ├── deploy-flow/SKILL.md
│   │   └── code-style/SKILL.md
│   └── CLAUDE.md
├── src/
└── package.json

提交到 Git 后，所有克隆该项目的人自动获得这些技能。

7.4 作用域优先级

1
项目级 > 用户级

同名技能，项目级覆盖用户级。

八、实战：一步步创建技能

我们来创建一个实用的 Python 项目初始化技能。

步骤 1：创建目录

1
mkdir -p ~/.claude/skills/init-python-project

步骤 2：编写 SKILL.md

1
vim ~/.claude/skills/init-python-project/SKILL.md

内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
---
name: init-python-project
description: |
  初始化 Python 项目结构。当用户说"创建 Python 项目"、"初始化项目"
  或 "new python project" 时触发。
  创建标准目录结构、虚拟环境、配置文件。
---

# Python 项目初始化

## 流程

### 1. 询问项目信息
- 项目名称
- 项目描述
- Python 版本要求（默认 3.11+）

### 2. 创建目录结构

project-name/
├── src/
│ └── project_name/
│ ├── init.py
│ └── main.py
├── tests/
│ ├── init.py
│ └── test_main.py
├── docs/
├── scripts/
├── .env.example
├── .gitignore
├── README.md
├── pyproject.toml
└── requirements.txt

1
2
3
4
5
6
7
8
9
10
11
12
13

### 3. 生成配置文件

**pyproject.toml** 包含：
- 项目元数据
- 依赖管理（使用 pip 或 uv）
- 工具配置（ruff, mypy, pytest）

**.gitignore** 包含 Python 标准忽略规则

### 4. 初始化虚拟环境
```bash
python -m venv .venv

5. 创建初始 Git 仓库

1
2
3
git init
git add .
git commit -m "chore: initial project structure"

输出

完成后打印项目结构和下一步建议。

1
2
3
4
5
6
7

### 步骤 3：验证技能是否加载

在 Claude Code 中运行：

```bash
/skills

如果看到 init-python-project 出现在列表中，说明加载成功。

步骤 4：测试使用

在 Claude Code 中说出：

“帮我创建一个新的 Python 项目”

此时 Claude 会匹配到 init-python-project 技能描述，加载完整指令并执行。

九、调试与优化技能

9.1 检查技能加载状态

1
2
/skills              # 列出所有已加载的技能
/plugin list         # 列出所有已安装的插件

9.2 强制触发技能

如果技能没有被自动触发，可以用斜杠命令方式：

1
/init-python-project "创建一个名为 my-app 的 Python 项目"

9.3 技能未触发的常见原因

问题 原因 修复
技能列表看不到 目录或文件名不对 检查 SKILL.md（大小写敏感）
描述匹配了但不触发 description 不够精准 增加触发词，参考已有技能
执行效果不符合预期 指令不够明确 增加具体步骤和代码示例
技能太多影响性能 description 太泛导致频繁误匹配 缩小触发范围，增加 when_to_use

9.4 优化建议

  1. 描述要精确：用触发词列表收窄匹配范围
  2. 步骤要具体：模糊的指令导致模糊的执行
  3. 提供示例：代码示例比文字描述更有效
  4. 使用脚本：复杂逻辑放到脚本中，SKILL.md 保持简洁
  5. 迭代改进：用 2-3 次真实使用来打磨内容

9.5 测试新技能的方法

装完后用实际场景测试：

1
2
3
4
5
6
7
8
9
# 场景 1：自然语言触发
"帮我审查一下最近的代码变更"

# 场景 2：斜杠命令触发
/code-review

# 场景 3：修改后重载
# 修改 SKILL.md 后保存，新会话自动生效
# 当前会话可以用 /plugin disable 再 /plugin enable 重载

十、常见问题

Q1：Skills 和 CLAUDE.md 有什么区别？

CLAUDE.md 是项目的背景知识（技术栈、架构、命名约定），Skills 是可执行的工作流程（怎么做某事）。两者互补。

Q2：装太多技能会影响性能吗？

不会。Claude 仅在启动时加载技能的 name 和 description（约 100 tokens/技能），完整内容只有在触发时才加载。装 50-100 个技能对性能影响微乎其微。

Q3：技能文件写得不好，Claude 会跳过吗？

会。如果技能指令模糊或前后矛盾，Claude 可能部分忽略或执行不到位。建议参考社区优秀技能（如 Superpowers）的写法。

Q4：如何共享我写的技能？

  • 上传到 GitHub 仓库
  • 分享给他人直接复制到 ~/.claude/skills/
  • 打包为 Plugin 发布到社区市场

Q5：技能可以在不同 AI 工具间通用吗？

可以！SKILL.md 是开放标准（Agent Skills open standard），兼容 Claude Code、Codex CLI、Cursor、OpenCode、Gemini CLI 等 30+ 工具。

Q6：技能的执行顺序可以控制吗？

不能直接控制顺序，但可以通过以下方式实现：

  • 在技能指令中引用其他技能的名称
  • 使用 context: fork 让子代理串行执行
  • 用钩子触发后续操作

总结

Claude Code 的技能系统是 2026 年 AI 编程领域最重要的进化之一。它的核心价值不在于安装了多少社区技能，而在于：

  1. 将最佳实践固化——不再依赖”记住要这样做”，而是让 AI 自动执行
  2. 定制化工作流——团队规范、个人习惯、项目约束都可以编码为技能
  3. 开放生态——SKILL.md 标准让技能跨平台通用

入门三步走：

1
2
3
4
5
6
7
8
9
10
# 第一步：熟悉内置命令
/review && /plan && /compact

# 第二步：安装核心社区技能
/plugin marketplace add obra/superpowers
/plugin install superpowers

# 第三步：为自己写第一个自定义技能
mkdir -p ~/.claude/skills/my-first-skill
vim ~/.claude/skills/my-first-skill/SKILL.md

从今天开始，每次你发现 Claude “总是做错”某件事时，与其手动纠正，不如花 15 分钟写一个技能——它在未来会为你省下无数个 15 分钟。

本文首发于 CaoZH 的笔记

CaoZHProgrammer

学习使我快乐。