Maintainer Explanations

Use these short explanations in README updates, PR notes, and user summaries.

Why .agents/ For Shared Assets?

.agents/ keeps shared agent primitives vendor-neutral. OpenCode can read .agents/skills, and other coding agents increasingly support the same convention. This avoids making .claude/ or .opencode/ the source of truth for content that should work across agents.

Why opencode-plugin/?

opencode-plugin/ is a neutral package root for OpenCode adapter code and metadata. It keeps generated package files separate from existing Claude Code files and avoids taking over the repository root package.json.

Why Not .opencode/ For Shared Generated Files?

.opencode/ is active project config. OpenCode auto-loads project plugins, skills, and other config from it. Use .opencode/ only for OpenCode-specific local harnesses or config, not as a neutral generated-files bucket.

Why Not Generate .claude/?

This work adds OpenCode support. Generating .claude/ can change Claude Code behavior for existing users and is outside the default scope. Existing .claude/ files are migration input, not the generated destination.

Why TypeScript Or JavaScript?

OpenCode plugins are JavaScript/TypeScript modules. Claude hook commands cannot run directly as OpenCode plugin handlers because event payloads, timing, blocking semantics, and installation models differ.

Does This Break Claude Code Users?

It should not. Existing Claude files remain unchanged unless the user explicitly approves moving or syncing shared content. Existing Claude tests should still pass.

What Remains Shared?

Agent Skills and reusable scripts should remain shared when possible, preferably under .agents/. OpenCode-specific code should be thin adapter glue in opencode-plugin/.

What Must Happen Before Publishing?

Maintainers need an npm package name, package ownership or org access, and a publishing path such as npm trusted publishing or an NPM_TOKEN release workflow. The local OpenCode migration should not add .github/workflows/*, release workflows, publish automation, or sync workflows. After local support works, offer the ci-setup follow-up to inspect versioning and propose CI/publishing automation.

Why Is MCP Separate From The Plugin Package?

Claude plugins can bundle MCP servers through .mcp.json or inline mcpServers. OpenCode MCP servers are configured in OpenCode config under the mcp key. The OpenCode plugin package should not imply it installs MCP servers automatically; document the separate opencode.jsonc / opencode.json config patch.

How Do I Verify MCP Works?

Use opencode mcp list to check configured servers. For OAuth remote servers, run opencode mcp auth <name>. If runtime testing is available, prompt OpenCode to use the named MCP tool.

Why Do Wrappers Need Frontmatter?

OpenCode commands and agents use frontmatter for metadata such as descriptions, agent selection, mode, and prompt references. A wrapper without frontmatter may not load correctly or may be hard to find in the UI.

How Do I Verify OpenCode Sees This?

Use opencode debug skill for skills, the / palette for commands, and the @ picker for agents. If skills do not appear, check whether the OpenCode skill tool is enabled in config.

Why Not Symlink Everything?

Symlinks are useful for personal migration, but they are fragile for reusable packages and cross-platform OSS support. Prefer explicit .agents/ shared assets and package-local copies only when distribution requires them.

Why Plural .agents/ Folders?

Plural paths such as .agents/skills, .agents/commands, and .agents/agents are clearer as generated conventions and avoid relying on singular/plural priority behavior that may vary by OpenCode version.