Claude Code Skills 完全指南：创建你的第一个技能

你是否曾想过让 Claude Code 按照你的方式工作？是否希望能有一个专属的命令来完成特定的重复任务？

好消息来了——Claude Code Skills 正是为此而设计！

什么是 Skills？

Skills 是扩展 Claude 能力的秘密武器。你可以创建一个 SKILL.md 文件，写入你的指令，Claude 会自动将其添加到工具箱中。

两种调用方式：

手动调用：输入 /skill-name 直接触发
自动加载：当对话内容与 skill 描述匹配时，Claude 会自动加载

⚡ Skills 遵循 Agent Skills 开放标准，可跨多个 AI 工具使用。Claude Code 还扩展了调用控制、子代理执行和动态上下文注入等高级功能。

创建你的第一个 Skill

让我们创建一个教 Claude 用可视化图表和类比来解释代码的技能：

步骤 1：创建技能目录

1	mkdir -p ~/.claude/skills/explain-code

步骤 2：编写 SKILL.md

---
name: explain-code
description: 用可视化图表和类比解释代码。用于解释代码工作原理、教学代码库，或用户问"这是怎么工作的？"
---

解释代码时，始终包含：

1. **从类比开始**：将代码与日常生活中的事物进行比较
2. **绘制图表**：用 ASCII 艺术展示流程、结构或关系
3. **逐步讲解**：逐步解释代码发生了什么
4. **强调陷阱**：常见的错误或误解是什么

保持解释的对话感。对于复杂概念，使用多个类比。

步骤 3：测试技能

方式一：让 Claude 自动调用

1	这段代码是怎么工作的？

方式二：直接调用

1	/explain-code src/auth/login.ts

无论哪种方式，Claude 都会在解释中包含类比和 ASCII 图表。

Skills 存放位置

位置	路径	适用范围
Enterprise	托管设置中	组织内所有用户
Personal	~/.claude/skills/<skill-name>/SKILL.md	所有项目
Project	.claude/skills/<skill-name>/SKILL.md	仅当前项目
Plugin	<plugin>/skills/<skill-name>/SKILL.md	插件启用处

当多个位置存在同名 skill 时，优先级：Enterprise > Personal > Project

自动发现嵌套目录

在 monorepo 环境中，Claude Code 会自动发现子目录中的 skills。例如，在 packages/frontend/ 中编辑文件时，Claude 也会查找 packages/frontend/.claude/skills/ 中的 skills。

Skill 目录结构

my-skill/
├── SKILL.md           # 主指令（必需）
├── template.md        # Claude 填充的模板
├── examples/
│   └── sample.md      # 展示预期格式的示例
└── scripts/
    └── validate.sh    # Claude 可执行的脚本

💡 保持 SKILL.md 在 500 行以内。将详细参考材料移到单独的文件中。

Frontmatter 配置详解

字段	必需	描述
`name`	否	显示名称（小写字母、数字和连字符，最多64字符）
`description`	推荐	技能用途和调用时机
`argument-hint`	否	自动完成时显示的参数提示
`disable-model-invocation`	否	设为 true 禁止 Claude 自动调用
`user-invocable`	否	设为 false 从 / 菜单隐藏
`allowed-tools`	否	技能激活时允许使用的工具
`model`	否	技能激活时使用的模型
`context`	否	设为 fork 在分支子代理中运行
`agent`	否	context: fork 时指定子代理类型

调用控制

# 只允许你手动调用，Claude 不会自动触发
---
name: deploy
description: 部署应用到生产环境
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:
1. 运行测试套件
2. 构建应用
3. 推送到部署目标
4. 验证部署成功

# 只允许 Claude 调用，用户不能通过 / 命令触发
---
name: legacy-system-context
description: 解释旧系统的工作方式
user-invocable: false
---

字符串替换

Skills 支持动态值替换：

变量	描述
`$ARGUMENTS`	调用时传递的所有参数
`$ARGUMENTS[N]`	按索引访问参数（从0开始）
`$N`	$ARGUMENTS[N] 的简写
`${CLAUDE_SESSION_ID}`	当前会话ID

示例：

---
name: migrate-component
description: 将组件从一个框架迁移到另一个框架
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

运行 /migrate-component SearchBar React Vue 时：

$0 → SearchBar
$1 → React
$2 → Vue

高级特性

1. 动态上下文注入

使用 ```command`` 语法在技能运行前执行 shell 命令：

---
name: pr-summary
description: 总结 Pull Request 的更改
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull Request 上下文
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## 你的任务
总结这个 Pull Request...

2. 子代理执行

添加 context: fork 在隔离的子代理中运行技能：

---
name: deep-research
description: 深入研究一个主题
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. 使用 Glob 和 Grep 查找相关文件
2. 阅读和分析代码
3. 总结发现，包含具体文件引用

3. 工具限制

使用 allowed-tools 限制技能激活时 Claude 可用的工具：

---
name: safe-reader
description: 只读模式查看文件，不做任何修改
allowed-tools: Read, Grep, Glob
---

4. 生成视觉输出

Skills 可以捆绑和运行脚本，生成交互式 HTML：

---
name: codebase-visualizer
description: 生成代码库的可交互树状可视化。用于探索新仓库、理解项目结构或识别大文件。
allowed-tools: Bash(python *)
---

# Codebase Visualizer

从项目根目录运行可视化脚本：

```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .

这会在当前目录创建 codebase-map.html 并在浏览器中打开。


## 故障排除

### Skill 不触发

如果 Claude 没有在预期时使用你的技能：

1. 检查 description 是否包含用户会自然说的关键词
2. 验证技能是否出现在 "What skills are available?" 中
3. 尝试重新表述请求，使其更贴近 description
4. 如果 skill 是用户可调用的，直接用 /skill-name 调用

### Skill 触发过于频繁

如果 Claude 在你不希望时使用技能：

1. 使 description 更具体
2. 如果只想手动调用，添加 `disable-model-invocation: true`

### Claude 看不到所有技能

技能描述会加载到上下文中以便 Claude 知道可用技能。如果技能很多，可能超出字符预算。预算动态缩放为上下文窗口的 2%，回退值为 16,000 字符。

## 总结

Claude Code Skills 为你打开了一扇大门，让你能够：

- 🎯 创建自定义命令，完成特定任务
- 🔄 实现工作流程自动化
- 📦 打包和分享可复用的技能
- 🚀 扩展 AI 助手的能力边界

**下一步：**

1. 创建一个简单的 skill 试试手
2. 探索官方文档获取更多灵感
3. 在项目中分享你的 skill

> 记住：好的 skill 应该是专注的、可组合的，并且能够解决真实问题。从小处着手，逐步迭代！

---

*本文基于 Claude Code 官方文档编写，完整内容请参考 [Extend Claude with skills](https://code.claude.com/docs/en/skills)*