punkdev/cc2oc
Add and ship OpenCode support for one Claude Code plugin at a time. Includes core migration to a reviewable `opencode-plugin/` adapter, maintainer-facing docs, and follow-up CI/versioning setup for package publishing or skill-copy drift checks.
92
92%
Does it follow best practices?
Impact
97%
1.25xAverage score across 2 eval scenarios
Passed
No known issues
placement-policy.mdskills/migrate-plugin/references/
Placement Policy
Use this before deciding where generated files should go.
Default Principle
Generate shared agent primitives into .agents/ by default. Treat .claude/ as migration input and .opencode/ as active OpenCode-specific config.
OpenCode can discover several compatibility paths, but discovery support is not the same as a generation policy. The generated output should avoid surprising maintainers or changing behavior for tools they did not ask to modify.
Directory Policy
| Asset type | Default generated location | Use .opencode/ when | Use .claude/ when |
|---|---|---|---|
| Shared skills | .agents/skills/<name>/SKILL.md | The skill is intentionally OpenCode-specific | Do not generate; input-only migration source |
| Shared agents | .agents/agents/<name>.md or repo convention | The agent is intentionally OpenCode-specific | Do not generate; input-only migration source |
| Shared commands/prompts | .agents/commands/<name>.md or repo convention | The command is intentionally OpenCode-specific | Do not generate; input-only migration source |
| Shared rules/instructions | .agents/rules/ or repo convention | The instruction is intentionally OpenCode-specific | Do not generate; input-only migration source |
| MCP config | opencode.jsonc / opencode.json mcp entries | Not by default; MCP does not belong in .opencode/ folders | Do not generate; .mcp.json is input-only |
| OpenCode package code | opencode-plugin/ | Not applicable | Never |
| Local dogfooding harness | Not generated by default | .opencode/plugins/<plugin>.ts shim | Never |
If the target repo already has a clear shared convention, preserve it instead of creating a parallel tree. For newly generated shared assets, prefer .agents/.
Why .agents/ First
.agents/is agent-neutral and avoids vendor-specific source-of-truth paths..opencode/is active OpenCode project config; files there may auto-load when a developer runs OpenCode..claude/changes Claude Code behavior and should not be generated by an OpenCode support task.- A neutral shared location makes it easier to package the same assets for OpenCode, Claude Code, and future coding agents.
OpenCode-Specific Files
Use .opencode/ only when behavior is intentionally OpenCode-local:
.opencode/plugins/<plugin>.tsfor a dogfooding shim..opencode/skills/<name>/SKILL.mdfor an OpenCode-only skill..opencode/commands/,.opencode/agents/, or other OpenCode config only when the user asked for OpenCode project config rather than a reusable package.
When creating .opencode/, explain that it is active config, not a neutral output folder.
OpenCode-specific command and agent wrappers must have frontmatter. If wrapping existing Claude command or agent files, use .opencode/commands/ or .opencode/agents/ only when the user explicitly wants OpenCode project config.
Do not generate both singular and plural variants of the same config folder. Prefer plural generated paths. If a repo already has both forms, inspect for same-name conflicts before writing.
Claude Files
Do not generate new .claude/ files by default.
When a repo already has .claude/skills/, .claude/commands/, or .claude/settings.json, treat those as input. If shared content should move to .agents/, ask before moving or copying because it may change Claude Code users' workflow.
When a repo already has .claude/agents/, treat those as input too. Prefer wrappers or .agents/agents/ for new shared output rather than editing the Claude source by default.
Treat .mcp.json and .claude-plugin/plugin.json mcpServers as Claude MCP input. Convert them to OpenCode config under opencode.jsonc / opencode.json mcp; do not generate .mcp.json for OpenCode support.
Package-Local Copies
opencode-plugin/skills/ is package-local distribution content, not automatically the source of truth. Use it when npm packaging needs to include shared skills. If you copy from .agents/skills/, document the sync relationship.
Do not put MCP configuration in opencode-plugin/package.json. OpenCode MCP belongs in OpenCode config, while opencode-plugin/ contains plugin adapter code and package-local runtime assets.