6、OpenCode Skills 快速上手指南

简介

Agent Skills 是 OpenCode 的可复用 AI 指令功能。通过创建 SKILL.md 文件，让 AI 按标准化流程执行任务。

步骤 1：安装 OpenCode-已安装忽略

curl -fsSL https://opencode.ai/install | bash

验证安装：

opencode --version

步骤 2：创建 Skill 文件

2.1 创建目录结构

项目级 Skill（仅当前项目可用）：

mkdir -p .opencode/skills/my-skill
touch .opencode/skills/my-skill/SKILL.md

全局 Skill（所有项目可用）：

mkdir -p ~/.config/opencode/skills/my-skill
touch ~/.config/opencode/skills/my-skill/SKILL.md

2.2 编写 SKILL.md

文件格式：

---
name: my-skill                    # 技能名称（必填）
description: 这是一段描述         # 技能描述（必填）
---

## What I do
这里写技能的具体功能说明。

## When to use me
说明什么情况下使用此技能。

## Steps
1. 第一步做什么
2. 第二步做什么
3. 第三步做什么

命名规则：

小写字母和数字
用连字符分隔单词
示例：code-review、api-docs、git-release

步骤 3：使用 Skill

3.1 查看可用 Skills

在 OpenCode 中输入 /，代理会自动列出所有可用 skills。

3.2 调用 Skill

两种方式：

方式一：@提及

@code-review 请审查 src/auth.js 文件

方式二：自然语言

使用 code-review 技能检查今天的提交

代理会自动加载对应的 SKILL.md 并执行。

步骤 4：权限配置（可选）

在 opencode.json 中配置：

{
  "permission": {
    "skill": {
      "*": "allow",
      "code-review": "allow",
      "internal-*": "deny"
    }
  }
}

权限选项：

allow：允许使用
deny：禁止使用
ask：使用前询问

实战示例

示例 1：代码审查 Skill

创建文件 .opencode/skills/code-review/SKILL.md：

---
name: code-review
description: 审查代码质量、性能和安全性
---

## What I do
检查代码中的问题，包括：
- 代码规范和可读性
- 潜在的性能问题
- 安全漏洞

## Steps
1. 阅读用户指定的代码文件
2. 按优先级列出发现的问题
3. 给出具体的改进建议

使用：

@code-review 请检查 src/app.js

示例 2：API 文档生成 Skill

创建文件 .opencode/skills/api-docs/SKILL.md：

---
name: api-docs
description: 从代码生成 API 文档
---

## What I do
分析代码中的 API 路由，生成 OpenAPI 文档。

## Steps
1. 扫描项目中的路由文件
2. 提取接口路径、参数、响应
3. 生成 openapi.yaml 文件

使用：

@api-docs 生成当前项目的 API 文档

文件位置速查

| 类型 | 路径 |
|------|------|
| 项目 Skill | .opencode/skills/<name>/SKILL.md |
| 全局 Skill | ~/.config/opencode/skills/<name>/SKILL.md |
| Claude 兼容 | .claude/skills/<name>/SKILL.md |

故障排除

| 问题 | 解决方案 |
|------|----------|
| Skill 不显示 | 检查文件名是否为 SKILL.md（全大写） |
| 无法加载 | 确认 name 字段与目录名一致 |
| 权限拒绝 | 在 opencode.json 中设置 "*": "allow" |
| 描述太长 | description 限制 1024 字符 |

注意事项

命名一致：目录名必须等于 SKILL.md 中的 name 字段
必填字段：name 和 description 必须填写
按需加载：Skill 只有被调用时才会加载，不占用日常资源
覆盖规则：项目级 Skill 优先级高于全局 Skill

最佳实践：让AI给你写Skill

每当完成一个任务时，可以让AI根据上面的对话，生成一个xxxx的skill,并设置为全局Skill 或项目Skill，
保存到 '.config/opencode/skills' 目录

完整示例：Git 发布 Skill

---
name: git-release
description: 创建发布说明和版本标签
---

## What I do
根据最近的提交生成发布说明。

## Steps
1. 查看最近的 git 提交
2. 整理变更列表
3. 生成发布说明草稿
4. 创建 git 标签

保存到 .opencode/skills/git-release/SKILL.md，然后使用：

@git-release 准备 v1.2.0 发布

参考：OpenCode 官方文档 https://opencode.ai/docs/skills/

简介