augmnt.sh
Back to Tips

Working with Claude Code Sub-Agents

Harness the power of specialized sub-agents for domain-specific tasks. Learn to create, configure, and orchestrate agents for security, testing, and architecture.

Understanding Claude Code Sub-Agents

Sub-agents in Claude Code are specialized AI assistants that operate in their own separate context windows, each designed to excel at specific development tasks with deep domain expertise. They provide context preservation, specialized knowledge, and intelligent task delegation.

Key Benefits

  • Context Preservation: Keep your main conversation focused while agents work independently
  • Specialized Expertise: Domain-specific knowledge and best practices
  • Reusability: Use across different projects and share with team members
  • Intelligent Delegation: Claude Code automatically invokes appropriate agents
  • Flexible Permissions: Customizable tool access for security

Creating Sub-Agents

Using the /agents Command

Create sub-agents directly in Claude Code using the /agents command:

  1. Type /agents in Claude Code
  2. Choose to create a new agent
  3. Select project-level or user-level scope
  4. Define name, description, and tools
  5. Write detailed system prompt

Agent File Structure

Sub-agents are stored as Markdown files with YAML frontmatter:

---
name: security-auditor
description: Security vulnerability assessment and compliance validation
tools: [Read, Bash, Grep, Write, Edit, WebSearch]
---

You are a security expert specializing in identifying vulnerabilities 
and ensuring OWASP compliance. You conduct security assessments, 
implement security controls, and protect sensitive data.

Focus on:
- Identifying security vulnerabilities
- OWASP compliance validation  
- Security architecture evaluation
- Vulnerability assessments

Always provide specific, actionable security recommendations.

Tool Access Configuration

Configure specific tools for each agent:

  • Read/Write Tools: File operations (Read, Write, Edit, MultiEdit)
  • Search Tools: Code analysis (Grep, Glob)
  • Execution Tools: Command execution (Bash)
  • Web Tools: External research (WebSearch, WebFetch)
  • MCP Tools: Model Context Protocol integrations

Working with Sub-Agents

Automatic Delegation

Claude Code automatically invokes appropriate agents based on your requests:

# Automatic agent selection
"Please review this code for security issues"
→ Automatically delegates to security-auditor

"Create comprehensive tests for this API"  
→ Routes to unit-test-generator and integration-test-builder

"Optimize this database query"
→ Invokes performance-profiler

Explicit Agent Invocation

You can also explicitly call specific agents:

# Direct agent invocation
"Use security-auditor to review this authentication code"

"Ask frontend-specialist to create a responsive navbar"

"Have code-reviewer check this implementation"

Agent Chaining

Claude Code can chain multiple agents for complex workflows:

# Complex workflow example
"Build a user authentication system"

→ project-orchestrator: Plans the feature
→ backend-architect: Designs API and database  
→ security-auditor: Reviews security requirements
→ unit-test-generator: Creates test suite
→ code-reviewer: Final quality check

Agent Storage and Scope

Project-Level Agents

Store agents in your project for team sharing:

# Project agents location
.claude/agents/
├── backend-architect.md
├── frontend-specialist.md  
├── security-auditor.md
└── performance-profiler.md

# Version control with your project
git add .claude/agents/
git commit -m "Add project sub-agents"

User-Level Agents

Global agents available across all projects:

# User agents location (macOS/Linux)
~/.claude/agents/
├── code-reviewer.md
├── unit-test-generator.md
└── documentation-expert.md

# Available in any Claude Code session

Agent Collections

Use pre-built agent collections like augmnt/agents:

# Install agent collection
git clone https://github.com/augmnt/agents.git
cp agents/*.md ~/.claude/agents/

# Or for project-specific
cp agents/*.md ./.claude/agents/

Best Practices

Agent Design Principles

  • Single Responsibility: Each agent should have one focused purpose
  • Clear Descriptions: Write specific descriptions for accurate delegation
  • Minimal Tool Access: Only grant tools necessary for the agent's role
  • Detailed Prompts: Include specific instructions and best practices

Tool Configuration Guidelines

# Security-focused agent - minimal tools
tools: [Read, Grep, WebSearch]

# Implementation agent - full toolkit  
tools: [Read, Write, Edit, MultiEdit, Bash, Grep, Glob]

# Analysis-only agent - read access
tools: [Read, Grep, Glob, WebFetch]

Version Control Integration

# Include agents in your repository
.claude/
├── agents/
│   ├── backend-architect.md
│   ├── security-auditor.md
│   └── test-generator.md
└── CLAUDE.md

# Team benefits from shared agents
git add .claude/agents/
git commit -m "Add project-specific sub-agents"

Performance Considerations

Context Management

  • Sub-agents start with clean context each time
  • This provides isolation but may add slight latency
  • Claude Code optimizes with caching and intelligent context sharing
  • Agents can run in parallel for complex workflows

Agent Selection Heuristics

Claude Code uses sophisticated methods to choose agents:

  • Request Analysis: Content and intent analysis
  • Tool Requirements: Matching needed capabilities
  • Agent Capabilities: Expertise domain matching
  • Workflow Patterns: Common task sequences

Common Considerations

Human Oversight

Maintain human judgment for:

  • Business logic and requirements interpretation
  • User experience and design decisions
  • Strategic architectural choices
  • Final security and quality validation

Agent Limitations

Sub-agents work best when:

  • Given clear, specific tasks
  • Working within their expertise domain
  • Provided with adequate context
  • Validated against project requirements

Getting Started

Quick Start with Agent Collections

  1. Install the augmnt/agents collection
  2. Start with simple requests like "review this code"
  3. Observe which agents Claude Code automatically selects
  4. Experiment with explicit agent invocation

Creating Your First Agent

  1. Type /agents in Claude Code
  2. Choose "Create new agent"
  3. Start with a focused role (e.g., "API documentation generator")
  4. Test with your specific codebase
  5. Iterate based on results

Building Agent Workflows

  1. Identify repetitive development tasks
  2. Create specialized agents for each task
  3. Let Claude Code handle orchestration automatically
  4. Version control project-specific agents

The Future of Claude Code Sub-Agents

The sub-agent ecosystem continues evolving with:

  • Enhanced Orchestration: Improved coordination and workflow automation
  • Domain-Specific Agents: Specialized agents for industries and frameworks
  • Learning Capabilities: Agents adapting to team patterns and preferences
  • Integration Ecosystem: Better tool and platform integrations

Conclusion

Claude Code sub-agents represent a paradigm shift from general-purpose AI to specialized, domain-expert collaboration. By leveraging focused agents with deep expertise, you can achieve higher quality results, faster development cycles, and continuous learning.

Start with the augmnt/agents collection, experiment with different agents for your workflow, and experience the transformative power of specialized AI assistance in your development process.