<br />
Claude Code Skills 完全指南：扩展 AI 编程助手的能力边界#
引言
在 AI 辅助编程工具快速发展的今天，如何让 AI 更好地理解你的项目、遵循团队规范、执行特定工作流，成为了开发者关注的核心问题。Claude Code 推出的 Skills（技能） 功能，正是为解决这一痛点而生。
Skills 是一种强大的扩展机制，允许开发者为 Claude Code 注入自定义的知识、工作流和能力。无论是项目特定的编码规范、自动化部署流程，还是复杂的代码审查标准，都可以通过 Skills 来实现。
本文将全面介绍 Claude Code Skills 的核心概念、配置方法、使用场景和最佳实践。
一、什么是 Skills？#
1.1 核心定义#
Skills 是以 SKILL.md 文件为核心的扩展单元，遵循 Agent Skills 开放标准（Claude Code 在此基础上做了增强）。每个 Skill 可以包含：
- 指令内容：告诉 Claude 如何执行特定任务
- 知识库：项目相关的规范、模式、领域知识
- 工作流：分步骤的操作流程
- 工具限制：限定 Claude 可以使用哪些工具
1.2 Skills vs 传统命令#
在 Skills 出现之前，Claude Code 使用 .claude/commands/ 目录下的自定义命令。Skills 是这一功能的全面升级：
| 特性 | 传统命令 | Skills |
|---|---|---|
| 自动触发 | ❌ | ✅ Claude 可根据上下文自动调用 |
| 元数据配置 | 有限 | 完整的 YAML frontmatter |
| 子代理支持 | ❌ | ✅ 可在隔离环境中运行 |
| 工具限制 | ❌ | ✅ 可限制可用工具 |
| 动态内容 | ❌ | ✅ 支持 shell 命令注入 |
二、Skills 的存放位置与优先级#
Skills 可以存放在不同层级，系统会按优先级自动发现和加载：
text
优先级从高到低：
┌─────────────────────────────────────────────────────┐
│ 1. 企业级 (Enterprise) │
│ 通过托管设置配置，适用于整个组织 │
├─────────────────────────────────────────────────────┤
│ 2. 个人级 (Personal) │
│ ~/.claude/skills/<skill-name>/SKILL.md │
│ 适用于你的所有项目 │
├─────────────────────────────────────────────────────┤
│ 3. 项目级 (Project) │
│ .claude/skills/<skill-name>/SKILL.md │
│ 仅适用于当前项目 │
├─────────────────────────────────────────────────────┤
│ 4. 插件级 (Plugin) │
│ <plugin>/skills/<skill-name>/SKILL.md │
│ 通过插件引入 │
└─────────────────────────────────────────────────────┘小贴士：Claude Code 会自动发现子目录中嵌套的 .claude/skills/ 目录，这对于 monorepo 项目特别有用。
三、Skill 的结构与配置#
3.1 基本文件结构#
一个完整的 Skill 可能包含以下文件：
text
my-skill/
├── SKILL.md # 主指令文件（必需）
├── reference.md # 可选：详细参考文档
├── examples/
│ └── sample.md # 可选：示例输出
└── scripts/
└── helper.py # 可选：辅助脚本3.2 SKILL.md 文件格式#
SKILL.md 由两部分组成：YAML Frontmatter 和 Markdown 内容。
YAML
---
name: code-review
description: 执行代码审查，检查代码质量和安全性。当用户要求审查代码时使用。
allowed-tools: Read, Grep, Glob
---
## 代码审查指南
在审查代码时，请遵循以下步骤：
1. **安全性检查**
- 检查是否存在 SQL 注入风险
- 验证用户输入是否经过sanitize
- 确认敏感信息未硬编码
2. **代码质量**
- 检查命名规范
- 评估函数复杂度
- 识别重复代码
3. **性能考量**
- 检查是否有 N+1 查询问题
- 评估算法复杂度
- 审查内存使用3.3 Frontmatter 字段详解#
| 字段 | 必需 | 说明 |
|---|---|---|
name | 否 | 技能名称，将成为 /name 斜杠命令。小写字母、连字符，最多 64 字符 |
description | 推荐 | 描述技能的功能和触发条件。Claude 根据此判断是否自动加载 |
argument-hint | 否 | 自动补全提示，如 [issue-number] 或 [filename] |
disable-model-invocation | 否 | 设为 true 时，只有用户能调用，Claude 不会自动触发 |
user-invocable | 否 | 设为 false 时，只有 Claude 能调用，不会出现在命令列表 |
allowed-tools | 否 | 限制可用工具，如 Read, Grep, Bash(git:*) |
model | 否 | 指定运行此技能时使用的模型 |
context | 否 | 设为 fork 时在隔离的子代理中运行 |
agent | 否 | 配合 context: fork 使用，指定子代理类型 |
hooks | 否 | 绑定到此技能生命周期的钩子 |
四、Skills 的类型与使用场景#
4.1 参考型 Skills（知识注入）#
适用于：编码规范、API 约定、架构模式等持久性知识。
YAML
---
name: api-conventions
description: 本项目的 API 设计规范。在编写 API 端点时参考。
---
## API 设计规范
### 路由命名
- 使用复数名词：`/users` 而非 `/user`
- 嵌套资源：`/users/:id/posts`
- 动作用动词：`/users/:id/activate`
### 响应格式
```json
{
"success": true,
"data": { ... },
"meta": {
"page": 1,
"total": 100
}
}错误处理
- 400: 请求参数错误
- 401: 未认证
- 403: 无权限
- 404: 资源不存在
- 500: 服务器内部错误
text
### 4.2 任务型 Skills（工作流自动化）
适用于：部署流程、提交规范、代码生成等需要步骤执行的任务。
```yaml
---
name: deploy
description: 将应用部署到生产环境
disable-model-invocation: true # 防止意外触发
allowed-tools: Bash
---
## 部署流程
执行以下步骤完成部署：
1. **运行测试套件**
```bash
npm run test-
构建生产版本
Shellnpm run build -
执行数据库迁移
Shellnpm run migrate:prod -
部署到服务器
Shellnpm run deploy:prod -
验证部署状态
- 检查健康检查端点
- 确认日志无异常
text
### 4.3 动态上下文 Skills
通过 `!`command`` 语法，在 Skill 加载时动态执行命令并注入结果：
```yaml
---
name: pr-review
description: 审查当前 Pull Request
context: fork
agent: Explore
allowed-tools: Bash(gh:*)
---
## PR 上下文
### 变更差异
!`gh pr diff`
### PR 评论
!`gh pr view --comments`
### 关联 Issue
!`gh pr view --json body -q '.body'`
## 审查任务
基于以上上下文，请：
1. 总结此 PR 的主要变更
2. 检查代码质量问题
3. 提出改进建议五、调用控制机制
5.1 调用权限矩阵#
| 配置 | 用户可调用 | Claude 可调用 | 适用场景 |
|---|---|---|---|
| 默认 | ✅ | ✅ | 通用技能 |
disable-model-invocation: true | ✅ | ❌ | 有副作用的操作（部署、发布） |
user-invocable: false | ❌ | ✅ | 背景知识、内部规则 |
5.2 工具限制#
通过 allowed-tools 限制 Claude 在执行技能时可使用的工具：
YAML
---
name: safe-explorer
description: 安全地探索代码库，不做任何修改
allowed-tools: Read, Grep, Glob
---支持的模式匹配：
- 精确匹配：
Read - 通配符：
Bash(git:*) - 多个工具：
Read, Grep, Glob
5.3 权限控制#
在 /permissions 中可以控制技能的访问权限：
Shell
# 禁用所有技能
Skill
# 允许特定技能
Skill(commit)
# 使用前缀匹配
Skill(review-*)
# 禁止特定技能
Skill(deploy:*)六、高级特性
6.1 子代理执行#
将技能放入隔离的子代理环境中执行，适合需要深度探索或长时间运行的任务：
YAML
---
name: deep-analysis
description: 深度分析代码架构
context: fork
agent: Explore
---
对 $ARGUMENTS 进行深度分析：
1. 识别所有相关文件
2. 绘制依赖关系图
3. 分析核心算法
4. 总结架构模式
5. 提出优化建议6.2 变量替换#
Skills 支持以下变量：
| 变量 | 说明 |
|---|---|
$ARGUMENTS | 调用时传入的所有参数 |
${CLAUDE_SESSION_ID} | 当前会话 ID |
示例：
YAML
---
name: fix-issue
description: 修复 GitHub Issue
disable-model-invocation: true
---
修复 GitHub Issue #$ARGUMENTS
1. 读取 issue 描述
2. 分析问题根因
3. 实现修复方案
4. 编写测试用例
5. 创建提交6.3 支持文件#
当 SKILL.md 内容超过 500 行时，建议拆分为多个文件：
text
my-skill/
├── SKILL.md # 核心指令（保持简洁）
├── patterns.md # 设计模式参考
├── examples.md # 示例代码
└── checklist.md # 检查清单在 SKILL.md 中引用：
Markdown
## 更多资源
- 完整 API 文档见 [reference.md](reference.md)
- 使用示例见 [examples.md](examples.md)七、实战示例
示例 1：Git 提交规范#
YAML
---
name: commit
description: 创建符合规范的 Git 提交
disable-model-invocation: true
allowed-tools: Bash(git:*)
---
## 提交规范
### Commit Message 格式<type>(<scope>): <subject>
<body> <footer> ```Type 类型#
- feat: 新功能
- fix: 修复 bug
- docs: 文档更新
- style: 代码格式（不影响功能）
- refactor: 重构
- perf: 性能优化
- test: 测试相关
- chore: 构建/工具相关
执行步骤
- 运行
git status查看变更 - 运行
git diff --staged查看详细变更 - 分析变更类型和范围
- 生成符合规范的提交信息
- 执行提交
text
### 示例 2：代码解释器
```yaml
---
name: explain-code
description: 用图表和类比解释代码。当需要解释代码工作原理时使用。
allowed-tools: Read, Grep
---
## 代码解释指南
解释代码时，始终包含以下内容：
### 1. 生活类比
用日常生活中的事物来类比代码逻辑，让抽象概念具象化。
### 2. ASCII 图表
使用 ASCII 艺术绘制流程图或结构图：
text
┌─────────┐ ┌─────────┐ ┌─────────┐
│ 输入 │ ──▶ │ 处理 │ ──▶│ 输出 │
└─────────┘ └─────────┘ └─────────┘text
### 3. 逐行解读
对关键代码进行逐行解释。
### 4. 常见陷阱
指出初学者容易犯的错误。示例 3：React 组件生成器#
YAML
---
name: react-component
description: 生成 React 组件。当用户要求创建新组件时使用。
argument-hint: [ComponentName]
---
## React 组件模板
为 `$ARGUMENTS` 生成 React 组件，遵循以下规范：
### 文件结构src/components/$ARGUMENTS/ ├── index.tsx # 主组件 ├── $ARGUMENTS.test.tsx # 测试文件 ├── $ARGUMENTS.styles.ts # 样式（styled-components） └── types.ts # 类型定义
text
### 组件规范
- 使用函数式组件 + Hooks
- Props 使用 TypeScript 接口定义
- 提供 displayName
- 使用 React.memo 优化（如适用）
- 包含基本的错误边界处理
### 测试要求
- 渲染测试
- Props 变化测试
- 用户交互测试八、最佳实践
8.1 命名规范#
- 使用小写字母和连字符：
code-review、fix-issue - 名称应直观反映功能
- 避免过长的名称（最多 64 字符）
8.2 描述编写#
描述是 Claude 决定是否自动加载技能的关键：
YAML
# ❌ 描述太模糊
description: 帮助处理代码
# ✅ 描述具体明确
description: 执行代码审查，检查安全漏洞、代码风格和性能问题。当用户说"审查代码"或"检查代码质量"时使用。8.3 安全考量#
- 有副作用的操作使用
disable-model-invocation: true - 限制工具权限：只授予必要的工具访问
- 避免硬编码敏感信息：使用环境变量
- 测试充分：在安全环境中验证技能行为
8.4 性能优化#
- 保持 SKILL.md 精简：建议不超过 500 行
- 使用支持文件：将详细参考拆分到单独文件
- 合理使用
context: fork：仅对需要隔离的任务使用子代理
九、分发与共享
9.1 项目内共享#
将 .claude/skills/ 目录提交到版本控制：
Shell
git add .claude/skills/
git commit -m "feat: add team coding standards skill"9.2 通过插件分发#
创建插件并在其中包含 skills 目录：
text
my-plugin/
├── plugin.json
└── skills/
└── my-skill/
└── SKILL.md插件中的技能会被命名空间化：/my-plugin:my-skill
9.3 企业级部署#
通过托管设置（Managed Settings）将技能部署到整个组织，确保一致的开发规范。
十、故障排查
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 技能未触发 | 描述不匹配 | 优化描述，加入更多触发关键词 |
| 技能过于频繁触发 | 描述太宽泛 | 缩小描述范围，或使用 disable-model-invocation: true |
| Claude 看不到所有技能 | 字符预算超限 | 设置环境变量 SLASH_COMMAND_TOOL_CHAR_BUDGET |
| 动态命令未执行 | 语法错误 | 确认使用 !command`` 格式 |
总结
Claude Code Skills 是一个强大的扩展机制，它让你能够：
- 将团队的最佳实践编码化
- 自动化重复性工作流
- 确保 AI 遵循项目特定规范
- 安全地控制 AI 的能力边界
无论是个人开发者还是大型团队，Skills 都能帮助你打造一个更智能、更符合实际需求的 AI 编程助手。
开始创建你的第一个 Skill 吧！只需在项目中创建 .claude/skills/my-first-skill/SKILL.md 文件，然后用 /my-first-skill 来调用它。
