Chen Yulin's Blog

Claude Code Skills 使用指南

官方文档 | Agent Skills 标准

---

概述

Skills（技能） 是扩展 Claude Code 能力的自定义工作流。通过 Markdown 文件定义，可以用斜杠命令调用或自动加载。
Skills 遵循开放的 Agent Skills 标准，可跨多个 AI 工具使用。

---

核心概念

Skills 的作用

• 自定义斜杠命令：直接调用专门的工作流（如 /commit、/review）
• 领域知识注入：为 Claude 提供特定领域的上下文
• 任务指令：定义复杂操作的步骤流程
• 工具集成：连接外部工具和脚本

文件结构

skill-name/
├── SKILL.md          # 必需：主要技能定义
├── reference.md      # 可选：详细文档
├── examples.md       # 可选：使用示例
└── scripts/          # 可选：辅助脚本

---

Skill 位置与作用域

位置	路径	作用域
个人级	~/.claude/skills/<skill-name>/SKILL.md	用户所有项目
项目级	.claude/skills/<skill-name>/SKILL.md	仅当前项目
企业级	通过设置管理	组织范围

优先级：项目级 > 个人级 > 企业级

---

创建 Skill

基本结构

最简单的 skill 只需一个带 YAML 头的 SKILL.md 文件：

---
name: explain-code
description: 用图表和类比解释代码。当用户询问"这段代码如何工作"时使用
---

解释代码时，始终包含：

1. **类比**：用日常生活中的事物比喻代码
2. **图表**：用 ASCII 艺术展示流程或结构
3. **逐步讲解**：���释每一步发生了什么
4. **常见误区**：指出容易混淆的点

配置选项 (Frontmatter)

字段	类型	说明
name	string	显示名称（成为 /斜杠命令）
description	string	功能描述 - 用于自动调用判断
disable-model-invocation	boolean	为 true 时仅用户可调用（禁止自动加载）
user-invocable	boolean	为 false 时仅 Claude 可调用（菜单中隐藏）
allowed-tools	array	Claude 可使用的工具列表（无需权限提示）
context	string	设为 fork 在隔离的子代理中运行
agent	string	指定代理类型（如 Explore、Plan）
argument-hint	string	自动补全提示（如 [issue-number]）

---

调用方式

1. 直接调用

用户显式使用斜杠命令：

/skill-name
/fix-issue 123
/explain-code src/auth/login.ts

2. 自动调用

当用户请求匹配 skill 的 description 时，Claude 自动加载：

用户："这个认证流程是如何工作的？"
→ Claude 自动加载 /explain-code skill

控制自动调用：

• 设置 disable-model-invocation: true 禁止自动加载
• 让 description 更具体以避免误触发

---

传递参数

使用 $ARGUMENTS

$ARGUMENTS 占位符捕获所有参数为单个字符串：

---
name: fix-issue
description: 修复 GitHub issue
---

修复 GitHub issue $ARGUMENTS，遵循我们的编码标准。

1. 从 GitHub 读取 issue 描述
2. 理解需求
3. 实现修复
4. 编写测试
5. 创建提交

用法：/fix-issue 123 → “修复 GitHub issue 123…”

使用位置参数

用 $0、$1、$2 等访问单个参数：

---
name: migrate-component
description: 在框架间迁移组件
argument-hint: [组件名] [源框架] [目标框架]
---

将 $0 组件从 $1 迁移到 $2。

要求：
- 保留所有现有行为
- 维持测试覆盖率
- 更新文档

用法：/migrate-component SearchBar React Vue

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

---

高级模式

动态上下文注入

使用反引号`和 ! 在 skill 运行前执行 shell 命令：

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

## Pull Request 上下文

**差异：**
!`gh pr diff`

**评论：**
!`gh pr view --comments`

## 任务

总结这个 PR，重点关注：
1. 主要变更及其目的
2. 审查者的潜在关注点
3. 测试覆盖情况

隔离子代理执行

在隔离上下文中运行 skill，避免污染主对话：

---
name: deep-research
description: 深入研究某个主题而不影响主上下文
context: fork
agent: Explore
---

深入研究 $ARGUMENTS：

1. 使用 Glob 和 Grep 查找相关文件
2. 阅读并分析代码
3. 识别模式和关系
4. 用具体的文件引用（file:line 格式）总结发现

工具限制

限制 Claude 在 skill 中可使用的工具：

---
name: read-only-analysis
description: 分析代码但不做修改
allowed-tools: Read, Grep, Glob, Bash(git *)
---

分析代码库中的 $ARGUMENTS。

你只能读取文件和运行 git 命令。
不要修改任何文件。

---

最佳实践

Skill 设计原则

1. 单一职责：每个 skill 应有一个明确目的
2. 清晰描述：description 应匹配用户的自然语言
3. 明确指令：为复杂工作流提供分步指导
4. 错误处理：包含常见失败场景的处理说明

命名规范

• 使用小写加连字符：fix-issue、explain-code
• 保持简短易记
• 使用动词导向的名称

---

示例 Skills

代码审查

---
name: review
description: 对变更进行全面的代码审查
disable-model-invocation: true
allowed-tools: Read, Grep, Bash(git *)
---

执行全面的代码审查：

## 审查清单

1. **正确性**：代码是否实现了预期功能？
2. **安全性**：是否存在安全漏洞？
3. **性能**：是否有明显的性能问题？
4. **可维护性**：代码是否可读且结构良好？
5. **测试**：测试覆盖是否充分？

## 流程

1. 运行 `git diff` 查看所有变更
2. 完整阅读修改的文件
3. 检查常见问题：SQL 注入、XSS、命令注入、竞态条件、内存泄漏、硬编码凭证
4. 提供具体反馈，使用 file:line 引用

文档生成

---
name: document
description: 为代码生成文档
argument-hint: [文件路径]
---

为 $ARGUMENTS 生成全面的文档：

1. 阅读文件并理解其目的
2. 记录：
   - 文件概述和用途
   - 公共 API（函数、类、接口）
   - 使用示例
   - 依赖和要求
3. 格式化为 markdown
4. 在有帮助的地方包含代码示例

---

常见问题

Skill 未自动触发

问题：Claude 没有在预期时加载你的 skill。

解决方案：

• 让 description 更具体，包含用户会自然说出的关键词
• 检查 /context 确保 skill 描述未超出字符预算
• 验证 skill 文件在正确位置

Skill 触发过于频繁

问题：Skill 在不需要时加载。

解决方案：

• 让 description 更具体
• 添加 disable-model-invocation: true 要求显式调用
• 在 description 中使用更独特的关键词

参数不工作

问题：$ARGUMENTS 或 $0、$1 未被替换。

解决方案：

• 确保传递了参数：/skill-name arg1 arg2
• 检查占位符在 skill 正文中，而非仅在 frontmatter 中
• 验证占位符语法无拼写错误

---

工作流集成示例

Git 工作流

---
name: feature
description: 创建新的功能分支并进行适当设置
argument-hint: [功能名称]
---

为 $ARGUMENTS 创建新的功能分支：

1. 确保工作目录干净
2. 从 main 拉取最新变更
3. 创建分支：`feature/$ARGUMENTS`
4. 设置分支跟踪
5. 创建初始提交

测试工作流

---
name: test-fix
description: 修复失败的测试
context: fork
allowed-tools: Bash, Read, Edit
---

修复失败的测试：

1. 运行测试套件识别失败
2. 对每个失败：
   - 阅读测试文件
   - 理解测试内容
   - 阅读实现代码
   - 识别问题
   - 修复代码或更新测试
3. 重新运行测试验证
4. 创建修复提交

---

参考资源

• 官方 Skills 文档
• Agent Skills 标准
• Claude Code GitHub

---

注意事项

• Skills 评估顺序：项目级 → 个人级 → 企业级
• / 命令显示所有可用 skills 并支持自动补全
• Skills 可以在指令中调用其他 skills
• 对于耗时操作使用 context: fork 保持主上下文清洁
• Skills 支持 markdown 格式，包括表格、代码块和列表