Subagents

Overview

Subagents are specialized AI agents that Friday can launch to handle complex, multi-step tasks autonomously. Each subagent runs in its own isolated context with a focused set of tools and expertise, allowing Friday to delegate specific work like web searches, code exploration, or code reviews. Subagents work behind the scenes to gather information and complete tasks, then return their results to Friday for further processing. Friday's subagents are compatible with Claude Code's sub-agents ecosystem.

Quick Start

Subagents are invoked automatically by Friday when needed, but you can also create custom subagents for specialized tasks.

Using Built-in Subagents

Friday automatically uses subagents when appropriate. For example:

  • Ask Friday to search for current information: "What are the latest features in React 19?"
  • Request code exploration: "Find all the authentication-related code in this project"
  • Ask for a code review: "Review my changes for security issues"

Friday will automatically launch the appropriate subagent (web-search, file-search, or code-review) to handle your request.

Creating a Custom Subagent

Use the /create-agent command to create your own specialized subagent:

  1. Type /create-agent in Friday
  2. Friday will guide you through the creation process
  3. Restart your Friday session to make the new subagent available

Usage

Built-in Subagents

Friday includes three built-in subagents that are automatically available:

web-search

Searches the web for current information beyond Friday's knowledge cutoff.

Configuration:

  • Model: haiku
  • Tools: WebSearch

Use cases:

  • Finding latest documentation and API references
  • Looking up current best practices and standards
  • Researching error messages and solutions
  • Verifying facts and gathering current information

file-search

Explores your codebase to find relevant code and gather information about your project structure.

Configuration:

  • Model: haiku
  • Tools: Glob, Grep, Read

Use cases:

  • Finding specific functions or classes
  • Exploring code organization and architecture
  • Locating files by name or pattern
  • Searching for code patterns across the project

code-review

Performs comprehensive code reviews with customizable focus areas.

Configuration:

  • Model: sonnet
  • Tools: Bash, Glob, Grep, Read

Use cases:

  • Reviewing all changes on a branch
  • Analyzing staged changes before committing
  • Reviewing specific files for quality issues
  • Checking for security vulnerabilities, performance issues, or test coverage

Custom Subagents

Create custom subagents to handle specialized tasks specific to your workflow or domain.

Agent File Structure

Subagents are defined in Markdown files with YAML frontmatter:

---
name: agent-name
description: Brief description of what this agent does
model: sonnet
tools: Read, Write, Bash, Glob, Grep
---

Your system prompt goes here. This defines the agent's behavior,
expertise, and how it should approach tasks.

Be specific about what the agent should do and how it should
communicate its findings.

Frontmatter Fields

Required Fields:

  • name (string, required) - Unique identifier for the agent

    • Format: single word or kebab-case (e.g., web-search, db-analyzer)
    • Max length: 64 characters

  • description (string, required) - Brief description of the agent's purpose

Optional Fields:

  • model (string, optional) - Specifies which model the agent uses

    • Accepted values:
      • haiku → claude-haiku-4-5-20251001
      • sonnet → claude-sonnet-4-6
    • Default: sonnet (if not specified)
    • Recommendation: Use haiku for simple tasks, sonnet for complex reasoning

  • tools (string, optional) - Comma-separated list of tools available to the agent

    • Available tools:
      • Read - Read files and directories
      • Write - Create new files
      • Edit - Edit existing files
      • Bash - Execute bash commands
      • Glob - File discovery and globbing operations
      • Grep - Search for text patterns in files
      • Plan - Generate plans for complex tasks
      • WebSearch - Search the web
      • WebFetch - Fetch content from public web URLs
    • Default: All tools (if not specified)
    • Best practice: Only include tools the agent actually needs to reduce token usage and improve focus

  • skills (string, optional) - Comma-separated list of skill names to load for this agent

    • Skills must exist in user (~/.claude/skills/), project (.claude/skills/), or plugin skill directories
    • Default: No skills loaded (if not specified)

  • mcp (string, optional) - Comma-separated list of MCP server IDs to load for this agent

    • Example: mcp: linear or mcp: linear, github
    • Loads only the specified MCP servers and their associated tools
    • Default: No MCP tools loaded (if not specified)

Agent Locations

Subagents can be stored in multiple locations:

User Agents (~/.claude/agents/)

Personal agents available across all your projects. Use this for:

  • General-purpose agents you use frequently
  • Personal workflow automation
  • Reusable specialized agents

Project Agents (.claude/agents/)

Project-specific agents that can be committed to version control and shared with your team. Use this for:

  • Domain-specific agents for the project
  • Team workflow automation
  • Project-specific analysis tools

Plugin Agents

Agents provided by enabled plugins. These are automatically loaded when you enable a plugin and provide specialized capabilities for specific integrations.

Examples

Example 1: Database Schema Analyzer

Create an agent that analyzes database schemas and migrations:

# ~/.claude/agents/db-analyzer/AGENT.md

---

name: db-analyzer
description: Analyze database schemas and migration files
model: sonnet
tools: Read, Glob, Grep

---

You are a database schema expert. When given a task, analyze database
schemas, migration files, and related code to provide insights about:

- Schema structure and relationships
- Migration history and patterns
- Potential issues or inconsistencies
- Optimization opportunities

Focus on clarity and actionable recommendations.

Example 2: Dependency Auditor

Create an agent that audits project dependencies:

# ~/.claude/agents/dep-audit/AGENT.md

---

name: dep-audit
description: Audit project dependencies for issues
model: haiku
tools: Bash, Read, Glob

---

You are a dependency auditor. When analyzing a project:

1. Check for outdated dependencies
2. Identify security vulnerabilities
3. Look for unused dependencies
4. Check for version conflicts
5. Suggest updates or alternatives

Use package manager commands to gather information and provide
a clear summary of findings with recommended actions.

Example 3: Test Coverage Analyzer

Create an agent that analyzes test coverage:

# .claude/agents/test-coverage/AGENT.md

---

name: test-coverage
description: Analyze test coverage and identify gaps
model: haiku
tools: Bash, Glob, Grep, Read

---

You are a test coverage specialist. When analyzing a codebase:

1. Identify all source files and their corresponding test files
2. Analyze test coverage metrics if available
3. Find untested or under-tested code
4. Identify critical paths without tests
5. Suggest specific tests to add

Provide actionable recommendations prioritized by importance.

Example 4: Agent with Skills

Create an agent that uses specific skills for enhanced context:

# .claude/agents/api-reviewer/AGENT.md

---

name: api-reviewer
description: Review API implementations with team standards
model: sonnet
tools: Read, Glob, Grep
skills: api-design, security-checklist

---

You are an API review specialist. Review API implementations according
to the loaded skills and provide specific, actionable feedback.

Example 5: Agent with MCP Tools

Create an agent that uses MCP tools for external integrations:

# .claude/agents/ticket-analyzer/AGENT.md

---

name: ticket-analyzer
description: Analyze code changes and update project management tickets
model: sonnet
tools: Read, Bash, Glob, Grep
mcp: linear

---

You are a ticket management specialist. Analyze code changes and use
Linear MCP tools to update project management tickets with progress
and findings.