| name | portable-agents |
| description | Defines agent configuration formats across Claude Code, Cursor, OpenCode, and Cline. Covers frontmatter fields, tool restrictions, model selection, and cross-tool portability. ALWAYS read before creating or editing agent definitions. This skill should be used when 'writing an agent', 'creating a subagent', 'porting agents between tools', 'agent frontmatter', 'agent configuration', or setting up agents across multiple AI tools. |
| user-invocable | true |
| disable-model-invocation | false |
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
| Scope | Claude Code | Cursor | OpenCode | Cline |
|---|
| Project | .claude/agents/ | .cursor/agents/ | .opencode/agents/ | .clinerules/agents/ |
| User | ~/.claude/agents/ | ~/.cursor/agents/ | ~/.config/opencode/agents/ | N/A |
| Plugin | Plugin agents/ dir | N/A | N/A | N/A |
Priority (when names collide): CLI flags > project > user > plugin (Claude Code). Project > user (Cursor, OpenCode).
Frontmatter Compatibility Matrix
| Field | Claude Code | Cursor | OpenCode | Cline |
|---|
name | Required | Required | Filename = name | Filename = name |
description | Required | Required | Required | Required |
model | sonnet/opus/haiku/inherit | inherit only | provider/model-id | N/A |
tools | Allowlist (tool names) | Not supported | Boolean map | Not supported |
disallowedTools | Denylist (tool names) | Not supported | Not supported | Not supported |
mode | Implicit (subagent by location) | Implicit | primary/subagent/all | Implicit |
temperature | Not in frontmatter | Not in frontmatter | Supported | Not supported |
maxTurns/steps | maxTurns | Not supported | steps | Not supported |
permissionMode | 6 modes | Not supported | permission (per-tool) | Not supported |
skills | Preload skill content | Not supported | Not supported | Not supported |
mcpServers | Scope MCP per agent | Not supported | Not supported | Not supported |
hooks | Full lifecycle hooks | Not supported | Not supported | Not supported |
memory |
Portable Subset (All Tools)
The only fields guaranteed portable across all four tools:
---
name: my-agent
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.
mkdir -p ~/.agents/
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
CANONICAL_DIR="./agents-canonical"
for agent in "$CANONICAL_DIR"/*.md; do
name=$(basename "$agent" .md)
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:
| Tool | How Models Work |
|---|
| Claude Code | Aliases: sonnet, opus, haiku, inherit. Subagents default to inherit |
| Cursor | Subagents always inherit parent model. No per-agent model selection |
| OpenCode | Full provider/model-id format. Per-agent overrides in JSON config or frontmatter |
| Cline | Model set globally. No per-agent selection |
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
| Tool | Mechanism | Format |
|---|
| Claude Code | tools (allowlist) or disallowedTools (denylist) | Comma-separated tool names: Read, Grep, Glob |
| Cursor | Not supported in agent frontmatter | N/A |
| OpenCode | tools (boolean map) | tools: { write: false, edit: false, bash: false } |
| Cline | Not supported | N/A |
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:
| Aspect | Claude Code | Cursor | OpenCode | Cline |
|---|
| Spawn mechanism | Task tool | Task tool | Task tool / @mention | @mention |
| Max concurrent | 10 (queues beyond) | Limited by model | Configurable per-provider | Limited |
| Nesting | Subagents cannot spawn subagents | Subagents can nest (2026) | Subagents cannot nest | Cannot nest |
| Background | Yes (Ctrl+B or explicit) | Yes (async subagents) | Yes (run_in_background) | No |
| Resume | Yes (agent ID) | Yes (agent ID) | Yes (session navigation) | No |
| Restrict spawning | Task(worker, researcher) in tools | Not supported | permission.task glob patterns | Not supported |
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:
References
