Claude Code Skill 开发指南

概述

上次学了 Claude Code Skills 的基本机制（怎么用），这次深入学习了怎么自己开发一个 Skill。通过实际创建一个代码审查 Skill（/review），掌握了 Skill 的设计原则和开发技巧。

为什么要自己开发 Skill？

Claude Code 虽然很强大，但每次都需要你用自然语言描述需求。如果某个工作流你经常重复做（比如代码审查、生成测试、写日志），每次都重新描述既麻烦又容易遗漏步骤。

自己开发 Skill 的好处：

• 一致性：每次执行的流程和标准都一样，不会因为你描述得不够详细而遗漏
• 效率：一个 /review 命令搞定，不需要每次解释"帮我检查安全漏洞、代码质量、拼写错误……"
• 可复用：写一次，永远受益；还可以分享给团队

Skill 文件的完整结构

~/.claude/skills/
└── my-skill/
    └── SKILL.md          # 技能定义文件

文件格式：YAML frontmatter + Markdown 正文

---
name: review
description: 代码审查 — 检查质量、安全漏洞、格式等问题
---
 
你是一个代码审查助手。
 
## 操作流程
 
### 第一步：确定审查范围
（详细步骤……）
 
### 第二步：执行审查
（详细步骤……）

Skill 的核心要素

1. 参数解析

用户调用 Skill 时可以传入参数，通过 $ARGUMENTS 变量接收：

/review src/utils/auth.ts          → 审查指定文件
/review --staged                    → 审查暂存区的改动
/review                             → 默认审查最近的 git diff

在 Skill 文件中这样处理：

### 第一步：确定审查范围
 
- 如果 $ARGUMENTS 包含文件路径 → 审查指定文件
- 如果 $ARGUMENTS 包含 --staged → 审查 git 暂存区
- 如果 $ARGUMENTS 为空 → 审查最近一次提交的改动

设计要点：提供合理的默认行为，让用户不传参也能正常工作。

2. 流程设计

把整个工作流拆成清晰的步骤，每步职责单一：

## 操作流程
 
### 第一步：确定审查范围
（获取要审查的代码）
 
### 第二步：检测项目技术栈
（识别框架、语言，决定审查规则）
 
### 第三步：执行多维度审查
（逐项检查问题）
 
### 第四步：生成报告
（按严重程度分级输出）
 
### 第五步：确认后自动修复
（询问用户是否自动修复可修复项）

设计要点：步骤之间有明确的先后顺序，每步的输入和输出清晰。

3. 工具调用

在 Markdown 中描述什么时候该用什么工具：

### 第一步：确定审查范围
 
1. 用 Bash 工具执行 `git diff` 获取改动
2. 用 Read 工具读取指定文件内容
3. 用 Glob 工具查找匹配模式的文件

Claude 会根据这些指令自动调用对应的工具。

4. 输出格式

定义结构化的输出模板，保证每次输出格式统一：

### 输出格式
 
#### 🔴 严重问题（必须修复）
- [文件名:行号] 问题描述
 
#### 🟡 可改进（建议修复）
- [文件名:行号] 问题描述
 
#### 💡 建议（可选优化）
- [文件名:行号] 问题描述

5. 交互规则

明确什么时候该问用户，什么时候可以自动执行：

## 交互规则
 
- 发现严重安全漏洞时立即告知用户
- 自动修复前必须列出改动内容并征得同意
- 不确定是否为误报时标注"待确认"

设计原则

实践案例：代码审查 Skill

我们实际创建了一个 /review Skill，以下是它的功能设计：

支持的审查范围

/review                        → 审查最近的 git diff
/review --staged               → 审查暂存区（即将提交的改动）
/review --commit abc123        → 审查指定 commit
/review src/utils/auth.ts      → 审查指定文件

6 大审查维度

工作流程

用户输入 /review
      ↓
解析参数，确定审查范围
      ↓
检测项目技术栈（React? Vue? TypeScript?）
      ↓
逐维度检查代码
      ↓
按严重程度分级生成报告
      ↓
询问用户：是否自动修复可修复项？
      ↓
用户确认后，自动应用修复

开发 Skill 的常见问题

Q：Skill 和直接对话有什么区别？

Skill 本质上就是一个预写好的 prompt。区别在于：直接对话需要你每次描述需求，Skill 把描述固化成文件，一键触发。就像函数封装——把重复的逻辑抽出来。

Q：Skill 太多会有问题吗？

会。Claude Code 启动时会加载所有 Skill 的描述，太多 Skill 会：

1. 占用上下文窗口
2. 增加匹配歧义（Claude 不知道该用哪个）

建议控制在 10-15 个以内，每个 Skill 的 description 要写得精确，避免功能重叠。

Q：怎么测试 Skill？

直接调用 /skill-name，观察 Claude 是否按预期步骤执行。如果有问题，修改 SKILL.md 文件后重新调用即可，不需要重启。

参考

• Claude Code 官方文档
• Claude Code Custom Slash Commands