OpenCode Skills

在 OpenCode 中，代理技能（Skills）是一种用于封装可复用行为的机制，通过 SKILL.md 文件定义，使 LLM 能够按需加载、按需执行特定能力。

相比普通提示词，技能更接近模块化能力单元，可以在多个项目或团队中复用。

Skills 是 OpenCode 的能力插件系统，它将 AI 行为从单次提示升级为可复用能力模块，使开发流程更加标准化、可组合，并适用于复杂工程体系。

更多 Skills 可以参考：

一、核心机制

Skills 通过内置的 skill 工具进行管理，工作流程如下：

  1. 扫描本地和全局技能目录
  2. 在上下文中暴露可用技能列表
  3. 代理根据任务自动选择技能
  4. 按需加载 SKILL.md 内容

这种机制避免了将所有规则一次性加载，提高了性能和上下文利用率。

二、目录结构与放置位置

每个技能必须独立目录：

.opencode/skills/<skill-name>/SKILL.md

OpenCode 会在以下位置查找技能：

  • 项目级：.opencode/skills/
  • 全局：~/.config/opencode/skills/
  • Claude 兼容：.claude/skills/、~/.claude/skills/
  • Agents 兼容：.agents/skills/、~/.agents/skills/

加载规则：

  • 从当前目录向上遍历至 Git 根目录
  • 加载所有匹配的 skills/*/SKILL.md
  • 同时加载全局目录中的技能

三、SKILL.md 基本结构

每个技能文件必须包含 YAML frontmatter：

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

字段说明

字段 说明
name 技能名称（必填）
description 技能描述（必填）
license 许可证（可选）
compatibility 兼容标识（可选）
metadata 扩展信息（键值对）

frontmatter 之后为技能的具体行为说明。

四、完整示例

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a gh release command

## When to use me

Use this when preparing a release.
Ask for clarification if versioning is unclear.

该技能可用于自动生成版本发布流程。

五、技能命名规范

技能名称必须满足以下规则：

  • 长度：1–64 字符
  • 仅包含：小写字母、数字、连字符
  • 不能以 - 开头或结尾
  • 不能出现连续 --
  • 必须与目录名称一致

正则表达式：

^[a-z0-9]+(-[a-z0-9]+)*$

六、技能发现与加载

OpenCode 会将技能列表注入上下文： 

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases</description>
  </skill>
</available_skills>

代理在需要时调用： 

skill({ name: "git-release" })

然后加载完整 SKILL.md 内容。

七、权限控制

通过 opencode.json 控制技能访问权限： 

{
  "permission": {
    "skill": {
      "*": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}
权限 行为
allow 直接加载
deny 隐藏技能
ask 需用户确认

八、按代理覆盖权限

可以针对不同代理设置不同技能权限： 

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

适用于：

  • 分析代理使用更多内部工具
  • 生产代理限制敏感技能

九、禁用技能工具

如果某些代理不需要 Skills，可以完全禁用： 

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

禁用后：

  • 技能不会被加载
  • 上下文中不再出现 skills 列表

十、常见问题排查

  • 确认文件名必须为 SKILL.md（大写）
  • 检查是否包含 name 和 description
  • 确保技能名称全局唯一
  • 检查权限是否被 deny
  • 确认目录结构是否正确

十一、最佳实践

  • 将复杂流程封装为 Skills（如发布、部署、审查）
  • 保持 description 清晰具体，方便代理选择
  • 按功能拆分多个技能，避免单体过大
  • 结合权限控制敏感操作
  • 团队统一维护 skills 目录