Agents

Specialized agents for complex, multi-step tasks.

---

What Are Agents?

Agents are autonomous Claude instances that handle specific complex tasks. Unlike skills (which provide inline guidance), agents:

• Run as separate sub-tasks
• Work autonomously with minimal supervision
• Have specialized tool access
• Return comprehensive reports when complete

Key advantage: Agents are standalone - just copy the .md file and use immediately!

---

Available Agents (10)

code-architecture-reviewer

Purpose: Review code for architectural consistency and best practices

When to use:

• After implementing a new feature
• Before merging significant changes
• When refactoring code
• To validate architectural decisions

Integration: ✅ Copy as-is

---

code-refactor-master

Purpose: Plan and execute comprehensive refactoring

When to use:

• Reorganizing file structures
• Breaking down large components
• Updating import paths after moves
• Improving code maintainability

Integration: ✅ Copy as-is

---

documentation-architect

Purpose: Create comprehensive documentation

When to use:

• Documenting new features
• Creating API documentation
• Writing developer guides
• Generating architectural overviews

Integration: ✅ Copy as-is

---

frontend-error-fixer

Purpose: Debug and fix frontend errors

When to use:

• Browser console errors
• TypeScript compilation errors in frontend
• React errors
• Build failures

Integration: ⚠️ May reference screenshot paths - update if needed

---

plan-reviewer

Purpose: Review development plans before implementation

When to use:

• Before starting complex features
• Validating architectural plans
• Identifying potential issues early
• Getting second opinion on approach

Integration: ✅ Copy as-is

---

refactor-planner

Purpose: Create comprehensive refactoring strategies

When to use:

• Planning code reorganization
• Modernizing legacy code
• Breaking down large files
• Improving code structure

Integration: ✅ Copy as-is

---

web-research-specialist

Purpose: Research technical issues online

When to use:

• Debugging obscure errors
• Finding solutions to problems
• Researching best practices
• Comparing implementation approaches

Integration: ✅ Copy as-is

---

auth-route-tester

Purpose: Test authenticated API endpoints

When to use:

• Testing routes with JWT cookie auth
• Validating endpoint functionality
• Debugging authentication issues

Integration: ⚠️ Requires JWT cookie-based auth

---

auth-route-debugger

Purpose: Debug authentication issues

When to use:

• Auth failures
• Token issues
• Cookie problems
• Permission errors

Integration: ⚠️ Requires JWT cookie-based auth

---

auto-error-resolver

Purpose: Automatically fix TypeScript compilation errors

When to use:

• Build failures with TypeScript errors
• After refactoring that breaks types
• Systematic error resolution needed

Integration: ⚠️ May need path updates

---

How to Integrate an Agent

Standard Integration (Most Agents)

Step 1: Copy the file

cp showcase/.claude/agents/agent-name.md \\\\
   your-project/.claude/agents/

Step 2: Verify (optional)

# Check for hardcoded paths
grep -n "~/git/\\|/root/git/\\|/Users/" your-project/.claude/agents/agent-name.md

Step 3: Use it Ask Claude: "Use the [agent-name] agent to [task]"

That's it! Agents work immediately.

---

Agents Requiring Customization

frontend-error-fixer:

• May reference screenshot paths
• Ask user: "Where should screenshots be saved?"
• Update paths in agent file

auth-route-tester / auth-route-debugger:

• Require JWT cookie authentication
• Update service URLs from examples
• Customize for user's auth setup

auto-error-resolver:

• May have hardcoded project paths
• Update to use $CLAUDE_PROJECT_DIR or relative paths

---

When to Use Agents vs Skills

Both can work together:

• Skill provides patterns during development
• Agent reviews the result when complete

---

Agent Quick Reference

---

For Claude Code

When integrating agents for a user:

1. Read CLAUDE_INTEGRATION_GUIDE.md
2. Just copy the .md file - agents are standalone
3. Check for hardcoded paths:

   grep "~/git/\\|/root/" agent-name.md
   

4. Update paths if found to $CLAUDE_PROJECT_DIR or .
5. For auth agents: Ask if they use JWT cookie auth first

That's it! Agents are the easiest components to integrate.

---

Creating Your Own Agents

Agents are markdown files with optional YAML frontmatter:

# Agent Name

## Purpose
What this agent does

## Instructions
Step-by-step instructions for autonomous execution

## Tools Available
List of tools this agent can use

## Expected Output
What format to return results in

Tips:

• Be very specific in instructions
• Break complex tasks into numbered steps
• Specify exactly what to return
• Include examples of good output
• List available tools explicitly

---

Troubleshooting

Agent not found

Check:

# Is agent file present?
ls -la .claude/agents/[agent-name].md

Agent fails with path errors

Check for hardcoded paths:

grep "~/\\|/root/\\|/Users/" .claude/agents/[agent-name].md

Fix:

sed -i 's|~/git/.*project|$CLAUDE_PROJECT_DIR|g' .claude/agents/[agent-name].md

---

Next Steps

1. Browse agents above - Find ones useful for your work
2. Copy what you need - Just the .md file
3. Ask Claude to use them - "Use [agent] to [task]"
4. Create your own - Follow the pattern for your specific needs

Questions? See CLAUDE_INTEGRATION_GUIDE.md