OpenCode Skills 安装指南:手动配置专业技能包扩展

2026-01-22 约 2011 字预计阅读 5 分钟

本文将教你:
什么是 OpenCode Skills 及其作用
如何创建标准的 Skills 目录结构
如何导入和验证技能包
常见问题的故障排查
如何创建自定义技能包

什么是 OpenCode Skills?

OpenCode Skills 是 OpenCode 的模块化扩展机制,通过结构化的指令包为 AI 助手注入特定领域的专业知识和工作流程。每个 Skill 封装了行业最佳实践、检查清单和执行模板,使 OpenCode 能够像领域专家一样执行任务。常见的 Skills 包括 SEO 审计、代码审查、测试编写、API 设计等专业能力。

本文将介绍如何为 OpenCode 助手安装自定义 Skills（技能包），以扩展其功能。

安装步骤

1. 创建配置目录

在你的项目根目录下，需要构建标准的目录结构来存放技能文件。

首先在项目根目录创建一个名为 .opencode 的文件夹。
在 .opencode 文件夹内，再创建一个名为 skills 的子文件夹。

如果你使用的是命令行，可以运行以下命令：

mkdir -p .opencode/skills

2. 导入技能包

将你获取到的技能包文件夹（例如 seo-review 或其他自定义技能）直接复制到刚才创建的 .opencode/skills/ 目录下。

安装后的推荐目录结构如下所示：

Project_Root/
├── .opencode/
│   └── skills/
│       └── your-custom-skill/  <-- 你的技能包文件夹
│           ├── SKILL.md
│           └── ...
└── ...

验证安装

安装完成后，你可以通过与 OpenCode 对话来验证技能是否被成功加载。

在项目目录下打开 OpenCode 终端。
输入查询指令，例如：“你有哪些 skills” 或 “列出当前可用技能”。

输出示例

如果安装成功，OpenCode 将会识别并列出可用的技能，如下所示：

> 你有哪些skills

Thinking: 用户问我有哪些skills。根据我的工具描述，我有一个skill工具可以加载特定的技能来获取详细的指导。
让我查看一下available_skills中列出了哪些skills：
根据工具描述，当前可用的skills有：
- seo-review: 对JavaScript概念页面进行专注的SEO审计，以最大化搜索可见性、精选片段优化和排名潜力

我当前有以下可用的skills：
seo-review - 对JavaScript概念页面进行专注的SEO审计，以最大化搜索可见性、精选片段优化和排名潜力

需要使用某个skill时，我会自动加载它来获取特定任务的详细指导。

至此，你已经成功为 OpenCode 安装了新的技能。在后续的对话中，当涉及到相关任务时，OpenCode 会自动加载并运用这些技能。

故障排查

问题 1: OpenCode 无法识别已安装的 Skill

症状: 技能包已复制到 .opencode/skills/ 目录,但查询时 OpenCode 提示没有可用技能。

可能原因:

目录结构不正确
缺少 SKILL.md 文件
权限问题

解决方案:

# 1. 验证目录结构
ls -la .opencode/skills/your-skill/
# 应该看到 SKILL.md 文件

# 2. 检查文件权限
chmod -R 755 .opencode/skills/

# 3. 验证 SKILL.md 格式 (必须以 --- 开头的 YAML frontmatter)
head -n 5 .opencode/skills/your-skill/SKILL.md

# 4. 重启 OpenCode (在项目目录重新启动)
cd /path/to/project
opencode

问题 2: Skill 文件格式错误

症状: OpenCode 启动时报错或技能无法加载。

常见格式错误:

# ❌ 错误 1: 缺少 YAML frontmatter
# Skill: SEO Review
This is my skill...

# ✅ 正确格式:
---
name: seo-review
description: "SEO审计技能"
version: 1.0.0
---
# Skill: SEO Review

# ❌ 错误 2: 文件名不是 SKILL.md
skill.md  # 小写不行
Skill.md  # 大小写错误

# ✅ 正确命名:
SKILL.md  # 必须全大写

问题 3: 技能在对话中不自动触发

症状: 技能已识别,但在相关任务中 OpenCode 不使用该技能。

解决方案:

# 1. 明确指定使用技能
> 请使用 seo-review 技能审查这篇文章

# 2. 检查技能的触发条件 (SKILL.md 中的 triggers 部分)
cat .opencode/skills/seo-review/SKILL.md | grep -A 5 "triggers"

# 3. 使用更明确的提示词
# ❌ 模糊: "检查这篇文章"
# ✅ 明确: "对这篇文章进行 SEO 审计"

常见问题 (FAQ)

Q1: Skills 和 MCP 有什么区别?

A: 两者服务于不同的目的:

特性	Skills	MCP
用途	提供专业知识和工作流程	提供外部工具和数据访问
内容	指令、清单、模板	API、数据库、命令
触发	根据任务类型自动触发	根据需要调用工具
示例	SEO审计、代码审查	文件读写、网络请求

简单来说: Skills 告诉 AI “怎么做”，MCP 给 AI “做事的工具”。

Q2: 在哪里可以找到更多 Skills?

A: 目前 Skills 主要通过以下渠道获取:

官方仓库: github.com/opencode-ai/skills (示例)
社区分享: OpenCode 社区论坛
自己创建: 参考现有 Skills 的格式编写

Q3: 可以同时安装多个 Skills 吗?

A: 可以。在 .opencode/skills/ 目录下创建多个子文件夹即可:

.opencode/skills/
├── seo-review/
│   └── SKILL.md
├── code-review/
│   └── SKILL.md
└── api-design/
    └── SKILL.md

OpenCode 会自动加载所有有效的技能包。

Q4: Skills 会增加 token 消耗吗?

A: 会,但影响可控:

Skills 采用渐进式加载,只在需要时注入相关指令
初始加载只读取元数据 (约 100 tokens)
详细指令只在技能触发时加载 (约 500-2000 tokens)
对于简单对话,不会加载任何 Skills 内容

Q5: 如何创建自己的 Skill?

A: 创建自定义 Skill 的基本步骤:

1. 创建目录结构

mkdir -p .opencode/skills/my-custom-skill
cd .opencode/skills/my-custom-skill

2. 创建 SKILL.md 文件

---
name: my-custom-skill
description: "我的自定义技能描述"
version: 1.0.0
author: "Your Name"

triggers:
  - type: keyword
    patterns:
      - "custom task"
      - "special analysis"
---

# My Custom Skill

## 工作流程

1. 步骤一：...
2. 步骤二：...
3. 步骤三：...

## 检查清单

- [ ] 检查项 1
- [ ] 检查项 2

## 示例

[提供具体示例...]

3. 测试验证

# 重启 OpenCode
opencode

# 查询技能
> 你有哪些 skills

# 测试触发
> 执行 custom task

Q6: Skills 支持哪些语言?

A: Skills 的指令可以用任何语言编写 (中文、英文等),因为它们本质上是给 AI 的文本指令。但建议:

使用英文编写更通用 (如果要分享)
使用目标用户的语言 (更易理解)
关键术语保持一致性

目录