Subagent Authoring
Create subagents that delegate to skills for Claude Code and OpenCode.
When to Use This Skill
Use this skill when:
- Creating a new subagent definition
- Refactoring an existing agent to delegate to a skill
- Ensuring consistency between Claude Code and OpenCode agent implementations
The Delegation Pattern
Agents should be thin wrappers that delegate all implementation to skills:
Claude Code agent (.claude/agents/<name>.md):
---
name: agent-name
description: Brief description of what the agent does
tools: Read, Grep, Glob, Skill(skill-name), ...
---
Use the `<skill-name>` skill to accomplish this task.OpenCode agent (.config/opencode/agents/<name>.md):
---
description: Brief description of what the agent does
mode: subagent
tools:
read: true
grep: true
glob: true
skill: true
permission:
bash:
...
---
Use the `<skill-name>` skill to accomplish this task.Claude Code Agent Structure
Frontmatter Fields
| Field | Required | Description |
|---|---|---|
name | Yes | Agent identifier (lowercase, no spaces) |
description | Yes | 1-2 sentence description of what the agent does |
tools | Yes | List of tools and skills the agent can use |
model | No | Specific model to use (e.g., sonnet) |
tools Format
Read,Write,Edit,Grep,Glob,Bash- Core toolsSkill(skill-name)- Load a skillBash(command:*)- Allow bash command with any arguments (note the colon)
Bash permission syntax (Claude Code uses colons, not spaces):
# Allow git commit with any arguments
Bash(git commit:*)
# Allow all git commands
Bash(git:*)
# Allow specific script
Bash(~/.agents/skills/my-skill/scripts/helper.py:*)Example:
tools: Read, Grep, Glob, Bash(git status:*), Bash(git commit:*), Skill(code-linting)Documentation: https://docs.anthropic.com/en/docs/claude-code/settings#tool-permissions
Naming Conventions
Subagent names should be agent nouns formed with the -er suffix (meaning "one who does X"):
- ✅
git-committer,git-stager,code-linter,test-runner,task-implementer - ❌
git-commit,commit-helper,committing-agent
The -er suffix creates agent/instrument nouns:
- committer = one who commits
- stager = one who stages
- implementer = one who implements
OpenCode Agent Structure
Frontmatter Fields
| Field | Required | Description |
|---|---|---|
description | Yes | 1-2 sentence description |
mode | Yes | Agent mode (subagent, primary) |
tools | Yes | Map of tool names to boolean enablement |
permission | Yes | Map of tool categories to permission rules |
tools Format
tools:
read: true
grep: true
glob: true
bash: true
edit: false
write: false
skill: trueCommon tool mappings
| Claude Tool | OpenCode Equivalent |
|---|---|
Read | read: true |
Write | write: true |
Edit | edit: true |
Grep | grep: true |
Glob | glob: true |
Bash | bash: true |
Skill(x) | skill: true |
Agent Body
The agent body should be 5-20 lines maximum and contain only:
Use the `<skill-name>` skill to accomplish this task.Do NOT include:
- Full implementation steps
- Duplicated content between Claude and OpenCode
- More than ~20 lines of content
Examples
Minimal Agent (Claude)
---
name: code-linter
description: Code linting specialist
tools: Read, Grep, Glob, Bash, Skill(code-linting)
---
Use the `code-linting` skill to run linters.Minimal Agent (OpenCode)
---
description: Code linting specialist
mode: subagent
tools:
read: true
grep: true
glob: true
bash: true
skill: true
---
Use the `code-linting` skill to run linters.Agent with Bash Permissions (OpenCode)
OpenCode uses spaces in permission patterns (unlike Claude Code which uses colons):
---
description: Run tests
mode: subagent
tools:
bash: true
read: true
grep: true
glob: true
skill: true
permission:
bash:
"*": "ask"
"pytest *": "allow"
"npm test": "allow"
"git status": "allow"
"git commit *": "allow"
---
Use the `test-running` skill to run tests.Documentation: https://opencode.ai/docs/permissions
Primary Mode Agent (OpenCode)
---
description: Orchestrates development workflow
mode: primary
tools:
read: true
write: true
edit: true
bash: true
grep: true
glob: true
todowrite: true
todoread: true
---
Use the `task-orchestration` skill to orchestrate the development workflow.Mode Selection
| Mode | Use When |
|---|---|
subagent | Agent is invoked by another agent or command |
primary | Agent is the main agent handling the conversation |
Why This Pattern?
- Single source of truth: Skills contain all implementation content
- Easier maintenance: Changes to skills automatically propagate
- Platform consistency: Agents are thin wrappers with platform-specific config
- Token efficiency: Skills load progressively via progressive disclosure
- No duplication: Implementation lives in one place
Anti-Pattern to Avoid
BAD - Agent with full implementation:
---
name: code-linter
description: Code linting specialist
tools: Read, Grep, Glob, Bash
---
You are a senior code reviewer responsible for ensuring that code changes pass
all linters...
## When to Use This Agent PROACTIVELY
Always use immediately after:
- Creating new source code files
- Modifying existing code...
## What This Agent Does
1. **Discovers** all appropriate linters...
2. **Runs** formatting checks...
3. **Auto-fixes** issues...
4. **Reports** remaining issues...
## Linting Process
Run linters according to repository guidelines. First look for linting
commands in the following order:
...GOOD - Agent that delegates:
---
name: code-linter
description: Code linting specialist
tools: Read, Grep, Glob, Bash, Skill(code-linting)
---
Use the `code-linting` skill to run linters.Workflow
- Create the skill first (or identify existing skill to use)
- Create/refactor Claude agent with proper frontmatter and delegation
- Create/refactor OpenCode agent with matching content and platform-specific config
- Verify both agents delegate correctly
Related Skills
agent-command-authoring- For creating commands that delegate to skillsskill-authoring- For creating skills themselves