Agents

Agent packages define autonomous workflows with system prompts, tool access, and model preferences. Claude Code, Cursor, and Codex all support agents natively but with different feature sets and file formats. This page documents how each tool discovers, loads, and runs agents.

For general information about agent packages, see Agent package type. For the generic setup mechanism, see Tool Setup Explained.

Claude Code

Claude Code has full native support for agents (called “subagents”). Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.

Reference: Claude Code subagents documentation

Discovery locations

Claude Code discovers agents from multiple locations, with higher-priority locations winning when names conflict:

Location	Scope	Priority
Managed settings	Organization-wide	1 (highest)
--agents CLI flag	Current session	2
.claude/agents/	Current project	3
~/.claude/agents/	All your projects (user-level)	4
Plugin agents/ directory	Where plugin is enabled	5 (lowest)

APKG writes agent packages to .claude/agents/ (project scope).

File paths and subfolder support

Claude Code supports multiple directory layouts. All three of the following produce the same result — an agent named test-agent:

.claude/agents/test-agent.md

.claude/agents/test-agent/test-agent.md

.claude/agents/@sheplu/test-agent/test-agent.md

The subfolder approach is what APKG uses. When you install @sheplu/test-agent, APKG creates:

.claude/agents/@sheplu/test-agent/test-agent.md

Claude Code resolves the agent name from the name field in frontmatter, not from the file path.

File format

Markdown with YAML frontmatter. The frontmatter defines configuration; the body becomes the system prompt.

---
name: research-agent
description: Researches a topic and produces a structured report
tools: Read, Grep, Glob, WebSearch, WebFetch
model: sonnet
---

You are a research agent. When asked to research a topic:

1. Search for authoritative sources.
2. Read and extract key information.
3. Synthesize findings into a structured report with sources.

Frontmatter fields

Field	Required	Description
name	Yes	Unique identifier (lowercase letters and hyphens)
description	Yes	When Claude should delegate to this agent — be specific so Claude knows when to use it
tools	No	Comma-separated list of tools the agent can use. Inherits all tools if omitted
disallowedTools	No	Tools to deny, removed from inherited or specified list
model	No	Model to use: sonnet, opus, haiku, a full model ID, or inherit (default)
permissionMode	No	Permission mode: default, acceptEdits, auto, dontAsk, bypassPermissions, plan
maxTurns	No	Maximum agentic turns before the agent stops
skills	No	Skills to preload into the agent’s context at startup
mcpServers	No	MCP servers available to this agent
hooks	No	Lifecycle hooks scoped to this agent
memory	No	Persistent memory scope: user, project, or local
background	No	If true, always run as a background task
effort	No	Effort level: low, medium, high, max
isolation	No	Set to worktree for an isolated git worktree
color	No	Display color in the UI: red, blue, green, yellow, purple, orange, pink, cyan
initialPrompt	No	Auto-submitted as the first user turn when running as main session agent

How agents are invoked

Claude Code delegates to agents automatically based on the description field. Users can also:

• Name the agent in natural language: “Use the research-agent to look into this.”
• @-mention: @"research-agent (agent)" guarantees delegation.
• Run as main agent: claude --agent research-agent starts a session using this agent’s prompt and tools.

Key capabilities

• Agents run in their own context window — they don’t consume the main conversation’s context.
• Agents can run in the foreground (blocking) or background (concurrent).
• Agents support persistent memory across conversations.
• Agents cannot spawn other subagents (no nesting).
• Agents support lifecycle hooks (PreToolUse, PostToolUse, Stop).
• Agents can scope MCP servers — connect an MCP server only when the agent runs.

---

Cursor

Cursor supports agents natively. It discovers agent definition files from multiple directories, including cross-tool compatibility with Claude Code and Codex.

Reference: Cursor subagents documentation

Discovery locations

Cursor reads agents from these directories:

Location	Notes
.cursor/agents/	Cursor’s native agents directory
.claude/agents/	Cross-compatible with Claude Code
.codex/agents/	Cross-compatible with Codex

When you configure defaultSetup.cursor, APKG installs agents into .cursor/agents/ — the native directory for Cursor. Cursor’s cross-tool discovery also means that agents installed into .claude/agents/ or .codex/agents/ by other tools are automatically available in Cursor without extra configuration.

File paths and subfolder support

Like Claude Code, Cursor supports both flat files and subfolders. All of the following produce the same result:

.cursor/agents/test-agent.md

.cursor/agents/test-agent/test-agent.md

.cursor/agents/@sheplu/test-agent/test-agent.md

APKG uses the scoped subfolder layout. When you install @sheplu/test-agent with Cursor configured, APKG creates:

.cursor/agents/@sheplu/test-agent/test-agent.md

File format

Markdown with YAML frontmatter, same as Claude Code.

---
name: research-agent
description: Researches a topic and produces a structured report
tools: Read, Grep, Glob
---

You are a research agent. Search for information and synthesize
findings into a structured report.

Frontmatter fields

Cursor supports a subset of the frontmatter fields that Claude Code uses:

Field	Supported	Description
name	Yes	Agent identifier
description	Yes	When to delegate to this agent
tools	Yes	Tools the agent can use
model	Partial	Cursor uses its own model selection; this field may be ignored
disallowedTools	No	Not supported
permissionMode	No	Not supported — Cursor manages permissions independently
maxTurns	No	Not supported
skills	No	Not supported
mcpServers	No	Not supported
hooks	No	Not supported
memory	No	Not supported
background	No	Not supported
isolation	No	Not supported

How agents are invoked

Cursor delegates to agents based on the description field, similar to Claude Code. Users can also invoke agents explicitly through Cursor’s agent picker UI.

Key differences from Claude Code

• Cross-tool discovery: Cursor reads from .claude/ and .codex/ in addition to .cursor/, making it the most compatible tool for mixed-tool teams.
• Fewer frontmatter fields: Advanced features like hooks, mcpServers, memory, isolation, and permissionMode are not supported.
• No background execution: Agents always run in the foreground.

---

Codex

Codex supports agents natively but uses TOML instead of Markdown for agent definitions. This is a key difference from Claude Code and Cursor.

Reference: Codex subagents documentation

Discovery locations

Codex reads agents from two directories:

Location	Scope
.codex/agents/	Current project
~/.codex/agents/	All your projects (user-level)

Codex does not read from .claude/agents/ or .cursor/agents/. Agent packages must be installed into .codex/agents/ to be available in Codex.

File format

TOML — not Markdown. Each .toml file defines a single agent.

name = "research-agent"
description = "Researches a topic and produces a structured report."
model = "o3"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
You are a research agent. When asked to research a topic:

1. Search for authoritative sources.
2. Read and extract key information.
3. Synthesize findings into a structured report with sources.

Always cite your sources. Do not fabricate information.
"""

Configuration fields

Field	Required	Description
name	Yes	Agent identifier
description	Yes	When Codex should spawn this agent
developer_instructions	Yes	Core behavioral instructions (equivalent to the system prompt body in Markdown agents)
model	No	Model to use. Inherits from parent session if omitted
model_reasoning_effort	No	Reasoning level (e.g. "medium")
sandbox_mode	No	Execution permissions: "read-only" or "workspace-write". Inherits from parent if omitted
nickname_candidates	No	Array of display names for spawned instances
mcp_servers	No	MCP servers available to this agent
skills.config	No	Skill configurations

How agents are invoked

Codex spawns agents only when you explicitly ask in natural language — there is no @-mention syntax or dedicated UI picker like in Claude Code or Cursor. You reference agents by name in your prompt:

“Have research-agent investigate the authentication flow and summarize findings.”

“Spawn one agent per point, wait for all of them, and summarize the result.”

Codex will not automatically delegate to an agent based on its description. You must ask for it. Once spawned, you can manage active agents with the /agent CLI command to switch between threads and inspect progress.

Built-in agents

Codex includes three built-in agents:

Agent	Purpose
default	General-purpose fallback
worker	Execution-focused tasks
explorer	Read-heavy exploration

Custom agents with matching names take precedence over built-ins.

Global agent settings

Subagent behavior can be tuned in the main config under [agents]:

Setting	Default	Description
agents.max_threads	6	Maximum concurrent agent threads
agents.max_depth	1	Maximum nesting depth
agents.job_max_runtime_seconds	—	Per-worker timeout for batch jobs

Key differences from Claude Code

• TOML, not Markdown: Agent definitions use TOML with developer_instructions instead of a Markdown body.
• No cross-tool discovery: Codex only reads from .codex/agents/, not from .claude/ or .cursor/.
• sandbox_mode instead of tools/permissionMode: Codex uses "read-only" or "workspace-write" rather than listing individual tools.
• Nesting supported: Codex supports agent nesting up to max_depth (default 1), unlike Claude Code where subagents cannot spawn other subagents.
• No hooks, memory, isolation, or background fields.

---

What APKG writes

When you install an agent package, APKG writes definition files into the tool’s agents directory based on your configured tool:

Tool	Output path	Format
Claude Code	.claude/agents/@<scope>/<name>/	Markdown
Cursor	.cursor/agents/@<scope>/<name>/	Markdown
Codex	.codex/agents/@<scope>/<name>/	TOML

Each tool gets its own native directory. If you use multiple tools, enable each in your config (e.g. defaultSetup.claude-code and defaultSetup.cursor). Cursor’s cross-tool discovery also picks up agents from .claude/agents/, so agents installed for Claude Code are visible in Cursor as well.

Fallback generation

If the agent package contains no .md definition files with frontmatter, APKG generates a summary file that includes:

• The resolved system prompt (from agent.systemPrompt in apkg.json — inline or read from file)
• Tool bindings with required/optional status
• Model preferences

---

Cross-tool compatibility

The table below summarizes which features work across the three documented tools:

Feature	Claude Code	Cursor	Codex
Native agent support	Yes	Yes	Yes
File format	Markdown	Markdown	TOML
name	Yes	Yes	Yes
description	Yes	Yes	Yes
tools	Yes	Yes	No (uses sandbox_mode)
model	Yes	Partial	Yes
System prompt / instructions	Markdown body	Markdown body	developer_instructions
Auto-delegation from description	Yes	Yes	No (explicit request only)
@-mention invocation	Yes (@"agent (agent)")	Yes	No
hooks	Yes	No (ignored)	No
mcpServers	Yes	No (ignored)	Yes (mcp_servers)
memory	Yes	No (ignored)	No
permissionMode	Yes	No (ignored)	No (uses sandbox_mode)
isolation	Yes	No (ignored)	No
background	Yes	No (ignored)	No
Subfolder support	Yes	Yes	Not documented
Reads .claude/agents/	Yes	Yes	No
Reads .cursor/agents/	No	Yes	No
Reads .codex/agents/	No	Yes	Yes

Because Codex uses TOML instead of Markdown, agent packages cannot use a single file across all three tools. APKG handles this by generating the appropriate format per tool — Markdown for Claude Code and Cursor, TOML for Codex.

When writing agent packages intended for Claude Code and Cursor, stick to the common Markdown subset: name, description, tools, and the system prompt body. Claude Code-specific fields like hooks and memory are safely ignored by Cursor.

Other tools

Windsurf and Kiro have varying levels of agent support. As their agent systems are less extensively documented, details will be added as they are verified. For now:

• Windsurf — Agents are mapped to Windsurf’s rule system. The system prompt becomes rule content.
• Kiro — Kiro has partial agent support through its steering rules.

Related pages

Page	Description
Agent package type	Manifest fields, tool bindings, and system prompt resolution
Tool Setup Explained	Detection, precedence, and the generic setup mechanism
Create an agent package	Step-by-step authoring guide