subagents-management

Subagents & Skills Management

Manage subagents, skills, and instruction files for coding agents.

Claude Code: Subagents in ~/.claude/agents/ and .claude/agents/
Codex CLI: AGENTS.md instructions + custom subagents (TOML) in ~/.codex/agents/ + skills in ~/.codex/skills/ and .agents/skills/
OpenCode: agent blocks in opencode.json AND markdown agents in ~/.config/opencode/agents/ / .opencode/agents/; AGENTS.md for instructions

IMPORTANT: After creating, modifying, or deleting subagents/skills, inform the user that they need to restart the agent for changes to take effect.

CRITICAL: Before performing any deletion operation, you MUST use the AskUserQuestion tool to confirm with the user. Never delete a subagent without explicit user confirmation, even if using --force flag or direct rm commands.

Operations

List Subagents

python3 {SKILL_PATH}/scripts/list_subagents.py [--scope user|project|all] [--json]

Create Subagent

Write a markdown file directly to the appropriate scope directory:

User scope: ~/.claude/agents/{name}.md Project scope: .claude/agents/{name}.md

Template:

---
name: {name}
description: {when Claude should use this subagent}
tools: {comma-separated tools, or omit to inherit all}
disallowedTools: {optional denylist}
model: {sonnet|opus|haiku|inherit, or full ID like claude-opus-4-7}
effort: {low|medium|high|xhigh|max}
maxTurns: {optional turn cap}
permissionMode: {default|acceptEdits|plan|auto|dontAsk|bypassPermissions}
isolation: worktree   # optional, runs agent in a fresh git worktree
background: true       # optional, run concurrently
color: blue            # optional UI color
---

{System prompt - instructions for the subagent}

Or use the helper script:

python3 {SKILL_PATH}/scripts/create_subagent.py {name} \
  --description "..." \
  --prompt "..." \
  --scope {user|project} \
  --tools "Read,Grep,Glob" \
  --model sonnet

Edit Subagent

Find the file: ~/.claude/agents/{name}.md or .claude/agents/{name}.md
Edit the frontmatter and/or system prompt using Edit tool

Move Subagent

python3 {SKILL_PATH}/scripts/move_subagent.py {name} --to {user|project} [--overwrite]

Or manually:

Read the source file
Write to target directory
Delete source file

Delete Subagent

⚠️ ALWAYS confirm with user before deleting. Use AskUserQuestion to ask: "Are you sure you want to delete the subagent '[name]'? This action cannot be undone."

python3 {SKILL_PATH}/scripts/delete_subagent.py {name} [--scope user|project] [--force]

Or delete directly (still requires user confirmation via AskUserQuestion first): rm ~/.claude/agents/{name}.md or rm .claude/agents/{name}.md

Codex CLI: AGENTS.md, Subagents & Skills

Codex uses AGENTS.md (equivalent to CLAUDE.md) for project instructions, supports custom subagents via TOML files, and shares the SKILL.md format with Claude Code.

AGENTS.md

~/.codex/AGENTS.md                # Global instructions
<project-root>/AGENTS.md          # Project instructions
<project-root>/sub/AGENTS.md      # Subdirectory instructions (additive, root → leaf)
<any-dir>/AGENTS.override.md      # Replaces AGENTS.md at that level

Configure size limits and fallbacks via project_doc_max_bytes (default 32 KiB) and project_doc_fallback_filenames in ~/.codex/config.toml.

Subagents (GA March 2026)

Codex ships three built-in subagents — default, explorer, worker — and lets you define custom ones as TOML files in ~/.codex/agents/:

# ~/.codex/agents/security-reviewer.toml
description = "Read-only security reviewer."
model = "gpt-5.5"
sandbox_mode = "read-only"
approval_policy = "never"

[features]
multi_agent = true

[agents]
max_threads = 6                   # Concurrent agent threads (default 6)
max_depth = 1                     # Max nesting; root = 0 (default 1)

[agents.security-reviewer]
config_file = "~/.codex/agents/security-reviewer.toml"
description = "Read-only security reviewer."
nickname_candidates = ["secrev"]

Custom agents may include any standard config keys (model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config). Subagents inherit the parent's interactive runtime overrides (e.g., /approvals changes, --yolo).

Skills

~/.codex/skills/<skill>/SKILL.md           # User skills (canonical default; $CODEX_HOME/skills)
~/.agents/skills/<skill>/SKILL.md          # User skills (cross-tool alias path)
<project-root>/.agents/skills/<skill>/SKILL.md  # Project skills

Skills use the same SKILL.md (YAML frontmatter) format as Claude Code and are cross-compatible across the Agent Skills standard. Stable in v0.124; the legacy codex --enable skills flag is still accepted but no longer required.

See references/codex-agents.md for the full Codex agents/skills reference.

OpenCode: agent blocks & AGENTS.md

OpenCode (anomalyco/opencode v1.14.x) supports both JSON agent blocks in opencode.json and markdown files in agents/.

AGENTS.md (instructions)

~/.config/opencode/AGENTS.md           # Global personal instructions
<project>/AGENTS.md                    # Project instructions (commit to git)

Falls back to CLAUDE.md and ~/.claude/CLAUDE.md automatically when the OpenCode equivalents are missing.

Subagents

Two equivalent forms:

JSON in opencode.json:

{
  "agent": {
    "reviewer": {
      "mode": "subagent",
      "description": "Reviews PRs for security issues",
      "model": "anthropic/claude-opus-4-5",
      "temperature": 0.1,
      "prompt": "{file:./prompts/reviewer.md}",
      "permission": {
        "edit": "deny",
        "bash": { "*": "deny", "rg *": "allow" }
      }
    }
  }
}

Markdown file at ~/.config/opencode/agents/reviewer.md or <project>/.opencode/agents/reviewer.md:

---
mode: subagent
description: Reviews PRs for security issues
model: anthropic/claude-opus-4-5
temperature: 0.1
permission:
  edit: deny
  bash:
    "*": deny
    "rg *": allow
---

You are a senior security reviewer...

OpenCode-specific fields not present in Claude Code subagents: mode (primary/subagent/all), temperature, reasoningEffort, color, granular permission glob rules, and full provider/model-id model strings.

CLI helpers:

opencode agent create   # Interactive scaffolder
opencode agent list     # List agents

See references/opencode-agents.md for the complete OpenCode agents/AGENTS.md reference.

Key Concepts (Claude Code)

User scope (~/.claude/agents/): Available in all projects
Project scope (.claude/agents/): Specific to current project, higher priority
Subagents reload on session restart or via /agents command
See references/claude-subagents.md for Claude Code subagent schema

Common Patterns

Read-only reviewer:

tools: Read, Grep, Glob
model: haiku

Full-access helper:

# omit tools field to inherit all
model: inherit

Restricted with hooks:

tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./validate.sh"

Parallel worktree-isolated worker (2026):

---
name: parallel-fixer
description: Fix lint errors in isolation
isolation: worktree
background: true
model: sonnet
maxTurns: 30
---

Tight allowlist + denylist (mind the ordering — disallowedTools is applied first):

tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: sonnet
color: blue