Opencode Primitives
Implement OpenWork behavior on OpenCode skills, plugins, MCP servers, and opencode.json without guessing paths, naming rules, or permission keys.
Overview
OpenCode Primitives is an agent skill most often used in Build (also Ship security review) that references official OpenCode documentation when implementing skills, plugins, MCPs, and opencode.json behavior.
Install
npx skills add https://github.com/different-ai/openwork --skill opencode-primitivesWhat is this skill?
- Cites official OpenCode docs for skills, plugins, MCP servers, and opencode.json config with stable URLs
- Documents skill paths: .opencode/skills and ~/.config/opencode/skills with git worktree walk-up discovery
- Enforces SKILL.md frontmatter rules: name regex ^[a-z0-9]+(-[a-z0-9]+)*$, length 1-64, description 1-1024 chars
- Maps plugin locations (.opencode/plugins, global plugins) and npm plugins via opencode.json plugin + Bun install
- Ties skill access to permission.skill allow/deny/ask in opencode.json
- SKILL.md name length 1-64; description length 1-1024 characters
Adoption & trust: 733 installs on skills.sh; 15.9k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are building on OpenCode but keep guessing skill paths, naming rules, plugin install flow, or permission keys and drift from official behavior.
Who is it for?
Solo builders shipping OpenWork-style agents who need a single checklist against opencode.ai docs before merging config changes.
Skip if: Teams not using OpenCode/OpenWork, or pure application feature work with no agent runtime configuration.
When should I use this skill?
Implementing OpenWork behavior on OpenCode primitives—skills, plugins, MCP servers, opencode.json config, tools, or permissions—or when UI terminology must match official OpenCode docs.
What do I get? / Deliverables
Your agent implements skills, plugins, and MCP wiring with doc-cited paths, frontmatter constraints, and permission.skill settings aligned to OpenCode.
- Doc-aligned skill and plugin layout
- Valid SKILL.md frontmatter checklist
- permission.skill configuration guidance
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build agent-tooling because the skill anchors engineering decisions to official OpenCode primitives during implementation. Covers SKILL.md discovery, plugin folders, MCP docs, and config precedence—core agent runtime wiring for solo builders.
Where it fits
Scaffold .opencode/skills/my-skill/SKILL.md with valid frontmatter before enabling the skill in the agent UI.
Register an MCP server and cross-check paths against the official MCP docs cited in the skill.
Audit permission.skill deny rules before giving the agent network or shell tools in production.
Adjust global ~/.config/opencode plugins without breaking project-level precedence.
How it compares
Use as a doc-anchored implementation checklist, not as a replacement for reading the linked OpenCode documentation pages.
Common Questions / FAQ
Who is opencode-primitives for?
Indie agent builders implementing OpenWork on OpenCode who want consistent terminology, file locations, and permission models in code and UI.
When should I use opencode-primitives?
During Build when adding .opencode/skills, plugins, or MCP entries; during Ship security review when setting permission.skill allow/deny/ask; when debugging skill discovery up the git worktree.
Is opencode-primitives safe to install?
It is reference material citing public docs—review the Security Audits panel on this Prism page and treat npm/Bun plugin installs as supply-chain sensitive.
SKILL.md
READMESKILL.md - 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.