Skills 概述

Overview of Claude Code Skills System

Claude Code Skills（技能）是一种强大的扩展机制，允许你将常用的工作流、指令和工具封装为可复用的模块。本章将全面介绍 Skills 系统的核心概念、运行机制和使用方式。

Skills 是什么

What Are Skills

Skills 是动态加载的指令文件夹，每个 Skill 包含一个核心描述文件 SKILL.md 以及可选的脚本、模板和资源文件。与传统的静态配置不同，Skills 只在需要时才被加载到上下文中，从而节省宝贵的 Token 预算。

一个 Skill 本质上是一组结构化的指令集合，它告诉 Claude：

做什么：任务的具体目标和步骤
怎么做：执行任务时应遵循的规则和约束
用什么：需要调用的工具、脚本或模板

简单理解：Skill = 指令 + 资源 + 触发方式

核心特性

Core Features

特性	说明
按需加载	只在触发时加载到上下文，节省 Token
模块化	每个 Skill 独立封装，互不干扰
可复用	一次编写，多次使用，可跨项目共享
可扩展	支持脚本集成，灵活性极高
可分享	可发布到技能市场供他人使用

Skills vs CLAUDE.md 的区别

Skills vs CLAUDE.md: Key Differences

你可能已经熟悉 CLAUDE.md 文件——它是 Claude Code 的全局指令文件。Skills 与它有本质区别：

对比维度	CLAUDE.md	Skills
加载时机	每次会话都加载	按需加载
Token 消耗	始终占用上下文空间	仅在激活时消耗
适用范围	项目级通用规则	特定任务或工作流
组织方式	单一文件	独立文件夹，含多个文件
触发方式	自动加载	模型判断或用户命令
可分享性	项目内共享	可发布到技能市场

何时使用 CLAUDE.md

When to Use CLAUDE.md

项目编码规范（如代码风格、命名约定）
始终需要遵守的安全规则
项目架构说明和上下文信息
通用的工作流偏好设置

何时使用 Skills

When to Use Skills

特定任务的详细操作流程（如代码审查、生成提交信息）
需要模板文件或脚本辅助的工作流
希望与团队或社区共享的实用工具
不常使用但流程复杂的操作

markdown

# 示例：CLAUDE.md 中的通用规则
## 编码规范
- 使用 TypeScript strict 模式
- 所有函数必须有 JSDoc 注释
- 变量命名使用 camelCase

# 示例：Skill 中的特定任务
## /review 代码审查技能
1. 读取 git diff
2. 按安全性、性能、可读性分类检查
3. 生成结构化审查报告

两种调用方式

Two Invocation Methods

Skills 支持两种触发方式，通过 SKILL.md 中的 invocable_by 字段控制。

模型调用（Model-Invocable）

Model-Invocable Skills

当 invocable_by 设置为 model 或 both 时，Claude 会根据对话上下文自动判断是否需要激活该 Skill。

yaml

---
name: code-review
description: 审查代码质量、安全性和性能
invocable_by: model
---

工作流程：

用户发送消息（如"帮我检查这段代码"）
Claude 分析消息意图
Claude 匹配到 code-review 技能的描述
自动加载并执行该 Skill 的指令

适用场景：

常见的开发任务（代码审查、重构建议）
与自然语言描述高度匹配的操作
希望无缝集成到对话流中的功能

用户调用（User-Invocable）

User-Invocable Skills

当 invocable_by 设置为 user 或 both 时，用户可以通过斜杠命令直接触发。

yaml

---
name: commit
description: 分析变更并生成规范的提交信息
invocable_by: user
---

使用方式：

bash

# 在 Claude Code 会话中输入：
/commit

# 或带参数：
/commit --scope=feat --no-emoji

适用场景：

需要用户明确意图的操作（如提交代码、发布版本）
带有可选参数的复杂工作流
不希望被自动触发的敏感操作

调用方式对比

Invocation Method Comparison

调用方式	invocable_by 值	触发条件	典型用例
模型调用	`model`	Claude 自动判断	代码分析、建议优化
用户调用	`user`	`/skill-name` 命令	提交代码、项目初始化
双重调用	`both`	两种方式均可	文档生成、测试编写

Skill 文件夹结构

Skill Folder Structure

每个 Skill 是 .claude/skills/ 下的一个独立文件夹。标准结构如下：

.claude/skills/my-skill/
├── SKILL.md          # 核心：技能描述和指令（必需）
├── template/         # 可选：模板文件
│   ├── component.tsx
│   └── test.spec.ts
├── scripts/          # 可选：辅助脚本
│   ├── validate.sh
│   └── transform.py
└── assets/           # 可选：其他资源
    └── config.json

各目录说明

Directory Descriptions

目录/文件	必需	说明
`SKILL.md`	是	技能的核心描述文件，包含 frontmatter 和指令
`template/`	否	存放代码模板、文件模板等
`scripts/`	否	存放辅助脚本（Bash、Python、Node.js 等）
`assets/`	否	存放配置文件、数据文件等资源

文件夹命名规范

Folder Naming Convention

✅ 推荐                    ❌ 避免
my-skill                  mySkill
code-review               CodeReview
project-init              project_init
doc-translate             Doc Translate

使用小写字母和连字符分隔
名称应简洁且具有描述性
避免使用空格、下划线或大驼峰命名

SKILL.md 文件格式

SKILL.md File Format

SKILL.md 是每个 Skill 的核心文件，由 frontmatter（元数据）和正文（指令内容）两部分组成。

Frontmatter 字段

Frontmatter Fields

yaml

---
name: my-skill              # 技能名称，用于命令调用
description: 简短描述该技能的用途    # 技能描述，帮助 Claude 判断何时使用
invocable_by: user           # 调用方式：model / user / both
---

字段	类型	必需	说明
`name`	string	是	技能的唯一标识符，也是斜杠命令名
`description`	string	是	技能用途的简短描述
`invocable_by`	string	是	调用方式：`model`、`user` 或 `both`

正文编写规范

Body Writing Guidelines

frontmatter 之后的正文部分就是 Skill 的具体指令。编写时应注意：

markdown

---
name: review
description: 代码审查，检查质量和安全性
invocable_by: both
---

## 任务说明

你是一个代码审查专家。当被要求审查代码时，请按以下步骤执行：

### 步骤一：获取变更

1. 使用 `git diff` 获取当前变更
2. 如果指定了特定文件，只审查这些文件

### 步骤二：审查维度

按以下维度检查代码：

- **安全性**：是否存在注入、泄露等安全隐患
- **性能**：是否有明显的性能问题
- **可读性**：代码是否清晰易懂
- **规范性**：是否符合项目编码规范

### 步骤三：输出报告

以 Markdown 表格形式输出审查结果。

Skills 的加载机制和生命周期

Loading Mechanism and Lifecycle

理解 Skill 的加载流程有助于编写高效的技能：

┌─────────────┐
│  会话开始    │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│  扫描 Skills 目录 │  ← 读取所有 SKILL.md 的 frontmatter
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  注册可用 Skills  │  ← 建立名称→路径映射，不加载正文
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  等待触发         │  ← 监听用户命令或分析对话意图
└──────┬──────────┘
       │ （触发）
       ▼
┌─────────────────┐
│  加载 Skill 正文  │  ← 读取完整 SKILL.md 内容
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  执行指令         │  ← 按照 Skill 中的步骤执行任务
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  任务完成         │  ← Skill 上下文可被释放
└─────────────────┘

关键点

Key Points

延迟加载：启动时只读取 frontmatter（几十个字节），不加载正文内容
按需激活：只有在匹配到触发条件时才读取完整指令
上下文管理：Skill 指令加载后进入当前会话上下文
资源引用：Skill 中引用的模板和脚本在执行时按需读取

与 MCP Tools 的关系

Relationship with MCP Tools

Skills 和 MCP（Model Context Protocol）Tools 是互补的两种扩展机制：

对比维度	Skills	MCP Tools
本质	指令集合（文本）	可调用的函数/API
运行环境	Claude 上下文内	外部服务器进程
扩展方式	编写 Markdown 指令	实现 MCP 协议的服务
能力范围	编排已有工具和流程	提供新的原子操作能力
复杂度	低（纯文本）	中高（需要编程）

协同使用

Using Together

Skills 可以在指令中引用 MCP Tools，实现强大的组合效果：

markdown

---
name: design-review
description: 审查 UI 设计稿并提供反馈
invocable_by: user
---

## 执行步骤

1. 使用 MCP 工具 `take_screenshot` 截取当前页面
2. 分析设计元素的布局、配色和一致性
3. 对比设计规范文件（位于 `./design-system/`）
4. 生成审查报告并提出改进建议

在这个例子中，Skill 作为编排层，调度 MCP Tool 提供的底层能力来完成复杂任务。

快速上手

Quick Start

以下是创建和使用第一个 Skill 的最简步骤：

bash

# 1. 创建 Skill 文件夹
mkdir -p .claude/skills/hello

# 2. 创建 SKILL.md
cat > .claude/skills/hello/SKILL.md << 'EOF'
---
name: hello
description: 打招呼并介绍自己
invocable_by: user
---

## 指令

当用户触发此技能时：

1. 用中文友好地打招呼
2. 介绍你是 Claude Code 助手
3. 列出当前项目的基本信息（语言、框架、文件数）
EOF

# 3. 在 Claude Code 中使用
# 输入 /hello 即可触发

小结

Summary

概念	要点
Skills 定义	动态加载的指令文件夹
核心文件	SKILL.md（frontmatter + 指令正文）
调用方式	模型自动调用 / 用户斜杠命令 / 两者兼有
与 CLAUDE.md 区别	按需加载，节省 Token，任务专用
与 MCP Tools 关系	Skills 编排指令，MCP 提供原子能力
文件夹位置	`.claude/skills/<skill-name>/`

下一章我们将介绍如何从技能市场发现和安装现成的 Skills。

Skills 概述 ​

Skills 是什么 ​

核心特性 ​

Skills vs CLAUDE.md 的区别 ​

何时使用 CLAUDE.md ​

何时使用 Skills ​

两种调用方式 ​

模型调用（Model-Invocable） ​

用户调用（User-Invocable） ​

调用方式对比 ​

Skill 文件夹结构 ​

各目录说明 ​

文件夹命名规范 ​

SKILL.md 文件格式 ​

Frontmatter 字段 ​

正文编写规范 ​

Skills 的加载机制和生命周期 ​

关键点 ​

与 MCP Tools 的关系 ​

协同使用 ​

快速上手 ​

小结 ​

Skills 概述

Skills 是什么

核心特性

Skills vs CLAUDE.md 的区别

何时使用 CLAUDE.md

何时使用 Skills

两种调用方式

模型调用（Model-Invocable）

用户调用（User-Invocable）

调用方式对比

Skill 文件夹结构

各目录说明

文件夹命名规范

SKILL.md 文件格式

Frontmatter 字段

正文编写规范

Skills 的加载机制和生命周期

关键点

与 MCP Tools 的关系

协同使用

快速上手

小结