opencode-primitives

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.

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/

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).

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.

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.

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.

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).

Usage

Call

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

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