Commands And Agents

Use this when a repo has .claude/commands/, .claude/agents/, or the user asks to migrate commands or agents.

Placement Policy

Existing Claude commands and agents are migration input. Do not generate new .claude/commands/ or .claude/agents/ as part of OpenCode support.

Default generated shared locations:

• Shared commands/prompts: .agents/commands/<name>.md or the repo's established shared convention.
• Shared agents: .agents/agents/<name>.md or the repo's established shared convention.

OpenCode-specific wrappers belong under .opencode/commands/ or .opencode/agents/ only when the user explicitly wants project-local OpenCode config. These are active OpenCode config files, not neutral package output.

Command Wrappers Need Frontmatter

OpenCode command wrappers should start with frontmatter. Without frontmatter, wrappers may not load or may load without useful metadata.

Minimal OpenCode command wrapper:

---
description: Enforce code discipline checklist
agent: build
---
@.claude/commands/enforce-code-disciplines.md

Use wrapper references when the goal is to keep existing Claude command files intact. If creating a new shared command, prefer .agents/commands/ rather than a wrapper around .claude/.

Agent Wrappers Need Frontmatter

OpenCode agent wrappers should also start with frontmatter and can point at an existing prompt file.

Minimal OpenCode agent wrapper:

---
description: Senior code reviewer
mode: subagent
prompt: "{file:~/.claude/agents/senior-code-reviewer.md}"
---

Use wrappers when preserving an existing Claude prompt as the source is the user's explicit goal. If creating a new shared agent, prefer .agents/agents/.

Singular And Plural Folder Caveat

OpenCode has supported singular and plural config folder names in some versions. Do not rely on this for generated output.

• Prefer plural folders for generated shared assets: .agents/skills, .agents/commands, .agents/agents, .agents/rules.
• Do not generate both singular and plural variants.
• If a repo already has both singular and plural OpenCode folders, inspect for same-name conflicts before writing.
• Treat any same-name priority behavior as implementation behavior that must be tested, not as a design dependency.

Symlink Guidance

Symlinks can be useful for personal migration or local dogfooding, but they are not the default for reusable OSS/package support.

Prefer explicit .agents/ shared assets and opencode-plugin/ package code. Avoid symlinks in package contents unless intentionally tested across platforms.

Verification

After generating wrappers or shared assets, verify the relevant user-facing surfaces:

• Skills: opencode debug skill lists expected skills.
• Commands: / palette shows expected commands.
• Agents: @ picker shows expected agents.
• Wrappers: generated command/agent wrappers have frontmatter.