Sharing Coding Agent Rules, Skills, and Agents
Sharing Coding Agent Rules, Skills, and Agents
Section titled “Sharing Coding Agent Rules, Skills, and Agents”Keep project knowledge portable while retaining each harness’s execution controls. A shared Markdown file can describe a build; it cannot make another runtime’s tool names, plugins, permissions, or authentication work.
Reviewed 2026-10-21. This guide distinguishes native OpenCode V2 from Claude Code using an OpenCode Go gateway. The latter still uses Claude’s customization system.
What carries across?
Section titled “What carries across?”| Asset | Claude Code | Codex | Native OpenCode V2 |
|---|---|---|---|
| Project guidance | CLAUDE.md; current releases also support AGENTS.md | Hierarchical AGENTS.md / AGENTS.override.md | Hierarchical AGENTS.md; no CLAUDE.md fallback |
| Global guidance | ~/.claude/CLAUDE.md and ~/.claude/rules/ | ~/.codex/AGENTS.md | ~/.config/opencode/AGENTS.md |
| Portable skill body | SKILL.md plus adjacent resources | SKILL.md plus adjacent resources | SKILL.md plus adjacent resources |
| Common skill directory | Harness discovery must be checked | ~/.agents/skills, project .agents/skills | Also discovers .agents/skills and .claude/skills |
| Agent profile | Claude Markdown/frontmatter | Custom-agent TOML | OpenCode Markdown/frontmatter or agents config |
| Execution policy | Claude settings and tool permissions | Approval/sandbox settings and execution rules | Ordered permissions rules and managed policies |
| Plugins and MCP | Claude-specific installation/config | Codex-specific installation/config | OpenCode-specific installation/config |
Sources: Claude memory and rules, Codex instructions, Codex skills, and OpenCode instructions.
Current Claude versions default to preferring CLAUDE.md when both instruction filenames exist in a directory. An explicit import or the documented both-files option can include AGENTS.md. The monorepo currently imports it from CLAUDE.md. Codex’s default project instruction cap is 32 KiB; OpenCode combines guidance without resolving contradictory instructions. Avoid copying every historical instruction into every global prompt.
A maintainable layout
Section titled “A maintainable layout”Put essential repository commands, ownership, verification, and shared constraints in root AGENTS.md. Keep focused guidance near the code it covers. Retain Claude-specific configuration in CLAUDE.md and .claude, and use an explicit OpenCode instructions entry for legacy guidance still required during migration.
Keep one maintained source for a portable skill and preserve its scripts, references, and assets together. Copying just SKILL.md can break relative references. Use verified links or the runtime’s additional-source settings where supported. Do not overwrite managed synced skills or create duplicate names without checking which definition wins.
A useful shared skill describes its trigger, necessary domain knowledge, expected artifacts, and verification. Harness-specific dispatch and tool calls belong in an adapter or clearly identified section. For example, Claude’s Bash, Vibe’s tool identifiers, and OpenCode V2’s shell cannot be substituted by copying frontmatter.
OpenCode skill discovery
Section titled “OpenCode skill discovery”V2 recursively discovers SKILL.md under its own locations and compatible Claude/agents directories. Runtime IDs come from the path; the frontmatter name is a display label. Later sources can replace the same ID. Check resolved locations, especially with nested account-synced directories.
Discovery does not enforce every Claude extension: allowed-tools, fork behavior, argument expansion, plugin tool references, and user-invocation settings require runtime-specific review. metadata.opencode/autoinvoke: false can remove a skill from automatic suggestions while retaining explicit use. See OpenCode skills.
Convert agents deliberately
Section titled “Convert agents deliberately”Port a reviewer by preserving its review criteria and evidence format, then assigning a model and actual tool restrictions in the destination runtime. A copied readonly: true field or “do not edit” paragraph is not proof that writes are blocked. OpenCode children use their own permissions; restrict write-capable MCP tools as well as file editing and shell access.
Start a security reviewer without shell execution and pass it the diff and check results. If it needs commands, add narrowly chosen read operations rather than a general shell. Verify a deliberately denied edit fails in a disposable project. Reviewers still need findings checked against real code.
See OpenCode agents and Codex custom agents for their different schemas. Agent descriptions help dispatch; neither framework guarantees an optimal model assignment.
Rules, plugins, and memory are different assets
Section titled “Rules, plugins, and memory are different assets”Claude’s .claude/rules/*.md are natural-language instructions. Codex execution rules use a separate policy format; do not rename them into Markdown and assume equivalent enforcement. Codex rules describe command approval, while repository instructions describe expected behavior.
A Claude or Codex plugin can depend on proprietary tools, a particular account, or an app runtime. Transfer an equivalent capability through a supported OpenCode plugin or MCP configuration only after checking authentication, tool names, and behavior. V1 OpenCode plugins also need the V2 plugin migration.
Automatic memories may contain private task history and assumptions. Bring over selected, reviewed project facts when needed; do not bulk-import conversation archives into a new provider’s context.
Flags to know: approvals and saved sessions
Section titled “Flags to know: approvals and saved sessions”The harness keeps its own launch and history controls. Common entrypoints are claude --dangerously-skip-permissions, codex --dangerously-bypass-approvals-and-sandbox, vibe --yolo, and native opencode --auto. They are not interchangeable permission policies: OpenCode retains explicit denies, while Codex’s full bypass also disables its command sandbox.
Continue with claude --continue, codex resume --last, vibe --continue, or opencode --continue. Use each tool’s session picker or explicit session ID for older work; conversation forks do not create filesystem isolation. See the current cross-agent flag table and the tool-specific guides for resume/fork, headless, model, directory and output options. Flags were checked against installed help on 2026-10-21.
Migration and verification
Section titled “Migration and verification”- Record the installed harness version, active model/provider/workspace, and effective config sources without displaying credentials.
- Inventory instructions, resolved skill locations, agent profiles, tools, plugins, and hooks. Resolve duplicate IDs and missing resource paths.
- Load the smallest applicable guidance. Confirm with a harmless unique instruction marker and require the agent to identify the source.
- Qualify file reads, a controlled edit, actual tests, an expected failure, and permission denial in a disposable project. Test child-model selection separately.
- Measure token/cache usage, latency, retries, and accepted task quality before broadening access or concurrency.
Use native diagnostics such as opencode debug agents, opencode plugin list, and the documented skill API. Inspect returned metadata privately: a full skill dump can include internal procedures and may be truncated by the CLI. A list of skills proves discovery, not correct execution.
Vibe uses its own configuration and profiles. If its global AGENTS.md is generated, change the generator/source rather than the generated file. See Vibe setup and headless verification.
Installed shared-skill repair
Section titled “Installed shared-skill repair”The 2026-10-21 Mac follow-up repaired three NUL-filled skill entrypoints (team-swarm, team-cloudflare, claudeflare) and refreshed vibe-orchestrator and agent-reliability. Maintained sources and a scoped backup/install script now live in dotfiles. Adjacent references and the historical reliability log were preserved; the new entrypoint points at dated corrections. Do not treat old instructions in retained historical files as current execution policy.
Native build retains its provider coding system prompt. GLM scout/reviewer use explicit deny-all rules with read/glob exceptions, rather than copied Claude frontmatter or prose-only restrictions. Actual child routing and native permission evaluation were checked; the repaired reliability skill was loaded and exercised through OpenCode. The local receipt separates these canaries from the larger earlier synthetic benchmark.