OpenCode Package Layout

Use this when creating or validating generated opencode-plugin/ files.

Default Layout

opencode-plugin/
  package.json
  src/plugin.ts
  src/tui.ts                   # only if needed
  src/state.ts                 # only if needed
  skills/<skill-name>/SKILL.md # only if publishing needs packaged skill assets
  tests/opencode-plugin.test.ts

For JavaScript-only repos:

opencode-plugin/
  package.json
  plugin.js
  skills/<skill-name>/SKILL.md # only if publishing needs packaged skill assets
  tests/opencode-plugin.test.js

Why opencode-plugin/

• It is a neutral generated package root.
• It avoids overwriting an existing root package.json.
• It keeps OpenCode adapter files separate from Claude Code plugin files.
• It can become an npm package root later.
• It does not auto-load when a developer runs OpenCode in the repo.

Do not use .opencode/ as the package root. .opencode/ is active OpenCode config and can auto-load plugins, skills, agents, commands, modes, tools, and themes.

Package Metadata Checklist

opencode-plugin/package.json should include:

• name: npm package name, ideally scoped.
• version: align with repo releases when possible.
• type: module.
• main: plugin entrypoint.
• exports: plugin entrypoint.
• files: only runtime package files.
• keywords: include opencode and opencode-plugin.
• license, repository, homepage, and author fields when known.

Example:

{
  "name": "@scope/my-plugin-opencode",
  "version": "0.1.0",
  "type": "module",
  "main": "./src/plugin.ts",
  "exports": {
    ".": "./src/plugin.ts"
  },
  "files": ["src/", "skills/"],
  "keywords": ["opencode", "opencode-plugin"],
  "license": "MIT",
  "repository": "https://github.com/owner/repo",
  "homepage": "https://github.com/owner/repo#readme"
}

If the package compiles before publishing, point main, exports, and files at compiled output instead.

Files Field Rules

Do not include agent config roots in files:

• .claude/
• .opencode/
• .agents/
• .cursor/

If package publication needs shared skills, copy or sync them into opencode-plugin/skills/ and document the source-of-truth relationship. Prefer a test or checksum/content-equality check that package-local copies match the source of truth. Do not add CI, GitHub Actions, release, publish, or sync workflows in this version.

Local Harness

Only create this when the user explicitly wants project-local OpenCode dogfooding:

.opencode/plugins/<plugin-name>.ts

Keep it as a tiny shim:

export { MyPlugin } from "../../opencode-plugin/src/plugin";

The implementation stays in opencode-plugin/.