Skip to content

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.

AssetClaude CodeCodexNative OpenCode V2
Project guidanceCLAUDE.md; current releases also support AGENTS.mdHierarchical AGENTS.md / AGENTS.override.mdHierarchical AGENTS.md; no CLAUDE.md fallback
Global guidance~/.claude/CLAUDE.md and ~/.claude/rules/~/.codex/AGENTS.md~/.config/opencode/AGENTS.md
Portable skill bodySKILL.md plus adjacent resourcesSKILL.md plus adjacent resourcesSKILL.md plus adjacent resources
Common skill directoryHarness discovery must be checked~/.agents/skills, project .agents/skillsAlso discovers .agents/skills and .claude/skills
Agent profileClaude Markdown/frontmatterCustom-agent TOMLOpenCode Markdown/frontmatter or agents config
Execution policyClaude settings and tool permissionsApproval/sandbox settings and execution rulesOrdered permissions rules and managed policies
Plugins and MCPClaude-specific installation/configCodex-specific installation/configOpenCode-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.

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.

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.

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.

  1. Record the installed harness version, active model/provider/workspace, and effective config sources without displaying credentials.
  2. Inventory instructions, resolved skill locations, agent profiles, tools, plugins, and hooks. Resolve duplicate IDs and missing resource paths.
  3. Load the smallest applicable guidance. Confirm with a harmless unique instruction marker and require the agent to identify the source.
  4. Qualify file reads, a controlled edit, actual tests, an expected failure, and permission denial in a disposable project. Test child-model selection separately.
  5. 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.

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.

Recent changes

  1. docs(wiki): add coding agent approval and session flag references @sac
  2. docs(wiki): publish installed OpenCode workflow and validation @sac
  3. docs(wiki): refresh OpenCode V2 orchestration and shared customization @sac