opencode-primitives

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Purpose

用途

Use this skill whenever OpenWork behavior is implemented directly on top of OpenCode primitives (skills, plugins, MCP servers, opencode.json config, tools/permissions). It anchors decisions to the official OpenCode documentation and keeps terminology consistent in the UI.

当OpenWork行为直接基于OpenCode原语（skill、plugin、MCP服务器、opencode.json配置、工具/权限）实现时，请使用本skill。它可以将决策锚定到官方OpenCode文档，保持UI中的术语一致性。

Doc Sources (Always cite when relevant)

文档来源（相关时请务必引用）

Skills: https://opencode.ai/docs/skills
Plugins: https://opencode.ai/docs/plugins/
MCP servers: https://opencode.ai/docs/mcp-servers/
Config (opencode.json, locations, precedence): https://opencode.ai/docs/config/

Skills: https://opencode.ai/docs/skills
Plugins: https://opencode.ai/docs/plugins/
MCP servers: https://opencode.ai/docs/mcp-servers/
Config (opencode.json, 位置、优先级): https://opencode.ai/docs/config/

Key Facts To Apply

需应用的核心规则

Skills

Skill files live in

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

or global

~/.config/opencode/skills/<name>/SKILL.md

Skills are discovered by walking up to the git worktree and loading any matching
```
skills/*/SKILL.md
```
in
```
.opencode/
```
or
```
.claude/skills/
```
.
```
SKILL.md
```
requires YAML frontmatter:
```
name
```
+
```
description
```
.
Name rules: lowercase alphanumeric with single hyphens (
```
^[a-z0-9]+(-[a-z0-9]+)*$
```
), length 1-64, must match directory name.
Description length: 1-1024 characters.
Access is governed by
```
opencode.json
```
permissions (
```
permission.skill
```
allow/deny/ask).

Skill文件存放在

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

或全局路径

~/.config/opencode/skills/<name>/SKILL.md

。

Skill的发现逻辑是向上遍历git工作树，加载
```
.opencode/
```
或
```
.claude/skills/
```
路径下所有匹配
```
skills/*/SKILL.md
```
的文件。
```
SKILL.md
```
必须包含YAML前置元数据：
```
name
```
+
```
description
```
。
命名规则：小写字母数字，仅可使用单个连字符分隔（正则匹配
```
^[a-z0-9]+(-[a-z0-9]+)*$
```
），长度1-64位，必须与所属目录名一致。
描述长度要求：1-1024个字符。
访问权限由
```
opencode.json
```
中的权限配置（
```
permission.skill
```
的allow/deny/ask规则）管控。

Plugins

Local plugins live in

.opencode/plugins/

(project) or

~/.config/opencode/plugins/

(global).

npm plugins are listed in
```
opencode.json
```
under
```
plugin
```
and installed with Bun at startup.
Load order: global config, project config, global plugins dir, project plugins dir.

本地plugin存放在
```
.opencode/plugins/
```
（项目级）或
```
~/.config/opencode/plugins/
```
（全局）。
npm plugin在
```
opencode.json
```
的
```
plugin
```
字段下列出，项目启动时通过Bun安装。
加载顺序：全局配置 > 项目配置 > 全局plugin目录 > 项目plugin目录。

MCP Servers

MCP servers are defined in
```
opencode.json
```
under
```
mcp
```
with unique names.
Local servers use
```
type: "local"
```
+
```
command
```
array; remote servers use
```
type: "remote"
```
+
```
url
```
.
Servers can be enabled/disabled via
```
enabled
```
.
MCP tools are managed via
```
tools
```
in config, including glob patterns.
OAuth is handled automatically for remote servers; can be pre-registered or disabled.

MCP服务器在
```
opencode.json
```
的
```
mcp
```
字段下定义，需使用唯一名称。
本地服务器使用
```
type: "local"
```
+
```
command
```
数组配置；远程服务器使用
```
type: "remote"
```
+
```
url
```
配置。
可通过
```
enabled
```
字段启用/禁用服务器。
MCP工具通过配置中的
```
tools
```
字段管理，支持glob模式。
远程服务器的OAuth会自动处理，支持预注册或手动禁用。

Config (opencode.json)

Supports JSON and JSONC.
Precedence order: remote
```
.well-known/opencode
```
-> global
```
~/.config/opencode/opencode.json
```
-> custom path -> project
```
opencode.json
```
->
```
.opencode/
```
directories -> inline env overrides.
```
.opencode
```
subdirectories are plural by default (
```
agents/
```
,
```
commands/
```
,
```
plugins/
```
,
```
skills/
```
,
```
tools/
```
,
```
themes/
```
), with singular names supported for compatibility.

支持JSON和JSONC格式。
优先级顺序：远程
```
.well-known/opencode
```
> 全局
```
~/.config/opencode/opencode.json
```
> 自定义路径 > 项目
```
opencode.json
```
>
```
.opencode/
```
目录 > 内联环境变量覆盖。
```
.opencode
```
下的子目录默认使用复数命名（
```
agents/
```
、
```
commands/
```
、
```
plugins/
```
、
```
skills/
```
、
```
tools/
```
、
```
themes/
```
），为兼容旧版本也支持单数名称。

When to Invoke

调用场景

Adding or adjusting OpenWork flows that reference skills, plugins, MCP servers, or OpenCode config.
Designing onboarding guidance that mentions skill/plugin installation, config locations, or permission prompts.
Implementing UIs that surface OpenCode primitives (skills tab, plugin manager, MCP toggles).

添加或调整涉及skill、plugin、MCP服务器或OpenCode配置的OpenWork流程时。
设计包含skill/plugin安装、配置位置或权限提示的新手引导内容时。
实现展示OpenCode原语的UI（skill标签页、plugin管理器、MCP开关）时。

Usage

使用方法

Call

skill({ name: "opencode-primitives" })

before implementing or documenting any OpenWork behavior that maps to OpenCode primitives.

在实现或编写任何映射到OpenCode原语的OpenWork行为相关内容前，调用

skill({ name: "opencode-primitives" })

。