Awesome-omni-skill portable-agents

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.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data-ai/portable-agents" ~/.claude/skills/diegosouzapw-awesome-omni-skill-portable-agents-5b6a81 && rm -rf "$T"

manifest: skills/data-ai/portable-agents/SKILL.md

source content

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`	`user` / `project` / `local`	Not supported	Not supported	Not supported
`color`	Hex or theme color	Not supported	Hex or theme color	Not supported
`hidden`	Not supported	Not supported	Hide from `@` menu	Not supported

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:

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:

```
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