aspiers/subagent-authoring

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 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):

# 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: 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:

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?

1. Single source of truth: Skills contain all implementation content
2. Easier maintenance: Changes to skills automatically propagate
3. Platform consistency: Agents are thin wrappers with platform-specific config
4. Token efficiency: Skills load progressively via progressive disclosure
5. 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

1. Create the skill first (or identify existing skill to use)
2. Create/refactor Claude agent with proper frontmatter and delegation
3. Create/refactor OpenCode agent with matching content and platform-specific config
4. Verify both agents delegate correctly

Related Skills

• agent-command-authoring - For creating commands that delegate to skills
• skill-authoring - For creating skills themselves