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):
yaml
--- 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/agent/<name>.md):
yaml
---
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 tools - •
Skill(skill-name)- Load a skill - •
Bash(command:*)- Allow bash command with any arguments (note the colon)
Bash permission syntax (Claude Code uses colons, not spaces):
yaml
# Allow git commit with any arguments Bash(git commit:*) # Allow all git commands Bash(git:*) # Allow specific script Bash(~/.claude/skills/my-skill/scripts/helper.py:*)
Example:
yaml
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
yaml
tools: read: true grep: true glob: true bash: true edit: false write: false skill: true
Common 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:
markdown
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)
yaml
--- 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)
yaml
--- 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):
yaml
---
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)
yaml
--- 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:
yaml
--- 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:
yaml
--- 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 skills - •
skill-authoring- For creating skills themselves