AGENTS/skill/agent-development/references/triggering-examples.md

Agent Triggering in Opencode

Understanding how agents are triggered and invoked in Opencode.

Triggering Mechanisms

Primary Agents

Primary agents are directly accessible to users:

Method	Description
Tab key	Cycle through primary agents
Keybind	Use configured switch_agent keybind
@ mention	Type @agent-name in message
default_agent	Set in config to start with specific agent

Subagents

Subagents are invoked indirectly:

Method	Description
Task tool	Primary agent delegates via Task tool
@ mention	User manually types @agent-name
Automatic	Based on description matching user intent

The Description Field

The description field is critical for subagent triggering. When a primary agent receives a request, it evaluates subagent descriptions to decide whether to delegate.

Good Descriptions

Clear purpose and triggers:

"description": "Reviews code for quality, security, and best practices. Use when reviewing PRs, after implementing features, or before commits."

Specific use cases:

"description": "Generates comprehensive unit tests for code. Use after implementing new functions or when improving test coverage."

Domain-specific:

"description": "Analyzes authentication and authorization code for security vulnerabilities. Use when reviewing auth flows, JWT handling, or session management."

Poor Descriptions

Too vague:

"description": "Helps with code"

No trigger conditions:

"description": "A code review agent"

Too broad:

"description": "Handles all development tasks"

Triggering Patterns

Pattern 1: Explicit Delegation

Primary agent explicitly invokes subagent via Task tool:

User: "Review my authentication code"

Primary Agent (internal): This matches "code-reviewer" description about 
"reviewing auth flows". Invoke via Task tool.

→ Task tool invokes code-reviewer subagent

Pattern 2: @ Mention

User directly invokes subagent:

User: "@security-analyzer check this endpoint for vulnerabilities"

→ security-analyzer subagent is invoked directly

Pattern 3: Automatic Context

Primary agent recognizes pattern from description:

User: "I just implemented the payment processing feature"

Primary Agent: Description mentions "after implementing features" and 
"security-critical code (auth, payments)". Consider delegating to 
security-analyzer or code-reviewer.

Task Tool Invocation

When a primary agent invokes a subagent, it uses the Task tool:

{
  "tool": "task",
  "parameters": {
    "subagent_type": "code-reviewer",
    "prompt": "Review the authentication code in src/auth/...",
    "description": "Code review for auth implementation"
  }
}

Task Permissions

Control which subagents an agent can invoke:

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

• "allow": Invoke without approval
• "ask": Prompt user for approval
• "deny": Remove from Task tool (agent can't see it)

Note: Users can still @ mention any subagent, regardless of task permissions.

Hidden Subagents

Hide subagents from @ autocomplete while still allowing Task tool invocation:

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

Use cases:

• Internal processing agents
• Agents only invoked programmatically
• Specialized helpers not meant for direct user access

Navigation Between Sessions

When subagents create child sessions:

Keybind	Action
<Leader>+Right	Cycle forward: parent → child1 → child2 → parent
<Leader>+Left	Cycle backward

This allows seamless switching between main conversation and subagent work.

Description Best Practices

Include Trigger Conditions

"description": "Use when [condition 1], [condition 2], or [condition 3]."

Be Specific About Domain

"description": "Analyzes [specific domain] for [specific purpose]."

Mention Key Actions

"description": "[What it does]. Invoke after [action] or when [situation]."

Complete Example

{
  "code-reviewer": {
    "description": "Reviews code for quality issues, security vulnerabilities, and best practice violations. Use when: (1) reviewing pull requests, (2) after implementing new features, (3) before committing changes, (4) when asked to check code quality. Provides structured feedback with file:line references.",
    "mode": "subagent"
  }
}

Debugging Triggering Issues

Agent Not Triggering

Check:

1. Description contains relevant keywords
2. Mode is set correctly (subagent for Task tool)
3. Agent is not disabled
4. Task permissions allow invocation

Agent Triggers Too Often

Check:

1. Description is too broad
2. Overlaps with other agent descriptions
3. Consider more specific trigger conditions

Wrong Agent Triggers

Check:

1. Descriptions are distinct between agents
2. Add negative conditions ("NOT for...")
3. Specify exact scenarios in description