opencode-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use this skill

何时使用此功能

Use this skill when:

User asks to create a new OpenCode agent
User wants to modify or configure an existing agent
User mentions agent modes (primary, subagent)
User wants to control tool permissions or access
User needs specialized agents for specific tasks (review, security, docs, etc.)
User mentions agent switching, task delegation, or @ mentions
User wants to customize prompts or models for different workflows

在以下场景使用此功能：

用户要求创建新的OpenCode Agent
用户想要修改或配置现有Agent
用户提及Agent模式（主Agent、子Agent）
用户想要控制工具权限或访问权限
用户需要针对特定任务的专属Agent（代码审查、安全审计、文档撰写等）
用户提及Agent切换、任务委派或@提及
用户想要为不同工作流自定义提示词或模型

What OpenCode agents are

什么是OpenCode Agent

OpenCode agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access.

OpenCode Agent是可针对特定任务和工作流进行配置的专业AI助手。你可以通过自定义提示词、模型和工具访问权限，打造专注于特定场景的工具。

Agent types

Agent类型

Primary agents: Main assistants you interact with directly. Switch between them using Tab key or configured keybind.

Examples: Build (default with all tools), Plan (restricted for analysis)

Subagents: Specialized assistants invoked by primary agents or via @ mention.

Examples: General (multi-step tasks), Explore (read-only codebase exploration)

主Agent：直接与用户交互的主要助手。使用Tab键或已配置的快捷键在不同主Agent间切换。

示例：Build（默认Agent，拥有全部工具权限）、Plan（仅用于分析的受限Agent）

子Agent：由主Agent调用或通过**@提及**唤起的专业助手。

示例：General（处理多步骤任务）、Explore（只读式代码库探索）

Built-in agents

内置Agent

Build (primary): Default agent with all tools enabled for full development work
Plan (primary): Restricted agent for planning/analysis without making changes
General (subagent): General-purpose for complex questions and multi-step tasks
Explore (subagent): Fast, read-only agent for exploring codebases

Build（主Agent）：默认Agent，启用全部工具，适用于完整开发工作
Plan（主Agent）：受限Agent，仅用于规划/分析，无法进行修改操作
General（子Agent）：通用型Agent，处理复杂问题和多步骤任务
Explore（子Agent）：快速只读Agent，用于探索代码库

Configuration methods

配置方式

Agents can be configured in two ways:

Agent有两种配置方式：

1. JSON configuration

1. JSON配置

Add agents to

opencode.json

config file:

json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "agent-name": {
      "description": "What the agent does and when to use it",
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "prompt": "{file:./prompts/agent-name.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      },
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

将Agent添加到

opencode.json

配置文件中：

json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "agent-name": {
      "description": "What the agent does and when to use it",
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "prompt": "{file:./prompts/agent-name.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      },
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

2. Markdown files

2. Markdown文件

Place markdown files in:

Global:
```
~/.config/opencode/agents/
```
Per-project:
```
.opencode/agents/
```

The filename becomes the agent name (e.g.,

review.md

creates

review

agent).

markdown

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
  webfetch: deny
---

You are in code review mode. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

将Markdown文件放置在以下位置：

全局配置：
```
~/.config/opencode/agents/
```
项目级配置：
```
.opencode/agents/
```

文件名即为Agent名称（例如，

review.md

会创建

review

Agent）。

markdown

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
  webfetch: deny
---

You are in code review mode. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

Configuration options

配置选项

Required fields

必填字段

description

Brief description of what the agent does and when to use it.

Required: Yes (for custom agents)
Constraints: Clear, actionable description with keywords

json

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

对Agent的功能及使用场景的简要描述。

必填：是（针对自定义Agent）
约束：清晰、可执行的描述，包含关键词

json

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

Optional fields

可选字段

mode

Determines how the agent can be used.

Values:
```
"primary"
```
,
```
"subagent"
```
,
```
"all"
```
(default if not specified)
Primary: Main assistants you interact with directly (switchable via Tab)
Subagent: Specialized assistants invoked by other agents or @ mention

json

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

定义Agent的使用方式。

可选值：
```
"primary"
```
、
```
"subagent"
```
、
```
"all"
```
（未指定时默认值）
主Agent：直接与用户交互的主要助手（可通过Tab键切换）
子Agent：由其他Agent调用或通过@提及唤起的专业助手

json

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

model

Override the model for this agent.

Format:
```
provider/model-id
```

Examples:

anthropic/claude-sonnet-4-20250514

openai/gpt-5

opencode/gpt-5.1-codex

Primary agents use globally configured model if not specified
Subagents use the invoking primary agent's model if not specified

json

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

为该Agent指定专属模型。

格式：
```
provider/model-id
```

示例：

anthropic/claude-sonnet-4-20250514

、

openai/gpt-5

、

opencode/gpt-5.1-codex

主Agent未指定时使用全局配置的模型
子Agent未指定时使用调用它的主Agent的模型

json

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

temperature

Control randomness and creativity of responses.

Range: 0.0 to 1.0
0.0-0.2: Very focused and deterministic (code analysis, planning)
0.3-0.5: Balanced with some creativity (general development)
0.6-1.0: More creative and varied (brainstorming, exploration)
Default: 0 for most models, 0.55 for Qwen models

json

{
  "agent": {
    "analyze": {
      "temperature": 0.1
    },
    "brainstorm": {
      "temperature": 0.7
    }
  }
}

控制响应的随机性和创造性。

范围：0.0 至 1.0
0.0-0.2：高度聚焦且确定（代码分析、规划）
0.3-0.5：平衡聚焦与创造性（通用开发）
0.6-1.0：更具创造性和多样性（头脑风暴、探索）
默认值：大多数模型为0，Qwen模型为0.55

json

{
  "agent": {
    "analyze": {
      "temperature": 0.1
    },
    "brainstorm": {
      "temperature": 0.7
    }
  }
}

prompt

Custom system prompt file for this agent.

Format:
```
{file:./path/to/prompt.txt}
```
Path: Relative to config file location
Works for both global and project-specific configs

json

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

为该Agent指定自定义系统提示词文件。

格式：
```
{file:./path/to/prompt.txt}
```
路径：相对于配置文件的位置
适用于全局和项目级配置

json

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

tools

Control which tools are available to this agent.

Values:
```
true
```
(enable),
```
false
```
(disable)
Can use wildcards:
```
"mymcp_*": false
```
Agent-specific config overrides global config

json

{
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "edit": false,
        "bash": false,
        "mymcp_*": false
      }
    }
  }
}

控制Agent可访问的工具。

值：
```
true
```
（启用）、
```
false
```
（禁用）
支持通配符：
```
"mymcp_*": false
```
Agent专属配置会覆盖全局配置

json

{
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "edit": false,
        "bash": false,
        "mymcp_*": false
      }
    }
  }
}

permission

Manage what actions an agent can take.

Values:
```
"ask"
```
(prompt for approval),
```
"allow"
```
(no approval needed),
```
"deny"
```
(disable)
Supported tools:
```
edit
```
,
```
bash
```
,
```
webfetch
```
Can set permissions for specific bash commands with glob patterns
Last matching rule takes precedence

json

{
  "agent": {
    "build": {
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git diff *": "allow",
          "git push": "ask"
        },
        "webfetch": "allow"
      }
    }
  }
}

管理Agent可执行的操作。

值：
```
"ask"
```
（需用户批准）、
```
"allow"
```
（无需批准）、
```
"deny"
```
（禁用）
支持的工具：
```
edit
```
、
```
bash
```
、
```
webfetch
```
可使用通配符模式为特定bash命令设置权限
最后匹配的规则优先级最高

json

{
  "agent": {
    "build": {
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git diff *": "allow",
          "git push": "ask"
        },
        "webfetch": "allow"
      }
    }
  }
}

Task permissions

Control which subagents an agent can invoke via the Task tool.

Uses glob patterns for flexible matching
```
"deny"
```
removes subagent from Task tool description
Last matching rule wins
Users can always invoke any subagent directly via @ mention

json

{
  "agent": {
    "orchestrator": {
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

控制Agent可通过Task工具调用哪些子Agent。

使用通配符模式实现灵活匹配
```
"deny"
```
会将子Agent从Task工具描述中移除
最后匹配的规则优先级最高
用户始终可以通过@提及直接调用任何子Agent

json

{
  "agent": {
    "orchestrator": {
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

maxSteps

Maximum number of agentic iterations before text-only response.

Type: Number
Controls cost by limiting iterations
Agent receives summary prompt when limit reached
If not set, agent continues until model stops or user interrupts

json

{
  "agent": {
    "quick-thinker": {
      "maxSteps": 5
    }
  }
}

Agent在转为纯文本响应前的最大迭代次数。

类型：数字
通过限制迭代次数控制成本
达到限制时，Agent会收到总结提示词
未设置时，Agent会持续运行直到模型停止或用户中断

json

{
  "agent": {
    "quick-thinker": {
      "maxSteps": 5
    }
  }
}

disable

Disable the agent.

Values:
```
true
```
(disable),
```
false
```
(enable)

json

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

禁用该Agent。

值：
```
true
```
（禁用）、
```
false
```
（启用）

json

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

hidden

Hide subagent from @ autocomplete menu.

Values:
```
true
```
(hidden),
```
false
```
(visible)
Only applies to
```
mode: subagent
```
Can still be invoked programmatically via Task tool

json

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

在@自动补全菜单中隐藏子Agent。

值：
```
true
```
（隐藏）、
```
false
```
（显示）
仅适用于
```
mode: subagent
```
仍可通过Task工具以编程方式调用

json

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

Additional provider-specific options

Any other options are passed directly to the provider.

Example: OpenAI reasoning models support
```
reasoningEffort
```
,
```
textVerbosity
```

json

{
  "agent": {
    "deep-thinker": {
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

其他所有选项会直接传递给供应商。

示例：OpenAI推理模型支持
```
reasoningEffort
```
、
```
textVerbosity
```

json

{
  "agent": {
    "deep-thinker": {
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

Creating agents step-by-step

逐步创建Agent

Using the CLI command

使用CLI命令

The fastest way to create an agent:

bash

opencode agent create

This interactive command will:

Ask where to save (global or project-specific)
Prompt for description
Generate appropriate system prompt and identifier
Let you select which tools can be accessed
Create a markdown file with the configuration

创建Agent的最快方式：

bash

opencode agent create

这个交互式命令会：

询问保存位置（全局或项目级）
提示输入描述信息
生成合适的系统提示词和标识符
让你选择Agent可访问的工具
创建包含配置信息的Markdown文件

Manual creation process

手动创建流程

1. Gather requirements

1. 收集需求

Ask the user:

What should the agent do?
When should it be used?
Should it be a primary agent or subagent?
What tools does it need access to?
Should any operations require approval?
What model is best suited for the task?
Should it have a custom prompt?

询问用户：

Agent的功能是什么？
何时应该使用它？
应该是主Agent还是子Agent？
需要访问哪些工具？
哪些操作需要用户批准？
哪种模型最适合该任务？
是否需要自定义提示词？

2. Choose agent name

2. 选择Agent名称

Use lowercase with hyphens (for markdown files)
Keep it short and descriptive
Examples:
```
review
```
,
```
security-audit
```
,
```
docs-writer
```

使用小写字母加连字符（适用于Markdown文件）
保持简短且描述性
示例：
```
review
```
、
```
security-audit
```
、
```
docs-writer
```

3. Write clear description

3. 编写清晰的描述

Include:

What the agent does
When to use it
Keywords for agent matching

Good: "Reviews code for best practices and potential issues" Poor: "Helps with code"

包含：

Agent的功能
使用场景
用于Agent匹配的关键词

优秀示例："Reviews code for best practices and potential issues" 糟糕示例："Helps with code"

4. Select mode

4. 选择模式

Primary: User switches to it directly (Tab key)
Subagent: Invoked by other agents or @ mention
All: Can be used both ways (default)

主Agent：用户可直接切换到该Agent（Tab键）
子Agent：由其他Agent调用或通过@提及唤起
All：可同时作为主Agent和子Agent使用（默认）

5. Configure tools and permissions

5. 配置工具和权限

Decide which tools to enable/disable:

Write operations (
```
write
```
,
```
edit
```
)
Shell commands (
```
bash
```
)
Web fetching (
```
webfetch
```
)
MCP tools (wildcards like
```
mymcp_*
```
)

Set permissions:

```
allow
```
: No approval needed
```
ask
```
: Prompt before execution
```
deny
```
: Completely disable

确定要启用/禁用的工具：

写入操作（
```
write
```
、
```
edit
```
）
Shell命令（
```
bash
```
）
网页抓取（
```
webfetch
```
）
MCP工具（使用通配符如
```
mymcp_*
```
）

设置权限：

```
allow
```
：无需批准
```
ask
```
：执行前需提示用户批准
```
deny
```
：完全禁用

6. Choose model and temperature

6. 选择模型和温度参数

Fast models for planning:
```
anthropic/claude-haiku-4-20250514
```
Capable models for implementation:
```
anthropic/claude-sonnet-4-20250514
```
Temperature: lower (0.1) for focused work, higher (0.7) for creative tasks

规划任务使用快速模型：
```
anthropic/claude-haiku-4-20250514
```
实现任务使用功能强大的模型：
```
anthropic/claude-sonnet-4-20250514
```
温度参数：聚焦工作使用较低值（0.1），创意任务使用较高值（0.7）

7. Write custom prompt (optional)

7. 编写自定义提示词（可选）

If the agent needs specialized instructions:

Create a prompts directory (e.g.,
```
./prompts/
```
)
Write a
```
.txt
```
or
```
.md
```
file with instructions
Reference it:
```
{file:./prompts/agent-name.txt}
```

如果Agent需要专属指令：

创建提示词目录（例如
```
./prompts/
```
）
编写
```
.txt
```
或
```
.md
```
文件，包含指令内容
在配置中引用该文件：
```
{file:./prompts/agent-name.txt}
```

8. Decide on configuration format

8. 选择配置格式

JSON: Better for complex configs, good for global agents
Markdown: Better for prompt-heavy agents, good for project-specific

JSON：适合复杂配置，适用于全局Agent
Markdown：适合侧重提示词的Agent，适用于项目级Agent

9. Create the configuration

9. 创建配置文件

For Markdown (recommended for most use cases):

bash

undefined

Markdown格式（推荐大多数场景使用）：

bash

undefined

Global

全局配置

mkdir -p ~/.config/opencode/agents touch ~/.config/opencode/agents/agent-name.md

Project-specific

项目级配置

mkdir -p .opencode/agents touch .opencode/agents/agent-name.md


For JSON:

```bash

mkdir -p .opencode/agents touch .opencode/agents/agent-name.md


JSON格式：

```bash

Edit opencode.json (global or project .opencode/config.json)

编辑opencode.json（全局或项目级.opencode/config.json）

undefined

undefined

10. Validate configuration

10. 验证配置

Check that:

Description is clear and keyword-rich
Mode is appropriate for use case
Tools match agent's purpose
Permissions prevent unwanted actions
Model is appropriate for task complexity
Temperature matches desired creativity level
Custom prompt (if any) is well-structured

检查以下内容：

描述清晰且包含关键词
模式符合使用场景
工具与Agent用途匹配
权限可防止不必要的操作
模型适合任务复杂度
温度参数匹配所需的创造性
自定义提示词（如有）结构合理

Common agent patterns

常见Agent模式

Read-only analysis agent

只读分析Agent

json

{
  "agent": {
    "analyzer": {
      "description": "Analyzes code for patterns and insights without making changes",
      "mode": "subagent",
      "temperature": 0.1,
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

json

{
  "agent": {
    "analyzer": {
      "description": "Analyzes code for patterns and insights without making changes",
      "mode": "subagent",
      "temperature": 0.1,
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

Security auditor

安全审计Agent

markdown

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
permission:
  bash:
    "*": deny
    "grep *": allow
    "git log*": allow
---

You are a security expert. Focus on identifying potential security issues.

Look for:
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

markdown

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
permission:
  bash:
    "*": deny
    "grep *": allow
    "git log*": allow
---

You are a security expert. Focus on identifying potential security issues.

Look for:
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

Documentation writer

文档撰写Agent

json

{
  "agent": {
    "docs-writer": {
      "description": "Writes and maintains project documentation",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "tools": {
        "bash": false
      },
      "prompt": "{file:./prompts/docs-writer.txt}"
    }
  }
}

json

{
  "agent": {
    "docs-writer": {
      "description": "Writes and maintains project documentation",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "tools": {
        "bash": false
      },
      "prompt": "{file:./prompts/docs-writer.txt}"
    }
  }
}

Careful build agent with approvals

需批准的谨慎开发Agent

json

{
  "agent": {
    "careful-build": {
      "description": "Development agent that asks before making changes",
      "mode": "primary",
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status": "allow",
          "git diff": "allow"
        }
      }
    }
  }
}

json

{
  "agent": {
    "careful-build": {
      "description": "Development agent that asks before making changes",
      "mode": "primary",
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status": "allow",
          "git diff": "allow"
        }
      }
    }
  }
}

Specialized reviewer with git access

具备Git访问权限的专业审查Agent

markdown

---
description: Reviews code changes using git history and diffs
mode: subagent
temperature: 0.1
tools:
  write: false
  edit: false
permission:
  bash:
    "*": deny
    "git diff*": allow
    "git log*": allow
    "git show*": allow
---

You are a code reviewer with access to git history.

Review process:
1. Use `git diff` to see changes
2. Use `git log` for context
3. Analyze for quality, security, performance
4. Provide constructive feedback

markdown

---
description: Reviews code changes using git history and diffs
mode: subagent
temperature: 0.1
tools:
  write: false
  edit: false
permission:
  bash:
    "*": deny
    "git diff*": allow
    "git log*": allow
    "git show*": allow
---

You are a code reviewer with access to git history.

Review process:
1. Use `git diff` to see changes
2. Use `git log` for context
3. Analyze for quality, security, performance
4. Provide constructive feedback

Orchestrator with limited subagent access

限制子Agent访问权限的编排Agent

json

{
  "agent": {
    "orchestrator": {
      "description": "Coordinates multiple specialized agents for complex tasks",
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "explore": "allow",
          "docs-writer": "allow",
          "security-audit": "ask"
        }
      }
    }
  }
}

json

{
  "agent": {
    "orchestrator": {
      "description": "Coordinates multiple specialized agents for complex tasks",
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "explore": "allow",
          "docs-writer": "allow",
          "security-audit": "ask"
        }
      }
    }
  }
}

Agent usage guide

Agent使用指南

Switching primary agents

切换主Agent

Use Tab key to cycle through primary agents
Or use configured
```
switch_agent
```
keybind

使用Tab键循环切换主Agent
或使用已配置的
```
switch_agent
```
快捷键

Invoking subagents

唤起子Agent

Automatic: Primary agents invoke based on descriptions
Manual: @ mention in message (e.g.,
```
@review please check this code
```
)

自动唤起：主Agent根据描述信息自动调用
手动唤起：在消息中使用@提及（例如，
```
@review please check this code
```
）

Navigating between sessions

在会话间切换

When subagents create child sessions:

<Leader>+Right: Cycle forward (parent → child1 → child2 → parent)
<Leader>+Left: Cycle backward (parent ← child1 ← child2 ← parent)

当子Agent创建子会话时：

<Leader>+Right：向前循环切换（父会话 → 子会话1 → 子会话2 → 父会话）
<Leader>+Left：向后循环切换（父会话 ← 子会话1 ← 子会话2 ← 父会话）

Use cases by agent type

按Agent类型划分的使用场景

Primary agents

主Agent

Build: Full development work with all tools
Plan: Analysis and planning without changes
Careful-build: Development with approval prompts
Fast-build: Quick iterations with faster model

Build：完整开发工作，拥有全部工具权限
Plan：仅用于分析和规划，无法进行修改
Careful-build：开发过程中需提示用户批准
Fast-build：使用快速模型进行快速迭代

Subagents

子Agent

Review: Code review with read-only access
Debug: Investigation with bash and read tools
Docs: Documentation writing without system commands
Security: Security audits with limited tool access
Explore: Fast codebase exploration (built-in)
General: Multi-step complex tasks (built-in)

Review：代码审查，仅拥有只读权限
Debug：问题排查，拥有bash和只读工具权限
Docs：文档撰写，无系统命令权限
Security：安全审计，拥有有限工具权限
Explore：快速代码库探索（内置）
General：处理多步骤复杂任务（内置）

Best practices

最佳实践

Agent design

Agent设计

Single responsibility: Each agent should have a clear, focused purpose
Descriptive names: Use names that clearly indicate the agent's role
Rich descriptions: Include what the agent does AND when to use it
Appropriate permissions: Grant only the tools needed for the task
Temperature matching: Lower for deterministic tasks, higher for creative work

单一职责：每个Agent应具备清晰、专注的用途
描述性名称：使用能明确体现Agent角色的名称
丰富的描述：包含Agent的功能及使用场景
合理的权限：仅授予完成任务所需的工具权限
匹配的温度参数：确定性任务使用较低温度，创意任务使用较高温度

Tool configuration

工具配置

Principle of least privilege: Disable tools not needed for the agent's purpose
Use permissions wisely:
```
ask
```
for dangerous operations,
```
allow
```
for safe ones
Bash command granularity: Allow specific safe commands, ask for risky ones
Test thoroughly: Ensure the agent can complete its tasks with given tools

最小权限原则：禁用Agent任务不需要的工具
合理使用权限:
```
ask
```
用于危险操作，
```
allow
```
用于安全操作
Bash命令粒度：允许特定安全命令，对危险命令使用
```
ask
```
彻底测试：确保Agent在给定工具权限下能完成任务

Prompt engineering

提示词工程

Clear instructions: Be specific about what the agent should do
Include examples: Show expected behavior and output format
Edge case handling: Document how to handle unusual situations
Consistent style: Match the project's coding standards and conventions

清晰的指令：明确说明Agent应执行的操作
包含示例：展示预期行为和输出格式
边缘情况处理：说明如何处理异常情况
风格一致：匹配项目的编码标准和约定

Organization

组织管理

Global vs project: Global for general-purpose, project for specific needs
Markdown for prompts: Use markdown format when custom prompts are primary
JSON for config: Use JSON when managing multiple related agents
Version control: Commit project-specific agents to git

全局与项目级：全局配置用于通用Agent，项目级配置用于特定需求
Markdown用于提示词：侧重提示词的Agent使用Markdown格式
JSON用于配置：管理多个相关Agent时使用JSON格式
版本控制：将项目级Agent配置提交到Git

Performance

性能优化

Use fast models for planning: Haiku for analysis, Sonnet for implementation
Set maxSteps: Limit iterations for cost control
Progressive disclosure: Keep agents focused, use task delegation
Cache-friendly prompts: Shorter, stable prompts cache better

规划任务使用快速模型：Haiku用于分析，Sonnet用于实现
设置maxSteps：限制迭代次数以控制成本
渐进式披露：保持Agent专注，使用任务委派
缓存友好的提示词：简短稳定的提示词缓存效果更好

Troubleshooting

故障排除

Agent not appearing

Agent未显示

Check
```
disable: false
```
is set (or option not present)
For subagents, verify not
```
hidden: true
```
Ensure config file is in correct location
Validate JSON syntax (if using JSON config)

检查是否设置了
```
disable: false
```
（或未设置该选项）
对于子Agent，确认未设置
```
hidden: true
```
确保配置文件位于正确位置
验证JSON语法（如果使用JSON配置）

Agent can't perform needed actions

Agent无法执行所需操作

Check
```
tools
```
configuration includes needed tools
Verify
```
permission
```
settings allow the operations
For subagents, check parent's
```
permission.task
```
settings
Ensure model has capability for the task

检查
```
tools
```
配置是否包含所需工具
验证
```
permission
```
设置是否允许该操作
对于子Agent，检查父Agent的
```
permission.task
```
设置
确保模型具备执行该任务的能力

Agent asks for approval too often

Agent频繁请求批准

Change permission from
```
ask
```
to
```
allow
```
for safe operations
Use glob patterns to allow specific bash commands
Consider creating a separate agent without restrictions

将安全操作的权限从
```
ask
```
改为
```
allow
```
使用通配符模式允许特定Bash命令
考虑创建一个无限制的独立Agent

Agent makes unwanted changes

Agent进行了不必要的修改

Set
```
permission.edit
```
to
```
ask
```
or
```
deny
```
Disable
```
write
```
tool if not needed
Review custom prompt for overly aggressive instructions

将
```
permission.edit
```
设置为
```
ask
```
或
```
deny
```
如果不需要，禁用
```
write
```
工具
检查自定义提示词是否包含过于激进的指令

Agent not invoking subagents

Agent未调用子Agent

Check subagent's
```
description
```
is clear and keyword-rich
Verify parent's
```
permission.task
```
allows the subagent
Ensure subagent is not
```
hidden: true
```
Consider manual invocation with @ mention

检查子Agent的
```
description
```
是否清晰且包含关键词
验证父Agent的
```
permission.task
```
是否允许调用该子Agent
确保子Agent未设置
```
hidden: true
```
考虑使用@提及手动唤起

Example configurations

示例配置

See assets/templates/ for complete example configurations:

```
read-only-reviewer.md
```
- Code reviewer without write access
```
security-auditor.json
```
- Security-focused agent with limited bash
```
docs-writer.md
```
- Documentation agent with file access only
```
careful-dev.json
```
- Development agent with approval prompts

查看assets/templates/获取完整示例配置：

```
read-only-reviewer.md
```
- 无写入权限的代码审查Agent
```
security-auditor.json
```
- 安全聚焦型Agent，拥有有限Bash权限
```
docs-writer.md
```
- 文档撰写Agent，仅拥有文件访问权限
```
careful-dev.json
```
- 开发Agent，需提示用户批准

Resources

资源

Run

opencode models

to see available models for your configured providers.

运行

opencode models

命令，查看已配置供应商的可用模型。