【转载】OpenCode中支持Skills

关注

原创最新推荐文章于 2026-10-15 14:23:14 发布 5.1k 阅读 AI 写同款· GEO 优化 ›

小白也能懂的 OpenCode 教程：从安装 Skill 工具到配置大模型，再到下载社区 Skill 全攻略 OpenCode 入门指南：安装、配置与使用本文为零基础用户提供 OpenCode 的详细使用教程，包含三个核心部分：安装 OpenCode - 详细讲解 Windows/Mac/Linux 系统的安装步骤，需先确保 Node.js 环境（v18+）配置大模型 - 指导如何获取并配置 API Key（支持 OpenAI/Anthropic/阿里云等），提供交互式和手动两种配置方法使用社区 Skill - 介绍主流 Skill 平台（skills.sh/skillsmp.com等），演示通过 npx 阅读详情

原文：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。

技能发现

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

~/.config/opencode/skills/ - XDG 配置位置（或 $XDG_CONFIG_HOME/opencode/skills/）
~/.opencode/skills/ - 全局技能（所有项目共享）
.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 的消息插入模式来传递技能内容：

技能加载消息 - 宣布技能已激活
技能内容消息 - 传递带有基础目录上下文的指令
工具确认 - 返回 "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