Claude Code的Skill应用教程

主流Agent安装与使用 2026-08-01 22:39 eogee.com 教程团队催更本节视频 0次 206 次阅读 0次收藏

Skill（技能）是 Claude Code 中最重要的行为定制机制之一，本质上是预定义的指令模板，告诉 Claude "应该以什么方式工作"。本教程通过实战案例讲解如何在 Claude Code 中创建、配置和使用 Skill，帮助你用 Skill 规范 Claude Code 的行为，提升学习和工作效率。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

ClaudeCode安装及配置国内大模型完整教程，确保 Claude Code 已正确安装并可正常使用。
Skill概念详解，此内容详细介绍了 Skill 的基本概念及与其他相关概念的对比。

资源下载

Skill 示例 mermaid2img 源码下载 — 包含 mermaid2img 实战 Skill 示例

1. Skill 的基本概念

在 Claude Code 中，Skill（技能） 是一组预定义的指令模板，在会话启动时注入到 Claude 的系统提示中，作为行为指令的一部分。

Skill 告诉 Claude "怎么做"——定义行为方式和输出规范
Skill 运行在主线会话中，不创建独立的子进程
Skill 的效果在调用后持续影响后续对话

关于 Skill的概念详解你可以前往前置教程回顾：Skill概念详解。

2. Claude Code 中 Skill 的创建与配置

2.1 Skill 文件结构

一个完整的 Skill 文件可以包含以下组件：

.claude/skills/
└── my-skill/
    ├── SKILL.md              # 主指令文件（必需）
    ├── references/           # 参考资料目录（可选）
    │   ├── template.yaml     # 模板文件
    │   └── examples.md       # 示例参考
    └── scripts/              # 辅助脚本（可选）
        └── validate.sh       # 验证脚本

my-skill 即为你的 Skill 名称，在 Claude Code 中，你可以通过/my-skill/调用它。

2.2 SKILL.md 文件格式

SKILL.md 文件由两部分组成：

第一部分：Frontmatter（元数据）

位于文件开头 --- 分隔的 YAML 块中：

---
name: skill-name              # 技能名称（必填）
description: 简短描述技能用途    # 描述（必填）
disable-model-invocation: true # 仅用户可调用（可选，默认 false）
user-invocable: false          # 仅 Claude 自动调用（可选，默认 true）
allowed-tools: Read, Grep, Glob # 限制工具访问（可选）
context: fork                  # 在隔离子代理中运行（可选）
agent: Explore                 # 隔离时使用的代理类型（可选）
---

Frontmatter 参数详解：

参数	必填	默认值	说明
`name`	是	—	Skill 名称，同时也是 `/name` 调用时的标识
`description`	是	—	简短描述，Claude 据此自动匹配合适的 Skill
`disable-model-invocation`	否	`false`	设为 `true` 时只有用户可主动调用，适用于有副作用的操作
`user-invocable`	否	`true`	设为 `false` 时只有 Claude 可自动调用，适用于后台知识
`allowed-tools`	否	继承主线	限制 Skill 可使用的工具列表
`context`	否	—	设为 `fork` 时在隔离的子代理中运行
`agent`	否	—	指定 `context: fork` 时使用的代理类型

第二部分：正文（指令内容）

Frontmatter 之后的内容就是 Skill 的指令正文，使用 Markdown 格式编写：

## 任务描述

当你收到 `$ARGUMENTS` 相关的任务时，按以下步骤执行：

### 步骤 1：分析需求
- 理解用户的具体需求
- 确定需要使用的工具

### 步骤 2：执行
- 按约定的规范和格式输出
- 使用参考模板（如果有）

### 输出格式
- 确保输出符合约定的格式标准

2.3 调用控制组合

通过 disable-model-invocation 和 user-invocable 两个参数组合，可以精确控制 Skill 的调用方式：

`disable-model-invocation`	`user-invocable`	用户调用	Claude 自动调用	适用场景
`false`（默认）	`true`（默认）	✓	✓	通用 Skill
`true`	`true`（默认）	✓	✗	有副作用的操作（部署、发送消息）
`false`（默认）	`false`	✗	✓	后台知识（编码规范、项目约定）
`true`	`false`	✗	✗	无意义组合，不会触发

3. Skill 的调用方式

3.1 用户主动调用

在对话中直接输入 /skill-name 即可调用已注册的 Skill：

/code-review 审查 src/main.py 的代码

/api-doc 生成 user API 端点的文档

调用效果：

❯ /code-review 审查 src/main.py 的代码

  Skill "code-review" 已加载。（指令已注入到当前会话）

  (Claude 按照 code-review Skill 定义的步骤和标准执行审查)

3.2 Claude 自动调用

当 Claude 判断当前任务与某个 Skill 的 description 匹配时，会自动加载该 Skill 的指令。以下情况会触发自动调用：

用户提出的问题与 Skill 描述高度相关
当前操作涉及 Skill 定义的领域

例如，如果有一个 python-style Skill 描述了 Python 编码规范，当用户让 Claude 编写 Python 代码时，该 Skill 会自动生效。

3.3 参数传递

向 Skill 传递参数有两种方式：

方式一：直接在命令后跟参数

/api-doc user/login 接口

参数 user/login 接口 会以 $ARGUMENTS 变量形式注入到 Skill 指令中。

方式二：在对话中提供上下文

/code-review
请审查以下代码：
def add(a, b):
    return a + b

Skill 指令注入后，对话中的后续内容都会受其影响。

4. Skill 实战案例

本教程项目包含一个实战 Skill 示例：mermaid2img，用于将文档中的 Mermaid 图表转换为 PNG 图片。

4.1 Skill 的获取与安装

点击进入Skill 示例 mermaid2img 源码下载，下载并解压 Skill 源码压缩包。
创建 Skill 目录：在你的项目中创建 .claude/skills/ 目录（如果不存在）：

mkdir -p .claude/skills

复制 Skill 文件：将源码文件复制到对应目录：

# 复制 mermaid2img Skill
cp -r .claude/skills/mermaid2img .claude/skills/

验证安装：确认 Skill 文件结构正确：

.claude/skills/
└── mermaid2img/
    ├── SKILL.md              # Skill 定义文件
    ├── README.md             # 使用说明文档
    └── scripts/              # 脚本目录
        ├── main.js           # 主脚本，整合所有功能
        ├── validate-mermaid.js  # 验证并清理 Mermaid 代码
        ├── find-diagram-placeholders.js  # 查找 Mermaid 代码块
        ├── extract-diagram-info.js      # 提取图表信息
        ├── create-assets-dir.js         # 创建 assets 目录
        └── replace-diagram-with-image.js # 替换代码块

安装后生效：Skill 安装完成后，立即在当前 Claude Code 会话中生效。如果 Claude Code 已在运行，重新启动后会话即可使用新安装的 Skill。

4.2 验证 mermaid2img

网盘文件中包含了一个mermaid-test.md,其中包含了多个Mermaid图表，我们可以通过Skill来将这些图表转换为PNG图片。

在 Claude Code 中输入以下命令：

/mermaid2img

Claude Code 会自动加载 mermaid2img Skill，并执行转换操作。
观察Claude Code 的输出，可以看到所有 Mermaid 图表都被成功转换为 PNG 图片。

验证 mermaid2img示意图

5. Skill 最佳实践

5.1 设计原则

原则	说明
单一职责	每个 Skill 只做一件事，一个 Skill 对应一个明确的行为规范
指令明确	使用具体的步骤和标准，避免模糊的描述
可验证	Skill 执行结果应可判断是否符合预期
简洁	正文控制在 50 行以内，过长的指令会占用过多上下文
参数化	使用 `$ARGUMENTS` 接收输入，避免在 Skill 中硬编码

5.2 命名规范

Skill 名称使用小写字母加连字符：code-review、api-doc、data-analysis
名称要能直观反映 Skill 的用途
避免与内置命令重名

5.3 常见误区

误区	正确做法
把 Skill 当 Agent 用，期望它并发执行	Skill 在主线运行，并发应使用 Agent 或 Workflow
Skill 指令写得过于冗长	保持指令精炼，过长会消耗上下文窗口
在 Skill 中使用绝对路径引用资源	使用相对路径，确保项目迁移后仍可用
期望 Skill 跨对话持久生效	Skill 只在当前对话有效，新对话重新加载

6 常见问题与解答

Q1: Skill 文件修改后需要重启 Claude Code 吗？

不需要。Skill 文件在每次调用时重新加载，修改后直接在对话中再次调用 /skill-name 即可使用更新后的指令。

Q2: 一个项目可以创建多少个 Skill？

没有数量限制。但建议每个项目保持 3-5 个核心 Skill，过多的 Skill 会增加 Claude 自动匹配时的选择开销。

Q3: Skill 可以在多个项目间共享吗？

可以。有两种方式：

在全局配置 ~/.claude 中注册，所有项目共享
在不同项目的 .claude 中分别注册（推荐，便于版本控制）

举手提问

0/1000