自定义技能

Creating Custom Skills

Claude Code 允许你创建自定义技能，将常用的工作流封装为可复用的指令包。本章将从零开始，带你完成一个自定义技能的创建过程。

技能文件结构

一个完整的 Skill 文件夹结构如下：

.claude/skills/my-skill/
├── SKILL.md          # 必需：技能描述和指令
├── template/         # 可选：模板文件
│   ├── component.tsx
│   └── test.spec.ts
├── scripts/          # 可选：辅助脚本
│   └── validate.sh
└── examples/         # 可选：示例文件
    └── usage.md

最小技能 只需要一个 SKILL.md 文件即可。

SKILL.md 编写指南

Frontmatter 字段

---
name: my-code-review
description: 执行团队标准的代码审查
invocable_by: user  # user | model | both
user_command: /review-team  # 用户调用命令（invocable_by 包含 user 时必需）
---

字段	必需	说明
name	是	技能唯一标识符
description	是	技能简要描述（一句话）
invocable_by	是	调用方式：user（用户斜杠命令）、model（模型自动判断）、both
user_command	条件	用户调用的斜杠命令名，当 invocable_by 包含 user 时必需
tags	否	分类标签，如 ["review", "quality"]
version	否	版本号

指令正文编写

SKILL.md 的正文就是给 Claude 的指令。编写技巧：

---
name: component-generator
description: 生成符合团队规范的 React 组件
invocable_by: user
user_command: /gen-component
---

# 组件生成器

当用户请求生成组件时，按以下步骤执行：

## 步骤

1. 询问组件名称和类型（如果用户未提供）
2. 在 `src/components/` 目录下创建组件文件夹
3. 生成以下文件：
   - `index.tsx` — 组件实现
   - `styles.module.css` — 样式文件
   - `index.test.tsx` — 单元测试
   - `index.stories.tsx` — Storybook 故事

## 代码规范

- 使用函数组件 + TypeScript
- Props 接口命名为 `{ComponentName}Props`
- 导出方式使用命名导出
- 样式使用 CSS Modules

## 模板参考

参考 `template/` 目录下的模板文件生成代码。

编写技巧

1. 明确步骤 — 用编号列表描述执行步骤
2. 提供约束 — 说明编码规范、文件位置等约束条件
3. 引用模板 — 指向 template/ 目录中的参考文件
4. 定义输出 — 明确技能执行完成后应产生的输出

模板文件

在 template/ 目录中放置参考模板，SKILL.md 中引用：

.claude/skills/gen-component/
├── SKILL.md
└── template/
    ├── component.tsx.template
    ├── styles.module.css.template
    └── test.tsx.template

模板文件示例 (component.tsx.template)：

import React from 'react'
import styles from './styles.module.css'

export interface {{ComponentName}}Props {
  // props here
}

export function {{ComponentName}}({ ...props }: {{ComponentName}}Props) {
  return (
    <div className={styles.container}>
      {/* component content */}
    </div>
  )
}

Claude 会读取这些模板并按照模式生成实际代码。

脚本集成

技能可以包含辅助脚本，在 SKILL.md 中指示 Claude 执行：

## 验证

生成组件后，运行验证脚本：
\`\`\`bash
bash .claude/skills/gen-component/scripts/validate.sh
\`\`\`

脚本示例 (scripts/validate.sh)：

#!/bin/bash
# 验证生成的组件是否符合规范

# 检查文件是否存在
for file in index.tsx styles.module.css index.test.tsx; do
  if [ ! -f "$1/$file" ]; then
    echo "❌ Missing file: $file"
    exit 1
  fi
done

# 运行 TypeScript 类型检查
npx tsc --noEmit "$1/index.tsx"

echo "✅ Component validation passed"

调用方式详解

用户调用 (invocable_by: user)

用户通过斜杠命令手动触发：

> /gen-component Button

适用场景：明确的操作命令，如生成代码、执行检查。

模型调用 (invocable_by: model)

Claude 根据上下文自动判断是否使用该技能：

---
name: error-handler
description: 当代码中发现未处理的错误时，自动添加错误处理
invocable_by: model
---

适用场景：自动增强行为，如代码规范检查、错误处理。

混合调用 (invocable_by: both)

同时支持用户手动触发和模型自动使用。

完整示例：代码审查技能

.claude/skills/team-review/
├── SKILL.md
└── scripts/
    └── check-rules.sh

SKILL.md：

---
name: team-review
description: 按照团队标准执行代码审查
invocable_by: user
user_command: /team-review
---

# 团队代码审查

对当前的代码变更进行全面审查，检查以下方面：

## 审查清单

### 1. 代码质量
- [ ] 函数长度不超过 50 行
- [ ] 圈复杂度不超过 10
- [ ] 没有重复代码（DRY 原则）
- [ ] 变量命名清晰有意义

### 2. 安全性
- [ ] 无硬编码密钥或密码
- [ ] 输入验证充分
- [ ] SQL 查询使用参数化
- [ ] 无 XSS 风险

### 3. 性能
- [ ] 无 N+1 查询
- [ ] 大数据集有分页
- [ ] 无不必要的重渲染（React）

### 4. 测试
- [ ] 关键路径有测试覆盖
- [ ] 边界条件有测试

## 输出格式

以 Markdown 清单形式输出审查结果，每个问题标注：
- 🔴 严重：必须修复
- 🟡 警告：建议修复
- 🟢 建议：可选优化

测试自定义技能

创建技能后，在项目中测试：

# 用户调用型技能
> /team-review

# 查看已加载的技能
> /skills

调试技巧

如果技能没有按预期工作，检查：

1. SKILL.md frontmatter 格式是否正确
2. 文件路径是否在 .claude/skills/ 目录下
3. invocable_by 和 user_command 字段是否匹配

发布技能

1. 创建独立的 GitHub 仓库
2. 包含完整的 README.md 说明
3. 添加 claude-skill topic
4. 提交到技能市场