OpenCode Skills 技能系统完全指南

Skills 是 OpenCode 中最重要的可复用知识模块。通过 Skills，你可以将某个领域的专业指令、工作流程和最佳实践封装成标准化的「技能包」，让 AI 编程助手在面对特定任务时自动激活对应的专业能力。本文将完整覆盖 Skills 的概念、编写、管理和最佳实践。

什么是 Skill？

Skill 是一个包含专业指令的 Markdown 文件（SKILL.md），告诉 OpenCode 在特定场景下应该如何思考和行动。每个 Skill 可以包含：

  • 描述文本：说明这个技能的用途和适用场景
  • 工作流程：分步骤的引导指令
  • 代码模板：可复用的代码片段
  • 外部资源引用：脚本、配置文件、参考文档
  • 触发条件：什么情况下应该使用这个 Skill

Skill 目录结构

.opencode/skills/
├── blog-publish/
│   ├── SKILL.md              # 技能定义文件
│   └── references/           # 附属资源
│       └── template.md
├── frontend-design/
│   └── SKILL.md
└── test-driven-development/
    ├── SKILL.md
    └── scripts/
        └── init-test.sh

内置 Skills

OpenCode 内置了大量经过精心设计的 Skills，包括：

开发流程类

| Skill | 用途 |
|-------|------|
| brainstorming | 在编码前进行需求分析和方案设计 |
| writing-plans | 为多步骤任务编写实施计划 |
| executing-plans | 按照计划分步执行 |
| verification-before-completion | 完成前运行验证命令 |
| test-driven-development | TDD 测试驱动开发 |

代码质量类

| Skill | 用途 |
|-------|------|
| systematic-debugging | 系统化调试方法 |
| requesting-code-review | 请求代码审查 |
| receiving-code-review | 接收和处理审查意见 |

前端开发类

| Skill | 用途 |
|-------|------|
| frontend-design | 前端视觉设计指导 |
| ui-ux-pro-max | 全面的 UI/UX 设计参考 |

工具与集成类

| Skill | 用途 |
|-------|------|
| playwright | 浏览器自动化测试 |
| using-git-worktrees | Git Worktree 工作隔离 |
| dispatching-parallel-agents | 并行子代理调度 |
| finishing-a-development-branch | 开发分支完成后的合并策略 |

元技能类

| Skill | 用途 |
|-------|------|
| writing-skills | 创建和优化 Skill 本身 |
| opencode-skill-creator | OpenCode Skill 创建工具 |

编写自定义 Skill

SKILL.md 基本结构

# Skill Name

## 用途描述

简短的说明这个 Skill 用于什么场景。

## 工作流程

### 第一步：分析需求

具体指令...

### 第二步：执行任务

具体指令...

### 第三步：验证结果

具体指令...

## 注意事项

- 注意点 1
- 注意点 2

实战：编写一个「API 接口开发」Skill

# Api Development

开发 RESTful API 接口的标准化流程。

## 工作流程

### 第一步：确认接口规范

在编写代码前，确认以下信息：
- HTTP 方法（GET / POST / PUT / DELETE）
- 路由路径
- 请求参数和验证规则
- 响应数据结构
- 认证和授权要求

### 第二步：编写 Controller

按照项目现有的 Controller 模式编写代码：
- 遵循已有的命名规范
- 添加参数验证
- 实现业务逻辑
- 返回标准化响应

### 第三步：编写测试用例

为 API 编写测试：
- 正常请求测试
- 参数验证测试
- 权限测试
- 边界条件测试

### 第四步：运行验证

php artisan route:list
php artisan test --filter=ApiTest

## 响应格式模板

{
"code": 200,
"message": "success",
"data": {}
}




使用外部脚本


Skill 目录中可以包含辅助脚本：


.opencode/skills/api-dev/
├── SKILL.md
├── scripts/
│   ├── run-tests.sh
│   └── check-routes.sh
└── references/
    └── api-standard.md


在 SKILL.md 中引用这些资源：


### 运行测试


bash .opencode/skills/api-dev/scripts/run-tests.sh
### 参考文档

详见 `references/api-standard.md` 中的接口规范。




Skill 的加载与优先级


加载顺序


OpenCode 按照以下顺序加载 Skills：


内置 Skills：随 OpenCode 发布的官方 Skills


全局 Skills：~/.config/opencode/skills/ 下的 Skills


项目 Skills：<项目>/.opencode/skills/ 下的 Skills


远程 Skills：通过 URL 或 Git 引入的 Skills


优先级规则


    

  • 项目级 Skill 覆盖同名的全局 Skill
    • 

  • 全局 Skill 覆盖同名的内置 Skill
    • 

  • 在 opencode.json 中可以禁用特定的内置 Skill
    • 



配置 Skill


在 opencode.json 中：


{
  "skills": {
    "enabled": true,
    "autoDetect": true,
    "disabled": ["some-builtin-skill"],
    "extraDirs": ["/shared/team-skills"],
    "remote": {
      "superpowers": "git+https://github.com/obra/superpowers.git"
    }
  }
}


    

  • autoDetect：是否根据上下文自动检测并激活 Skill
    • 

  • disabled：禁用的内置 Skill 列表
    • 

  • extraDirs：额外的 Skill 搜索目录
    • 

  • remote：通过 Git / URL 引入远程 Skill 仓库
    • 



Skill 的自动触发


OpenCode 会根据对话内容自动判断是否需要加载某个 Skill。触发机制基于 Skill 描述中的关键词匹配：


# Skill: Database Migration

MUST USE when user wants to create, modify, or rollback database migrations.


当用户说「帮我创建一个用户表的迁移文件」时，OpenCode 会自动激活 Database Migration Skill。


控制触发条件


# Skill: Database Migration

## 触发条件

- 用户提到「数据库迁移」、「migration」、「建表」等关键词
- 不适用于查询操作（不需要 Skill）

## 排除场景

- 仅查询数据时不需要加载
- SELECT 语句不需要加载


高级技巧


1. 链式 Skills


一个 Skill 可以引用另一个 Skill，形成工作流：


### 第三步：代码审查

完成后，使用 requesting-code-review Skill 发起代码审查。


2. 条件化 Skills


# Skill: Production Deploy

## 部署前检查

IF 分支是 main 或 master:
  - 运行完整测试套件
  - 检查环境变量配置
  - 确认数据库备份
ELSE:
  - 跳过部署流程


3. Skill 参数化


# Skill: Create Component

## 参数

调用时请提供以下参数：
- **component-name**：组件名称（PascalCase）
- **framework**：目标框架（React / Vue / Svelte）
- **style**：样式方案（Tailwind / CSS Modules / styled-components）


4. 项目特定的编码规范


将团队的编码规范写入 Skill，让 AI 严格遵守：


# Skill: Team Code Style

## PHP 编码规范

- 使用 strict types：`declare(strict_types=1);`
- 方法命名使用 camelCase
- 类命名使用 PascalCase
- 所有方法必须有 PHPDoc 类型注解
- 不允许使用 `**@**` 抑制错误
- 字符串优先使用单引号


从 Superpowers 社区获取 Skills


Superpowers 是 OpenCode 的官方 Skills 市场，包含社区贡献的高质量 Skills：


{
  "skills": {
    "remote": {
      "superpowers": "git+https://github.com/obra/superpowers.git"
    }
  }
}


常用社区 Skills 包括：


    

  • docker：Docker 容器管理
    • 

  • kubernetes：K8s 集群操作
    • 

  • terraform：基础设施即代码
    • 

  • python-testing：Python 测试框架
    • 

  • react-patterns：React 设计模式
    • 



小结


Skills 系统让 OpenCode 从「通用 AI 助手」转变为「领域专家」。通过编写和管理 Skills，你可以将团队的最佳实践、编码规范和工作流程固化下来，让每个使用 OpenCode 的团队成员都拥有统一的高质量 AI 编程体验。


下一篇我们将深入 OpenCode 的 Rules 规则与指令系统，学习如何用 AGENTS.md 精准控制 AI 的行为。


                        

                    

                

                

                    

                        
叶云梦天

                        

                            
叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客