Back to Details

subagent-authoring

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Subagent Authoring

子代理编写指南

Create subagents that delegate to skills for Claude Code and OpenCode.
为Claude Code和OpenCode创建可委托至Skill的子代理。

When to Use This Skill

何时使用本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
在以下场景中使用本Skill：
  • 创建新的子代理定义
  • 重构现有代理以委托至Skill
  • 确保Claude Code与OpenCode代理实现的一致性

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/agents/<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.
代理应作为轻量包装器，将所有实现逻辑委托给Skill：
Claude Code代理（
.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代理（
.config/opencode/agents/<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

Claude Code代理结构

Frontmatter Fields

前置元数据字段

FieldRequiredDescription
name
YesAgent identifier (lowercase, no spaces)
description
Yes1-2 sentence description of what the agent does
tools
YesList of tools and skills the agent can use
model
NoSpecific model to use (e.g., 
sonnet
)
字段是否必填描述
name
是代理标识符（小写，无空格）
description
是1-2句话描述代理功能
tools
是代理可使用的工具与Skill列表
model
否指定使用的模型（例如：
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
undefined
  • Read
    , 
    Write
    , 
    Edit
    , 
    Grep
    , 
    Glob
    , 
    Bash
    - 核心工具
  • Skill(skill-name)
    - 加载指定Skill
  • Bash(command:*)
    - 允许带任意参数的bash命令（注意使用冒号）
Bash权限语法（Claude Code使用冒号，而非空格）：
yaml
undefined

Allow git commit with any arguments

允许带任意参数的git commit命令

Bash(git commit:*)
Bash(git commit:*)

Allow all git commands

允许所有git命令

Bash(git:*)
Bash(git:*)

Allow specific script

允许指定脚本

Bash(~/.agents/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
Bash(~/.agents/skills/my-skill/scripts/helper.py:*)

**示例：**
```yaml
tools: Read, Grep, Glob, Bash(git status:*), Bash(git commit:*), Skill(code-linting)
文档链接：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
子代理名称应采用以**-er后缀构成的施事名词**（意为“执行X操作的主体”）：
  • ✅ 
    git-committer
    , 
    git-stager
    , 
    code-linter
    , 
    test-runner
    , 
    task-implementer
  • ❌ 
    git-commit
    , 
    commit-helper
    , 
    committing-agent
-er后缀用于构成代理/工具类名词：
  • committer = 提交者
  • stager = 暂存者
  • implementer = 实现者

OpenCode Agent Structure

OpenCode代理结构

Frontmatter Fields

前置元数据字段

FieldRequiredDescription
description
Yes1-2 sentence description
mode
YesAgent mode (
subagent
, 
primary
)
tools
YesMap of tool names to boolean enablement
permission
YesMap of tool categories to permission rules
字段是否必填描述
description
是1-2句话描述代理功能
mode
是代理模式（
subagent
、
primary
）
tools
是工具名称与启用状态的映射表
permission
是工具类别与权限规则的映射表

tools Format

工具格式

yaml
tools:
  read: true
  grep: true
  glob: true
  bash: true
  edit: false
  write: false
  skill: true
yaml
tools:
  read: true
  grep: true
  glob: true
  bash: true
  edit: false
  write: false
  skill: true

Common tool mappings

常见工具映射

Claude ToolOpenCode Equivalent
Read
read: true
Write
write: true
Edit
edit: true
Grep
grep: true
Glob
glob: true
Bash
bash: true
Skill(x)
skill: true
Claude工具OpenCode等效配置
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
代理主体内容应控制在5-20行以内，且仅包含：
markdown
Use the `<skill-name>` skill to accomplish this task.
禁止包含：
  • 完整的实现步骤
  • Claude与OpenCode之间重复的内容
  • 超过约20行的内容

Examples

示例

Minimal Agent (Claude)

极简代理（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.
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)

极简代理（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.
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)

带Bash权限的代理（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
OpenCode在权限规则中使用空格（与Claude Code使用冒号不同）：
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.
文档链接：https://opencode.ai/docs/permissions

Primary Mode Agent (OpenCode)

主模式代理（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.
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

模式选择

ModeUse When
subagent
Agent is invoked by another agent or command
primary
Agent is the main agent handling the conversation
模式使用场景
subagent
代理由其他代理或命令调用
primary
代理是处理对话的主代理

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
  1. 单一事实源：所有实现内容都存储在Skill中
  2. 更易维护：Skill的变更会自动同步至所有代理
  3. 平台一致性：代理作为轻量包装器，仅包含平台特定配置
  4. Token效率：Skill通过渐进式披露实现按需加载
  5. 无重复内容：实现逻辑仅存在于一处

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...
错误示例 - 包含完整实现的代理：
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

When to Use This Agent PROACTIVELY

Always use immediately after:
  • Creating new source code files
  • Modifying existing code...
Always use immediately after:
  • Creating new source code files
  • Modifying existing code...

What This Agent Does

What This Agent Does

  1. Discovers all appropriate linters...
  2. Runs formatting checks...
  3. Auto-fixes issues...
  4. Reports remaining issues...
  1. Discovers all appropriate linters...
  2. Runs formatting checks...
  3. Auto-fixes issues...
  4. Reports remaining issues...

Linting Process

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.
Run linters according to repository guidelines. First look for linting commands in the following order: ...

**正确示例** - 采用委托模式的代理：

```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

工作流程

  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
  1. 先创建Skill（或确定要使用的现有Skill）
  2. 创建/重构Claude代理，配置正确的前置元数据并实现委托
  3. 创建/重构OpenCode代理，配置匹配的内容和平台特定设置
  4. 验证两个代理均能正确完成委托

Related Skills

相关Skill

  • agent-command-authoring
    - For creating commands that delegate to skills
  • skill-authoring
    - For creating skills themselves
  • agent-command-authoring
    - 用于创建可委托至Skill的命令
  • skill-authoring
    - 用于创建Skill本身