1. Claude Code技能系统概述
Claude Code的技能系统是一个强大的扩展框架,允许用户通过创建、管理和共享技能来增强Claude的能力。每个技能本质上是一个包含特定指令的Markdown文件(SKILL.md),它定义了Claude在特定场景下应该如何响应和操作。
技能可以用于多种用途:
- 自动化常见开发任务(如代码审查、部署)
- 提供项目特定的知识(如API设计规范)
- 创建交互式工具(如代码可视化)
- 扩展Claude的核心功能
技能系统的核心优势在于它的灵活性和可定制性。开发者可以根据项目需求创建专属技能,也可以从社区获取现成的技能来加速开发流程。
2. 技能创建与管理
2.1 技能目录结构
一个完整的技能通常包含以下文件和目录:
code复制my-skill/
├── SKILL.md # 主指令文件(必需)
├── template.md # 模板文件
├── examples/ # 示例目录
│ └── sample.md # 示例文件
└── scripts/ # 脚本目录
└── helper.sh # 辅助脚本
SKILL.md是每个技能的核心文件,包含YAML frontmatter和Markdown内容两部分。frontmatter用于配置技能行为,而Markdown内容则包含具体的指令。
2.2 创建基本技能
创建一个简单技能的步骤如下:
- 创建技能目录:
bash复制mkdir -p ~/.claude/skills/summarize-changes
- 编写SKILL.md文件:
markdown复制---
description: 总结未提交的更改并标记风险项。当用户询问更改内容、需要提交信息或要求审查差异时使用。
---
## 当前更改
!`git diff HEAD`
## 指令
用2-3个要点总结上述更改,然后列出你注意到的任何风险,如缺少错误处理、硬编码值或需要更新的测试。如果差异为空,说明没有未提交的更改。
这个技能会执行git diff HEAD命令获取当前未提交的更改,然后让Claude总结这些更改并识别潜在风险。
2.3 技能存储位置
技能可以存储在多个位置,影响其可用范围:
| 位置 | 路径 | 适用对象 |
|---|---|---|
| 企业级 | 管理设置 | 组织内所有用户 |
| 个人级 | ~/.claude/skills/ | 用户的所有项目 |
| 项目级 | .claude/skills/ | 当前项目 |
| 插件级 | 启用插件的项目 |
当不同级别的技能同名时,企业级覆盖个人级,个人级覆盖项目级。项目级技能也会覆盖同名的内置技能。
3. 高级技能功能
3.1 动态内容注入
技能支持通过!命令语法注入动态内容。这些命令会在技能内容发送给Claude之前执行,输出结果会替换原始命令。
示例:
markdown复制## Pull request上下文
- PR差异: !`gh pr diff`
- PR评论: !`gh pr view --comments`
- 更改文件: !`gh pr diff --name-only`
对于多行命令,可以使用```!代码块:
markdown复制## 环境信息
```!
node --version
npm --version
git status --short
code复制
### 3.2 参数传递
技能支持参数传递,可以通过`$ARGUMENTS`或`$0`、`$1`等占位符访问:
```markdown
---
name: fix-issue
description: 修复GitHub问题
---
修复GitHub问题 $ARGUMENTS:
1. 阅读问题描述
2. 理解需求
3. 实现修复
4. 编写测试
5. 创建提交
调用方式:/fix-issue 123
3.3 子代理执行
通过设置context: fork可以让技能在独立的子代理中执行:
markdown复制---
name: deep-research
description: 深入研究某个主题
context: fork
agent: Explore
---
深入研究 $ARGUMENTS:
1. 使用Glob和Grep查找相关文件
2. 阅读分析代码
3. 用具体文件引用总结发现
这种模式适合需要隔离环境或特定工具集的任务。
4. 技能开发最佳实践
4.1 技能设计原则
- 单一职责:每个技能应专注于解决一个特定问题
- 明确触发条件:在description中清晰定义何时应使用该技能
- 模块化设计:将大型技能拆分为多个小技能
- 文档完整:为技能提供清晰的用法说明和示例
4.2 性能优化技巧
- 控制技能大小:保持SKILL.md简洁,将详细内容移到支持文件中
- 合理使用动态注入:避免在频繁调用的技能中使用耗时命令
- 缓存常用数据:对于不变的数据,考虑将其硬编码而非动态获取
- 分批处理:对于大型任务,设计为多个小技能链式调用
4.3 调试与测试
- 使用skill-creator插件:自动化测试技能行为
- 隔离测试:在新会话中测试技能,避免残留上下文影响
- 对比测试:比较有技能和无技能时的输出差异
- 日志记录:在技能中添加日志输出以便调试
5. 实用技能示例
5.1 代码审查技能
markdown复制---
name: code-review
description: 执行代码审查,关注代码质量、可维护性和潜在问题
---
## 代码审查清单
审查以下方面:
1. **代码风格**:是否符合项目规范
2. **错误处理**:是否有足够的错误检查和恢复
3. **性能**:是否存在明显的性能问题
4. **安全性**:是否有潜在的安全漏洞
5. **可测试性**:代码是否易于测试
6. **文档**:是否有足够的注释和文档
对于每个发现问题:
- 明确描述问题
- 指出具体位置
- 提供改进建议
- 评估严重程度(低/中/高)
5.2 部署技能
markdown复制---
name: deploy
description: [部署应用](https://taotoken.net?utm_source=general)到生产环境
disable-model-invocation: true
allowed-tools: Bash(npm run *) Bash(git *) Bash(ssh *)
---
## 部署流程
1. **测试**:运行测试套件
```bash
npm test
-
构建:创建生产版本
bash复制
npm run build -
验证:检查构建结果
bash复制ls -lh dist/ -
部署:上传到服务器
bash复制
scp -r dist/ user@production:/var/www/app -
重启服务:在服务器上重启应用
bash复制ssh user@production "sudo systemctl restart app"
注意:部署前确保所有测试通过,并且已提交当前更改。
code复制
### 5.3 交互式可视化技能
```markdown
---
name: visualize-deps
description: 生成项目依赖关系可视化图
allowed-tools: Bash(python3 *)
---
## 依赖关系可视化
生成项目依赖关系的交互式可视化:
1. 安装依赖分析工具(首次使用时):
```bash
pip install graphviz
- 运行可视化脚本:
bash复制python3 ${CLAUDE_SKILL_DIR}/scripts/deps_visualizer.py
这将生成一个HTML文件并在浏览器中打开,显示:
- 模块间的依赖关系
- 循环依赖(用红色高亮)
- 每个模块的大小和文件数
code复制
## 6. 常见问题与解决方案
### 6.1 技能不触发
**问题**:技能没有在预期场景下自动触发
**解决方案**:
1. 检查description是否准确描述了触发条件
2. 确保没有设置`disable-model-invocation: true`
3. 验证技能位于正确的目录层级
4. 检查是否有同名技能覆盖了当前技能
### 6.2 动态注入不工作
**问题**:`!`命令没有执行或被忽略
**解决方案**:
1. 确认命令以`!`开头且前面只有空格
2. 检查命令是否存在于系统中
3. 验证命令执行权限
4. 确保没有设置`"disableSkillShellExecution": true`
### 6.3 参数传递错误
**问题**:`$ARGUMENTS`没有正确替换
**解决方案**:
1. 确保参数用引号包裹(如`/skill "arg with spaces"`)
2. 检查参数索引是否正确(`$0`是第一个参数)
3. 验证技能内容中确实包含`$ARGUMENTS`或`$N`占位符
### 6.4 性能问题
**问题**:技能执行缓慢或消耗过多资源
**解决方案**:
1. 优化动态命令,减少执行时间
2. 将大型技能拆分为多个小技能
3. 对于不变的数据,考虑硬编码而非动态获取
4. 使用`context: fork`隔离资源密集型任务
## 7. 技能共享与分发
### 7.1 项目内共享
将技能放在项目的`.claude/skills/`目录并提交到版本控制,这样所有项目成员都可以使用这些技能。
### 7.2 创建技能插件
1. 创建插件目录结构:
my-plugin/
├── plugin.json
└── skills/
└── my-skill/
├── SKILL.md
└── scripts/
└── helper.sh
code复制
2. 定义plugin.json:
```json
{
"name": "my-plugin",
"version": "1.0.0",
"description": "我的自定义技能集合"
}
- 打包并发布到插件市场
7.3 企业级分发
通过管理设置将技能部署到整个组织,确保所有用户都能访问这些标准化技能。
8. 技能系统的高级应用
8.1 结合CI/CD
技能可以集成到持续集成流程中,例如:
- 自动代码审查
- 测试覆盖率检查
- 部署验证
示例CI集成技能:
markdown复制---
name: ci-checks
description: 运行CI检查套件
disable-model-invocation: true
allowed-tools: Bash(npm *) Bash(docker *)
---
## CI检查
1. 运行lint检查:
```bash
npm run lint
-
执行单元测试:
bash复制npm test -
构建Docker镜像:
bash复制
docker build -t my-app . -
运行集成测试:
bash复制
docker-compose -f docker-compose.test.yml up --abort-on-container-exit
注意:所有检查必须通过才能继续部署流程。
code复制
### 8.2 自定义开发工具链
通过组合多个技能,可以创建完整的开发工具链,例如:
1. `/setup-env` - 设置开发环境
2. `/code-review` - 代码审查
3. `/run-tests` - 执行测试
4. `/deploy` - 部署应用
### 8.3 领域特定技能
针对特定领域创建专用技能,如:
- 数据科学:数据清洗、模型训练技能
- Web开发:路由生成、API测试技能
- 嵌入式:硬件验证、低功耗优化技能
示例数据科学技能:
```markdown
---
name: clean-data
description: 数据清洗和预处理
allowed-tools: Bash(python3 *)
---
## 数据清洗
1. 加载数据:
```python
import pandas as pd
df = pd.read_csv("${ARGUMENTS[0]}")
-
处理缺失值:
python复制# 删除全空列 df.dropna(axis=1, how='all', inplace=True) # 用中位数填充数值列 for col in df.select_dtypes(include='number'): df[col].fillna(df[col].median(), inplace=True) -
保存处理后的数据:
python复制df.to_csv("cleaned_${ARGUMENTS[0]}", index=False)
code复制
## 9. 技能维护与更新
### 9.1 版本控制
建议对技能进行版本控制:
1. 在SKILL.md中添加版本信息:
```markdown
---
version: 1.0.1
---
- 使用语义化版本控制
- 维护变更日志
9.2 向后兼容
更新技能时注意:
- 不破坏现有参数接口
- 逐步弃用而非立即移除功能
- 提供迁移指南
9.3 性能监控
监控技能使用情况:
- 记录执行时间
- 跟踪使用频率
- 收集用户反馈
10. 安全最佳实践
10.1 权限管理
- 限制敏感技能的执行权限
- 谨慎使用
allowed-tools - 定期审查技能权限
10.2 输入验证
- 验证动态注入命令的参数
- 限制命令执行范围
- 使用白名单而非黑名单
10.3 安全审计
- 定期审计第三方技能
- 检查动态注入命令的安全性
- 监控异常技能活动
