Portable Agents

Cross-Tool Agent Interoperability

Write agent definitions that work across Claude Code, Cursor, OpenCode, and Cline without duplication.

Quick Start

All four tools define agents as markdown files with YAML frontmatter. The body is the system prompt.

---
name: code-reviewer
description: Reviews code for quality and best practices
---

You are a code reviewer. Analyze code for security, performance, and maintainability.

Store agents in tool-specific directories. Unlike skills, there is no single shared directory -- each tool has its own agent location.

Agent Directories

Priority (when names collide): CLI flags > project > user > plugin (Claude Code). Project > user (Cursor, OpenCode).

Frontmatter Compatibility Matrix

Portable Subset (All Tools)

The only fields guaranteed portable across all four tools:

---
name: my-agent          # or use filename in OpenCode/Cline
description: What this agent does and when to use it
---

System prompt in markdown body.

Everything beyond name, description, and the markdown body is tool-specific. Write the core agent logic in the body, then add tool-specific frontmatter as needed.

Cross-Tool Setup

Strategy: Canonical Source + Symlinks

Maintain one source directory with canonical agent definitions, then symlink or copy to each tool's expected location.

# Canonical source
mkdir -p ~/.agents/

# Symlink to each tool
ln -sfn ~/.agents ~/.claude/agents
ln -sfn ~/.agents ~/.cursor/agents
ln -sfn ~/.agents ~/.config/opencode/agents

Caveat: OpenCode uses the filename as the agent name (no name field needed), while Claude Code and Cursor require name in frontmatter. Include name in frontmatter for maximum compatibility -- OpenCode ignores it.

Strategy: Transpiler Script

For agents that need tool-specific features (model routing, tool restrictions, permissions), maintain a canonical format and transpile:

#!/bin/bash
# sync-agents.sh - Generate tool-specific agent files from canonical source
CANONICAL_DIR="./agents-canonical"
for agent in "$CANONICAL_DIR"/*.md; do
  name=$(basename "$agent" .md)
  # Copy to each tool dir, stripping unsupported fields
  cp "$agent" ".claude/agents/$name.md"
  cp "$agent" ".cursor/agents/$name.md"
  cp "$agent" ".opencode/agents/$name.md"
done

Model Selection Across Tools

Each tool handles model assignment differently:

Portable approach: Omit model from frontmatter (defaults to inherit/parent in all tools). Override per-tool via config files when needed.

Tool Restrictions Across Tools

Portable approach: Express tool restrictions in the system prompt body as instructions ("Do NOT modify files. Only read and analyze."). This works everywhere, though it's advisory rather than enforced.

Subagent Spawning

All four tools support subagents, but the spawning mechanism differs:

Orchestration Patterns

Pattern 1: AGENTS.md Orchestration (Most Portable)

Put orchestration rules in AGENTS.md (read by all tools). The root agent decides when to delegate based on instructions, not config.

## Orchestration Rules

When the task involves:
- **Multiple files or modules**: Delegate to explore agent first
- **External libraries**: Delegate to librarian agent
- **Complex implementation**: Create a plan, then delegate to implementer
- **Architecture decisions**: Consult oracle agent

Pattern 2: Orchestrator Rule (Cursor-Specific)

Cursor supports .cursor/rules/*.mdc with alwaysApply: true for always-on orchestration. This is the pattern oh-my-cursor uses.

Pattern 3: Plugin Orchestration (OpenCode-Specific)

oh-my-opencode uses a plugin system with JSON config for model routing, categories, and provider fallback chains. See references/opencode-agents.md.

Validation Checklist

Before finalizing a portable agent:

• name is lowercase with hyphens, matches filename
• description clearly states when to delegate to this agent
• System prompt body uses imperative form
• No tool-specific features in core prompt logic
• Tool-specific frontmatter clearly commented
• model omitted or set to inherit for portability
• Tool restrictions expressed in prompt body (advisory) AND frontmatter (enforced) where supported
• Tested delegation in target tools

References

• references/claude-code-agents.md - Claude Code agent configuration and capabilities
• references/cursor-agents.md - Cursor agent configuration and capabilities
• references/opencode-agents.md - OpenCode agent configuration and capabilities
• references/agent-roster.md - Standard agent roles and their system prompts