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?

• 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 skills

• skill-authoring

• For creating skills themselves