原文：https://github.com/malhashemi/opencode-skills

OpenCode Skills 插件

将 Anthropic 的 Agent 技能规范 (v1.0) 带到 OpenCode 中。此插件自动将技能发现并注册为动态工具，使 Agent 能够利用专业知识、工作流程和捆绑资源。

功能特性

• ✅ 自动发现 - 扫描项目、主目录和配置目录中的技能
• ✅ 规范兼容 - 根据 Anthropic 的技能规范 v1.0 进行验证
• ✅ 动态工具 - 每个技能都会成为一个 skills_{{name}} 工具
• ✅ 路径解析 - 为相对文件路径提供基础目录上下文
• ✅ 嵌套技能 - 支持分层级的技能组织
• ✅ 优雅的错误处理 - 跳过无效技能并给出有用的提示信息

系统要求

• OpenCode SDK ≥ 0.15.18 - 需要 noReply 消息插入模式的支持 (PR#3378)

安装

将其添加到您的 opencode.json 或 ~/.config/opencode/opencode.json 文件中：

{
  "plugin": ["opencode-skills"]
}

OpenCode 在启动时会自动安装插件。

版本锁定

锁定到特定版本：

{
  "plugin": ["opencode-skills@x.y.z"]
}

插件更新

检查已安装的版本：

cat ~/.cache/opencode/node_modules/opencode-skills/package.json | grep version

强制更新到最新版本：

rm -rf ~/.cache/opencode

然后重启 OpenCode。

技能发现

该插件扫描三个位置（优先级从低到高）：

1. ~/.config/opencode/skills/ - XDG 配置位置（或 $XDG_CONFIG_HOME/opencode/skills/）
2. ~/.opencode/skills/ - 全局技能（所有项目共享）
3. .opencode/skills/ - 项目本地技能（覆盖全局技能）

所有位置的内容都会被合并。如果存在重复的技能名称，则项目本地版本的技能将被采用，并会记录一条警告信息。

快速上手

1. 创建一个技能

mkdir -p .opencode/skills/my-skill

.opencode/skills/my-skill/SKILL.md：

---
name: my-skill
description: 一个用于帮助我处理特定任务的自定义技能
license: MIT
---

# 我的自定义技能

此技能可帮助您完成特定任务。

## 指令

1.  首先，执行此操作
2.  然后，执行那个操作
3.  最后，验证结果

您可以引用支持文件，如 `scripts/helper.py` 或 `references/docs.md`。

2. 重启 OpenCode

插件将会发现并注册您的技能。

3. 使用技能

skills_my_skill

Agent 将接收技能内容并遵循其指令。

技能结构

必需项：SKILL.md

每个技能都必须有一个带有 YAML frontmatter 的 SKILL.md 文件：

---
name: skill-name # 必须与目录名匹配
description: 此技能的功能及使用场景（至少20个字符）
license: MIT # 可选
allowed-tools: # 可选（会被解析但不强制执行）
  - read
  - write
metadata: # 可选的键值对
  version: "1.0"
---

# 技能内容

您的 Markdown 格式的技能指令。

可选项：支持文件

my-skill/
├── SKILL.md              # 必需
├── scripts/              # 可执行代码
│   └── helper.py
├── references/           # 按需加载的文档
│   └── api-docs.md
└── assets/               # 输出中使用的文件
    └── template.html

技能命名

目录	Frontmatter 名称	工具名称
brand-guidelines/	brand-guidelines	skills_brand_guidelines
tools/analyzer/	analyzer	skills_tools_analyzer

规则：

• 目录名：小写，用连字符连接 (my-skill)
• Frontmatter 中的 name：必须与目录名完全匹配
• 工具名：自动生成，用下划线连接 (skills_my_skill)

工作原理

该插件使用 Anthropic 的消息插入模式来传递技能内容：

1. 技能加载消息 - 宣布技能已激活
2. 技能内容消息 - 传递带有基础目录上下文的指令
3. 工具确认 - 返回 "Launching skill: {name}"

这两条消息都使用 noReply: true，因此它们会显示为用户消息（而非工具响应）。这确保了技能内容可以在整个长对话中持续存在，即使 OpenCode 为管理上下文而清除了工具响应也是如此。

路径解析

技能可以使用相对路径引用文件：

读取 `references/api.md` 并运行 `scripts/deploy.sh`

Agent 会接收到基础目录上下文：

此技能的基础目录: /path/to/.opencode/skills/my-skill/

并自动解析出如下路径：/path/to/.opencode/skills/my-skill/references/api.md

故障排除

技能未被发现？

• 确认发现路径中存在 SKILL.md 文件
• 检查控制台是否有发现日志
• 确认 frontmatter 是有效的 YAML

工具未出现？

• 确保 name 字段与目录名完全匹配
• 检查是否存在重复的工具名（会记录为警告）
• 在添加/修改技能后重启 OpenCode

路径无法解析？

• 检查技能输出中显示的基础目录
• 确认支持文件存在于指定路径
• 确保 SKILL.md 中的路径是相对路径（非绝对路径）

技能无效错误？

• 名称必须仅为小写字母和连字符 ([a-z0-9-]+)
• 描述必须至少20个字符
• Frontmatter 中的名称必须与目录名匹配

插件未更新？

• 检查版本：cat ~/.cache/opencode/node_modules/opencode-skills/package.json | grep version
• 强制更新：rm -rf ~/.cache/opencode 然后重启
• 锁定版本：在 opencode.json 的插件名称中添加 @version

API 参考

该插件导出一个函数，用于将技能注册为动态工具：

export const SkillsPlugin: Plugin;

发现：扫描 .opencode/skills/、~/.opencode/skills/ 和 ~/.config/opencode/skills/
验证：强制执行 Anthropic 技能规范 v1.0
工具命名：对于嵌套路径，使用下划线生成 skills_{name}

完整的接口定义请参见 types。

高级

设计决策

Agent 级别的工具限制

工具限制在 OpenCode 的 agent 级别（通过 opencode.json 或 agent frontmatter）处理，而不是在技能级别。这提供了更清晰的权限模型，并更好地与 OpenCode 的现有系统保持一致。

技能从 frontmatter 中解析 allowed-tools 以符合规范要求，但强制执行在 agent 级别进行。

无热重载

技能被视为项目配置，而非运行时状态。添加或修改技能需要重启 OpenCode。这是可以接受的，因为技能不经常更改，并且没有用于运行时工具注册的 API。

贡献

欢迎贡献！Fork 本项目，创建一个功能分支，然后提交 PR。

许可证

MIT - 详见 LICENSE

参考资料

• Anthropic Skills Specification
• OpenCode Documentation

---

与 OpenAI 或 Anthropic 无关联。 这是一个独立的、开源的项目。