Subagents Local Catalog Tool

Manage and access subagents from the local filesystem. Scans $HOME/.config/opencode/agents/ for agent definitions and provides browsing, searching, and fetching capabilities.

The Job

1. •Receive user request for subagent operations (list, search, fetch)
2. •Scan local filesystem for agent definitions
3. •Parse YAML frontmatter and extract metadata
4. •Filter and format results as requested
5. •Return formatted results to the user

Important: All operations use local filesystem access - no network requests required.

Step 1: Parse User Request

Identify the operation type:

• •list: Show all categories and their subagents
• •search <query>: Find subagents matching keywords in name or description
• •fetch <name>: Get the full markdown content for a specific subagent

Step 2: Scan Local Agent Directory

1. •Check for agents directory: Use glob with absolute path: glob with path="$HOME/.config/opencode/agents" and pattern="*.md"
2. •Handle missing directory: If no agents found, provide helpful setup instructions
3. •Parse agent files: For each .md file found, use read to extract:
   • •YAML frontmatter (name, description, tools, category)
   • •Filename for categorization (backend-, frontend-, devops- prefixes)

Frontmatter Extraction Pattern

Use read to get file contents, then parse YAML between --- markers:

---
name: backend-developer
description: Senior backend engineer for scalable APIs
tools: postgresql_execute_query, jira_search_issues
---

Categorization Logic

Extract category from filename prefixes:

• •backend-* → Backend Development
• •frontend-* → Frontend Development
• •devops-* → DevOps & Infrastructure
• •qa-* → Quality & Testing
• •security-* → Security
• •data-* → Data & Analytics
• •ui-* → UI/UX Design
• •mobile-* → Mobile Development
• •cloud-* → Cloud & Platform
• •docs-* → Documentation
• •Other → General

Step 3: Process Request

For List Operation

1. •Collect all agent files using glob
2. •Group by category using filename prefix logic
3. •Format organized list by categories:

## Backend Development
- backend-developer: Senior backend engineer for scalable APIs
- database-architect: Database design and optimization expert

## Frontend Development  
- frontend-developer: React/Vue/Angular specialist
- ui-designer: User interface and experience designer
...

For Search Operation

1. •Use grep to search agent files for keywords in:
   • •Names (filename and frontmatter name field)
   • •Descriptions (frontmatter description field)
   • •Tools (frontmatter tools field)
2. •Return matches with category context:

Found 3 matching subagents:

## Security-Related Subagents
- security-engineer (Infrastructure): Security specialist for cloud infrastructure
- security-auditor (Quality): Security vulnerability assessment expert
- backend-security (Backend): API security and authentication specialist

For Fetch Operation

1. •Find exact match for requested name using glob pattern *{name}*.md
2. •Use read to return full file content including frontmatter and body
3. •If not found, suggest similar names using partial matches

Output Format

• •Use markdown formatting for readability
• •Include category names for organization
• •Show brief descriptions in lists
• •Return full content for fetches
• •Include tool lists for context

Error Handling

No Agents Directory Found

❌ No subagents found in $HOME/.config/opencode/agents/

To set up subagents:
1. Create the directory: mkdir -p $HOME/.config/opencode/agents
2. Add agent definition files as .md files with YAML frontmatter
3. Example agent file:
   ---
   name: backend-developer
   description: Senior backend engineer for scalable APIs
   tools: postgresql_execute_query, jira_search_issues
   ---
   
   # Backend Developer
   
   Expert in building scalable backend systems...

No Search Results

❌ No subagents found matching "keyword"

💡 Try these alternatives:
- Search for different keywords
- Use `/subagents list` to see all available agents
- Check for typos in your search query

Agent Not Found for Fetch

❌ Subagent "agent-name" not found

💡 Did you mean:
- similar-agent-name (Backend Development)
- agent-name-alt (Infrastructure)

Use `/subagents list` to see all available agents.

Examples

List all subagents:

## Backend Development
- backend-developer: Senior backend engineer for scalable APIs
  Tools: postgresql_execute_query, jira_search_issues
- database-architect: Database design and optimization expert
  Tools: postgresql_execute_query

## Frontend Development  
- frontend-developer: React/Vue/Angular specialist
  Tools: chrome_click, chrome_fill, playwright_browser_evaluate

Search for "security":

Found 3 matching subagents:

## Security-Related Subagents
- security-engineer (Infrastructure): Security specialist for cloud infrastructure
  File: security-engineer.md
  Tools: jira_search_issues, bash
  
- security-auditor (Quality): Security vulnerability assessment expert  
  File: qa-security-auditor.md
  Tools: jira_search_issues, grep

Fetch backend-developer:

# Backend Developer

---
name: backend-developer
description: Senior backend engineer for scalable APIs
tools: postgresql_execute_query, jira_search_issues
category: backend
---

## Overview

Expert in building scalable backend systems with focus on API design, database architecture, and performance optimization.

## Capabilities

- Database design and optimization
- API development and documentation
- Performance troubleshooting
- Security best practices
- System architecture design

## Tools Available

- PostgreSQL database operations
- Jira issue tracking and management
- Code review and analysis
- Deployment automation

## Usage

Perfect for tasks involving backend development, database work, and API design.

File Structure Requirements

Agents should be stored as .md files in $HOME/.config/opencode/agents/ with:

1. •

   YAML Frontmatter with required fields:

   • •name: Human-readable agent name
   • •description: Brief description of capabilities
   • •tools: Comma-separated list of available tools
   • •category (optional): Override auto-categorization
2. •

   Filename following naming convention:

   • •Use hyphens for spaces: backend-developer.md
   • •Include category prefix for auto-categorization: backend-, frontend-, etc.
3. •

   Markdown Body with sections like:

   • •Overview
   • •Capabilities
   • •Usage examples
   • •Tool documentation