Skip to main content
Subagents are specialized AI agents that operate with their own custom system prompt, separate context window, and isolated execution environment. They handle specific tasks delegated by the main agent without polluting the main conversation context. Key Characteristics:
  • Isolated Context Windows: Each subagent maintains its own separate context window. Only the final results returned by subagents consume space in the main agent’s context, not the intermediate processing.
  • Custom System Prompts: Every subagent has a dedicated system prompt defining its behavior, personality, and task interpretation approach.
  • Automatic Task Delegation: The main agent automatically invokes subagents when appropriate task types are detected, similar to automatic tool selection.
  • Manual Invocation: Users can explicitly reference subagents using @-mentions (@Verifier, @Explorer, @Code-reviewer).
Two Categories:
  • Default Subagents: Built-in (Verifier, Explorer, Code-reviewer) - immediately available, pre-configured
  • Custom Subagents: User-created, stored in ~/.verdent/subagents/ - tailored to project-specific needs

​
Understanding Default Subagents

Verdent for VS Code includes three built-in default subagents that are pre-configured, immediately available, and require no setup or configuration.
Specialization: Quick code checks and validationCapabilities:
  • Validates code logic
  • Checks syntax correctness
  • Verifies implementation against requirements
Usage: Reference during coding tasks:
@Verifier check this authentication logic
Best For: Rapid validation without full code review overhead

​
Automatic vs Manual Invocation

Automatic Selection Triggers: The main agent automatically selects subagents based on task pattern recognition: Explorer Subagent:
  • Questions about codebase structure (“What is the architecture?”, “Where is X implemented?”)
  • File search requests (“Find all files that…”, “Show me components related to…”)
  • Code navigation queries (“How does authentication work?”, “What calls this function?”)
Code-reviewer Subagent:
  • Security review requests (“Review security vulnerabilities”, “Check for SQL injection risks”)
  • Code quality assessment prompts (“Analyze code quality”, “Identify maintainability issues”)
  • Pre-commit review scenarios (implicitly when code changes are presented)
Verifier Subagent:
  • Validation requests (“Verify this logic”, “Check if this implementation is correct”)
  • Syntax and correctness checks (“Does this code work?”, “Validate the authentication flow”)
Manual Specification: Users can override automatic routing using @-mentions: 
@Explorer find all authentication-related files
@Code-reviewer review the security of login flow
@Verifier check validation logic in middleware
Add Subagent Button: Click the Add Subagent button in the Input Box to:
  • Select from available subagents (default and custom)
  • Explicitly delegate task to chosen subagent
  • Override automatic routing decisions
Benefits of Manual Specification:
  • Precision: Ensure exact subagent handles the task
  • Override: Choose specific subagent when multiple could apply
  • Testing: Validate custom subagent behavior explicitly
  • Consistency: Repeat tasks with same subagent for consistent results
Custom subagents may be auto-invoked based on their defined “When to use” guidelines in the subagent system prompt invocation policy. Details about trigger pattern configuration are currently in development.

​
Creating Custom Subagents

Custom subagents enable you to create specialized agents tailored to your project-specific needs, domain expertise, or team workflows.

​
Creation Methods

Recommended for beginners
  1. Click Settings → Subagents
  2. Select “Create new subagent”
  3. Define subagent name, description, and system prompt
  4. Configure invocation policy and usage guidelines
  5. Save to ~/.verdent/subagents/ directory
This method provides a guided interface for creating subagents with validation and helpful prompts.

​
File Structure

Custom subagent files use Markdown format with YAML frontmatter: 
---
name: subagent-name
description: Brief description of specialization
---
# System Prompt

[Behavior definition, personality, interpretation style]

Invocation policy (strict): Only run if explicitly requested.

When to use:
- Specific scenario 1
- Specific scenario 2

When NOT to use:
- Avoid scenario 1
- Avoid scenario 2
YAML Frontmatter (Required):
  • name: Subagent identifier used in @-mentions
  • description: One-line description of subagent purpose
System Prompt Section: Markdown content defining subagent behavior:
  • Personality and tone
  • Interpretation approach for tasks
  • Output format preferences
  • Decision-making principles
Invocation Policy (Required): 
Invocation policy (strict|flexible): Policy description
  • strict: Only invoke when explicitly requested by user
  • flexible: Allow automatic invocation based on task patterns
Usage Guidelines: 
When to use the [name] agent:
- Bullet list of scenarios for invocation

When NOT to use:
- Bullet list of scenarios to avoid

​
Custom Subagent Examples

---
name: api-documenter
description: Generates comprehensive API documentation from code
---
# System Prompt

You are an API documentation specialist.

Documentation approach:
- Extract endpoints, parameters, and responses from code
- Generate OpenAPI/Swagger specifications
- Include usage examples and error codes
- Document authentication requirements

Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User requests API documentation generation
- Need to document REST/GraphQL endpoints
- Creating developer guides

When NOT to use:
- Inline code comments
- User-facing documentation
Use Case: Automatically generate comprehensive API documentation by analyzing route handlers, controllers, and schema definitions.

​
Common Use Cases for Custom Subagents

Domain-Specific Expertise
  • Financial calculations: Subagent specialized in tax compliance, financial regulations
  • Healthcare HIPAA compliance: Review code for patient data handling standards
  • Cryptography: Analyze security implementations against best practices
Ideal for industries with specialized knowledge requirements and regulatory constraints.

​
Subagent Behavior Configuration (AGENTS.md Pattern)

While AGENTS.md primarily serves as a project rules file (see Rule Systems), it can also define project-specific subagent behavior.

​
System Prompt Design Principles

Be Specific and Directive: Define exact behavior expectations rather than general guidance.
Be specific and directive in system prompts, ‘Profile before optimizing’ is better than ‘Try to optimize when possible’.
Good: 
Analysis approach:
- Profile before optimizing
- Focus on algorithmic improvements
- Provide before/after benchmarks
Avoid: 
Try to optimize code when possible
Establish Personality and Tone: Create distinct “personas” optimized for specific purposes: 
You are a performance optimization specialist.
Define Decision-Making Principles: Guide how the subagent should approach trade-offs: 
When suggesting optimizations:
1. Measure first, optimize second
2. Prioritize readability over micro-optimizations
3. Only suggest changes with >10% performance improvement
Specify Output Format: Control how results are presented: 
Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

​
Invocation Policy Configuration

Strict Policy: 
Invocation policy (strict): Only run when explicitly requested.
Use when:
  • Subagent handles sensitive operations (security reviews, database migrations)
  • User should consciously decide when to invoke
  • Automatic invocation could be disruptive
Flexible Policy: 
Invocation policy (flexible): May auto-invoke based on task patterns.
Use when:
  • Subagent provides helpful context without disruption
  • Automatic invocation enhances workflow efficiency
  • Task patterns are clearly identifiable
Usage Guidelines Best Practices: “When to use” section:
  • Be specific about trigger scenarios
  • Include example prompts that should invoke the subagent
  • Describe task characteristics that match subagent specialization
“When NOT to use” section:
  • Explicitly list exclusions to prevent inappropriate invocation
  • Clarify boundaries with related subagents
  • Prevent scope creep

​
Task Routing and Dispatch

Verdent’s multi-subagent system enables parallel task execution with automatic routing and coordination across specialized agents.

​
Architecture Components

Main Agent (Orchestrator): The primary agent analyzes user requests, breaks down complex tasks, and delegates specialized work to appropriate subagents. It maintains conversation context and coordinates subagent results. Subagent Pool: Collection of available subagents (both default and custom) that can be invoked automatically or manually. Each operates independently with isolated context. Automatic Task Routing: When the main agent detects task patterns matching subagent specializations, it automatically dispatches work:
  • Codebase exploration questions → Explorer subagent
  • Security review requests → Code-reviewer subagent
  • Validation checks → Verifier subagent
Parallel Execution: Multiple subagents can run concurrently for complex operations. Example: Explorer subagent searches codebase while Code-reviewer analyzes security simultaneously, delivering faster results.
Parallel subagent execution accelerates complex tasks, Explorer can search while Code-reviewer analyzes simultaneously.
Result Consolidation: Subagent outputs are returned to the main agent, which synthesizes results and presents unified responses to the user.
Detailed information about subagent execution scheduling, priority, maximum concurrent limits, error handling, and resource allocation is currently in development. Contact support for specific architectural questions.

​
Subagent Monitoring

Track subagent usage and performance through the Chat View where Verdent displays subagent operations and results.

​
Monitoring Methods

Chat View Indicators:
  • Subagent invocations appear in the conversation history
  • Progress indicators show when subagents are executing
  • Results explicitly identify which subagent provided the output
Subagent Outputs Section: Dedicated display for:
  • Results from subagent task execution
  • Progress indicators for parallel tasks
  • Consolidated summaries when tasks complete
Response Attribution: Verdent attributes findings to specific subagents in responses, making it clear which agent performed which analysis or search.

​
Visibility and Transparency

Operation Transparency: Verdent shows:
  • Which subagent was invoked
  • Whether invocation was automatic or manual
  • Task delegation reason
  • Subagent execution status
Manual Specification Verification: When you use @-mentions, Verdent confirms the specified subagent is handling the task, ensuring your routing preferences are respected.
Enhanced monitoring features including detailed execution logs, performance metrics (execution time, token usage), historical invocation tracking, activity visibility settings, and usage analytics dashboards are currently in development.

​
See Also

Rule Systems & Behavior Guidance

Configure Verdent behavior through user rules, project rules, and plan rules

Tool Reference

Complete reference of available tools and capabilities