【OpenCode系统性指南】第14篇：Skills系统：打造可复用的AI技能
【OpenCode系统性指南】第14篇：Skills系统：打造可复用的AI技能
引言
在前面的文章中，我们介绍了 Commands（自定义命令）和 Agents（自定义代理）。Commands 让你能用快捷方式执行常见操作，Agents 则为不同任务分配专属的 AI 角色。但你是否遇到过这样的场景：某些知识需要 AI 在特定上下文中自动感知并应用，而不是每次都手动调用？
这就是 Skills 系统的价值所在。Skills 是一种基于提示词的可复用技能架构，它采用"渐进式披露"的设计理念，在需要时自动激活，为 AI 提供精确的上下文支持。
本文将系统性介绍 Skills 的核心概念、文件结构、创建方法以及团队协作最佳实践，帮助你打造一套可复用的 AI 技能库。
一、Skills vs 普通Prompt：核心区别
1.1 什么是 Skills
Skills 是一种基于提示词的元工具架构，用于扩展 Claude 的能力。与普通的 Prompt 不同，Skills 采用"渐进式披露"（Progressive Disclosure）的设计模式，分三层逐步加载内容：
第一层：Metadata（始终加载）
↓ 触发时加载
第二层：SKILL.md 指令内容
↓ 按需加载
第三层：支持文件（scripts/referenc/uploads/2026/02/21/）
这种设计的好处是：只在需要时加载需要的内容，避免上下文膨胀，同时保持强大的功能扩展性。
1.2 Skills vs Commands vs Agents
理解 Skills 的关键在于区分它与 Commands、Agents 的不同用途：
| 特性 | Skills | Commands | Agents |
|---|---|---|---|
| 触发方式 | 自动（上下文感知） | 手动（用户调用 /xxx） | 手动/自动（任务分配） |
| 加载时机 | 需要时 | 立即 | 分配任务时 |
| 主要用途 | 扩展上下文 | 快捷操作 | 专门任务 |
| 复杂度 | 低到中 | 低 | 高 |
| 可复用性 | 极高 | 中等 | 高 |
选择建议：
- 用 Skills：当你希望 AI 在特定场景下自动应用某些知识（如代码规范检查、特定框架的最佳实践）
- 用 Commands：当你需要一个快捷方式执行固定操作（如
/commit、/test） - 用 Agents：当任务需要专门的工具权限和独立配置（如代码审查代理、测试专家代理）
1.3 渐进式披露的优势
为什么 Skills 要采用三层加载模式？
上下文效率：Metadata 只有几百字节，始终加载不会影响性能。只有当 AI 判断需要某个 Skill 时，才会加载完整的指令内容。
灵活扩展：复杂的 Skill 可以包含脚本、参考文档、静态资源等支持文件，这些都按需加载，不会每次都塞进上下文。
智能触发：AI 通过 Metadata 中的 description 字段判断是否需要激活该 Skill，实现"隐形"的能力扩展。
二、创建你的第一个 Skill
2.1 Skill 目录结构
一个完整的 Skill 目录结构如下：
.claude/skills/
└── code-review/ # 技能名称
├── SKILL.md # 必需：主定义文件
├── scripts/ # 可选：可执行脚本
├── references/ # 可选：参考资料
└── assets/ # 可选：静态资源
存放位置优先级：
| 位置 | 路径 | 用途 |
|---|---|---|
| 企业级 | 企业配置目录 | 全公司共享的技能 |
| 个人 | ~/.claude/skills/ | 个人复用的技能 |
| 项目 | .claude/skills/ | 项目特定的技能 |
| 插件 | 插件目录 | 第三方扩展技能 |
2.2 SKILL.md 文件规范
SKILL.md 是 Skill 的核心文件，由 YAML frontmatter 和指令内容两部分组成：
---
name: code-review
description: 当用户请求代码审查、代码评审、code review 时触发
allowed-tools: [Read, Grep]
user-invocable: true
---
## 代码审查技能
当此技能被触发时，请按以下步骤进行代码审查：
### 审查维度
1. **代码质量**：检查命名规范、代码结构、可读性
2. **安全性**：识别潜在的安全漏洞
3. **性能**：分析性能瓶颈
4. **最佳实践**：对照框架最佳实践提供建议
### 输出格式
请使用以下格式输出审查结果：
## 审查报告
### 问题列表
- [严重程度] 问题描述
### 改进建议
- 具体改进方案
### 总体评分
X/10
Frontmatter 字段说明：
| 字段 | 必需 | 说明 |
|---|---|---|
name | 是 | Skill 的唯一标识符 |
description | 是 | 触发条件描述，AI 据此判断是否激活 |
allowed-tools | 否 | 限制该 Skill 可使用的工具 |
user-invocable | 否 | 是否允许用户手动调用（默认 false） |
2.3 创建步骤
第一步：创建目录
mkdir -p .claude/skills/code-review
第二步：创建 SKILL.md
在 .claude/skills/code-review/ 目录下创建 SKILL.md 文件，填入上述内容。
第三步：验证
启动 OpenCode，尝试说"帮我审查一下这段代码"，观察 AI 是否自动加载了你的 Skill。
三、Skills 最佳实践
3.1 可复用指令设计
设计可复用的 Skill 需要遵循以下原则：
单一职责：每个 Skill 只做一件事，并做好它。不要创建一个"万能审查"Skill，而是创建"安全审查"、"性能审查"、"风格审查"等多个专注的 Skill。
清晰的触发条件：description 字段要明确、具体。避免模糊的描述如"帮助用户"，而是使用"当用户请求数据库迁移时触发"。
结构化输出：定义清晰的输出格式，便于后续处理或与其他工具集成。
3.2 参数化技能
Skills 支持参数传递，让你的技能更加灵活：
使用 $ARGUMENTS
---
name: generate-test
description: 为指定函数生成测试用例
---
为以下函数生成测试用例：
函数路径：$ARGUMENTS
请生成：
1. 正常情况测试
2. 边界情况测试
3. 异常情况测试
调用方式：
/generate-test src/utils/formatDate.ts
使用位置参数
# $ARGUMENTS[0] - 文件路径
# $ARGUMENTS[1] - 测试框架（可选，默认 jest）
调用方式：
/generate-test src/utils/formatDate.ts vitest
使用环境变量
项目使用的技术栈：${TECH_STACK}
默认作者：${AUTHOR_NAME}
3.3 技能组合使用
多个 Skills 可以组合使用，形成完整的工作流：
示例：代码提交工作流
Skills:
├── lint-check # 代码风格检查
├── test-runner # 运行测试
├── commit-msg # 生成提交信息
└── branch-naming # 分支命名规范
当你说"提交代码"时，AI 可能会：
- 自动加载
lint-check检查代码风格 - 加载
test-runner运行相关测试 - 根据
commit-msg规范生成提交信息 - 检查分支命名是否符合
branch-naming规范
这种组合能力让 Skills 成为构建 AI 工作流的基础单元。
四、团队 Skills 共享
4.1 Git 管理技能库
将项目的 .claude/skills/ 目录纳入 Git 版本控制，团队成员就能共享相同的 AI 能力：
# 添加到版本控制
git add .claude/skills/
# 提交
git commit -m "feat: 添加代码审查 Skill"
团队协作流程：
- 创建分支：为新 Skill 创建独立分支
- 评审合并：通过 Pull Request 评审 Skill 内容
- 版本管理：使用 Git 标签标记 Skill 版本
- 更新同步：团队成员 pull 最新代码即可获得新 Skill
4.2 远程技能加载
对于企业级共享，可以将 Skills 放在独立的 Git 仓库：
企业 Skills 仓库
├── skills/
│ ├── security-audit/
│ ├── api-design/
│ └── code-standards/
└── README.md
团队成员通过配置文件引用：
{
"skills": {
"remote": [
"git@github.com:company/claude-skills.git"
]
}
}
4.3 Skills 维护建议
命名规范：使用小写字母和连字符，如 api-design、db-migration
版本控制：在 SKILL.md 中添加版本号和更新日志
文档完善：每个 Skill 目录添加 README.md，说明使用方法和示例
定期清理：删除不再使用的 Skill，保持技能库精简
小结
- Skills 本质：基于提示词的可复用技能架构，采用渐进式披露设计
- 三层加载：Metadata（始终）→ SKILL.md（触发时）→ 支持文件（按需）
- 与 Commands/Agents 区别：Skills 自动感知触发，用于扩展上下文；Commands 手动调用执行快捷操作；Agents 分配专门任务
- 参数化：使用
$ARGUMENTS、$ARGUMENTS[N]、${VAR}实现灵活参数传递 - 团队共享：通过 Git 版本控制管理技能库，支持远程加载企业级 Skills
Skills 系统是 OpenCode 扩展生态的重要组成部分。掌握 Skills 的创建和使用，能让你打造一套专属的 AI 技能库，在特定场景下获得更精准、更高效的 AI 辅助。
📥 想获取更多 OpenCode 资源？
扫码加入「大熊掌门AI编程会员群」：
进群即领：
- 📄 Claude Code 入门指南 PDF（群内领）
专栏更新中，后续解锁：
- 📁 OpenCode 完整配置模板库
- 📝 5个常用自定义命令模板
- 📋 AGENTS.md 规则模板
- 📖 本专栏完整版 PDF 电子书（约20篇文章整合）
群内还有：
- 每周技术干货分享
- 问题答疑
- 付费内容专属优惠