gh-resolve-io-prism/skills/agent-builder/reference/troubleshooting.md

Agent Troubleshooting Guide

Common issues and solutions when working with Claude Code sub-agents.

Issue: Agent Never Triggers

Symptoms

• Agent doesn't activate when expected
• Claude doesn't recognize when to use agent
• Manual invocation works, automatic doesn't

Diagnosis

1. Check description specificity:

   # Read your agent file
   head -20 .claude/agents/my-agent.md
   

   Look for:

   • Is description too generic?
   • Missing trigger keywords?
   • No action-oriented language?

2. Test with explicit invocation:

   "Use the my-agent agent to [task]"
   

   If this works, problem is in description/triggers.

Solutions

Solution 1: Add Specific Triggers

❌ Before:

description: Helps with code tasks

✅ After:

description: Use PROACTIVELY after writing Rails controllers to review for RESTful patterns, security issues, and performance problems

Solution 2: Use Trigger Keywords

Add words like:

• PROACTIVELY
• MUST BE USED
• Specific technologies: "Rails", "SQL", "Docker"
• Specific actions: "review", "analyze", "debug"
• Specific contexts: "after writing", "when encountering", "before deploying"

Solution 3: Add Conditional Language

description: Use when SQL queries are slow or EXPLAIN shows missing indexes. Do not use for application code optimization.

Verification

Test automatic triggering:

# Don't name the agent, describe the task
"I just wrote a new Rails controller action. Can you review it?"

If agent triggers, issue is resolved.

---

Issue: Agent Triggers Too Often

Symptoms

• Agent activates for irrelevant tasks
• Wrong agent chosen for task
• Agent interferes with main conversation

Diagnosis

Description is too broad or missing constraints.

Solutions

Solution 1: Narrow Scope

❌ Before:

description: Use for code review

✅ After:

description: Use for Rails code review ONLY. Do not use for JavaScript, Python, or other languages.

Solution 2: Add Exclusions

description: Use when debugging test failures in RSpec. Do not use for Jest, pytest, or other test frameworks.

Solution 3: Make Prerequisites Explicit

description: Use when performance profiling shows database bottlenecks (slow queries, N+1 problems). Requires existing performance data.

Verification

Test with edge cases:

• Tasks that should NOT trigger agent
• Similar but different domains
• Related but out-of-scope work

---

Issue: Agent Has Wrong Permissions

Symptoms

• "Tool not available" errors
• Agent can't complete task
• Agent attempts actions but fails

Diagnosis

1. Check tool configuration:

   tools: Read, Grep, Glob
   

2. Identify what agent tried to do:

   • Tried to edit files? (needs Edit)
   • Tried to run commands? (needs Bash)
   • Tried to create files? (needs Write)

Solutions

Solution 1: Grant Required Tools

For code review (read-only):

tools: Read, Grep, Glob

For debugging (read + execute):

tools: Read, Bash, Grep, Glob

For code fixing (read + modify + execute):

tools: Read, Edit, Bash, Grep, Glob

For creating new files:

tools: Read, Write, Edit, Bash, Grep, Glob

Solution 2: Grant All Tools

If agent needs flexibility, omit tools field:

---
name: my-agent
description: Agent description
# No tools field = inherits all tools
---

Solution 3: Split Agent

If one agent needs different permissions for different tasks:

Create two agents:

• code-analyzer (read-only)
• code-fixer (read + edit)

Verification

Test all expected actions:

• Agent can read files
• Agent can search (if needed)
• Agent can edit (if needed)
• Agent can run commands (if needed)

---

Issue: Agent Produces Wrong Output

Symptoms

• Output format inconsistent
• Missing required information
• Wrong analysis or suggestions
• Output style doesn't match expectations

Diagnosis

System prompt lacks specificity or examples.

Solutions

Solution 1: Define Explicit Output Format

Add to system prompt:

## Output Format

Use this exact structure:

# Analysis Result

## Summary
[One sentence]

## Details
- Point 1
- Point 2

## Recommendation
[Specific action]

Solution 2: Add Examples

## Example Output

**Input**: SQL query with missing index
**Output**:

Query Optimization

Issue

Query scans full table (1M rows)

Root Cause

Missing index on user_id column

Recommendation

CREATE INDEX idx_orders_user_id ON orders(user_id);

Expected Impact

Query time: 2.5s → 50ms (98% faster)

Solution 3: Add Constraints

## Constraints

- ALWAYS include specific file paths and line numbers
- NEVER suggest vague improvements like "optimize this"
- DO NOT provide multiple options - pick the best one
- MUST include before/after examples

Solution 4: Improve Instructions

Break down the process:

## Analysis Process

1. Read the error message carefully
2. Identify the exact line that failed
3. Read 10 lines before and after for context
4. Check git blame for recent changes
5. Formulate hypothesis about root cause
6. Propose minimal fix with explanation

Verification

Test with multiple inputs:

• Output follows format consistently
• All required sections present
• Quality meets expectations
• Style is appropriate

---

Issue: Agent Not Found

Symptoms

• "Agent not found" error
• Agent file exists but isn't recognized
• Manual attempts to invoke fail

Diagnosis

1. Check file location:

   # Project agents
   ls -la .claude/agents/
   
   # User agents
   ls -la ~/.claude/agents/
   

2. Check file naming:

   • Must end in .md
   • Name should match YAML name field
   • Lowercase with hyphens

Solutions

Solution 1: Correct File Location

Move to correct directory:

# For project agent
mv my-agent.md .claude/agents/my-agent.md

# For user agent
mv my-agent.md ~/.claude/agents/my-agent.md

Solution 2: Fix File Name

Ensure consistency:

# In my-agent.md
---
name: my-agent  # Must match filename (without .md)
---

Solution 3: Create Directory

If directory doesn't exist:

# Project agents
mkdir -p .claude/agents

# User agents
mkdir -p ~/.claude/agents

Solution 4: Check YAML Syntax

Validate frontmatter:

---
name: agent-name
description: Description here
tools: Read, Edit
model: sonnet
---

Common YAML errors:

• Missing opening ---
• Missing closing ---
• Incorrect indentation
• Missing quotes around special characters

Verification

# List all agents Claude can see
/agents

# Try explicit invocation
"Use the my-agent agent to test"

---

Issue: Agent Runs But Produces No Output

Symptoms

• Agent starts successfully
• No errors reported
• But no useful output or response

Diagnosis

Agent completed but didn't communicate results.

Solutions

Solution 1: Add Output Instructions

## Final Output

After completing analysis, ALWAYS provide a summary using this format:
[format specification]

Do not end without providing output.

Solution 2: Check for Silent Failures

Add error handling instructions:

## Error Handling

If you encounter errors:
1. Clearly state what failed
2. Explain why it failed
3. Suggest workaround or next steps

Never fail silently.

Solution 3: Require Summary

## Completion Requirement

You must always end with:

# Summary
- [What was done]
- [What was found]
- [What to do next]

Verification

Test edge cases:

• Agent with no findings
• Agent that encounters errors
• Agent with partial results

All should produce output.

---

Issue: Agent Takes Too Long

Symptoms

• Agent runs but is very slow
• Times out or seems stuck
• Uses many tokens

Diagnosis

Agent may be:

• Reading too many files
• Running expensive operations
• Lacking clear stopping criteria

Solutions

Solution 1: Add Scope Limits

## Scope

Analyze only:
- Files in `app/` directory
- Maximum 10 files
- Skip `node_modules/`, `vendor/`

Solution 2: Prioritize Efficiently

## Process

1. Check git diff for changed files (start here)
2. Read only files with relevant patterns
3. Stop after finding 5 issues
4. Report findings incrementally

Solution 3: Use Faster Model

model: haiku  # Faster for simple tasks

Solution 4: Break Into Smaller Agents

Instead of one "complete-analyzer":

• quick-scanner (initial pass)
• deep-analyzer (detailed review)
• fix-applier (apply changes)

Verification

Measure performance:

• Time to completion
• Token usage
• Files accessed

Optimize as needed.

---

Issue: Agent Conflicts With Main Conversation

Symptoms

• Main Claude and agent give conflicting advice
• Confusion about which entity is responding
• Agent overrides main conversation decisions

Diagnosis

Agent is too broadly scoped or triggers too easily.

Solutions

Solution 1: Narrow Agent Scope

Make agent highly specific:

description: Use ONLY for Rails model validations. Do not use for controllers, views, or other components.

Solution 2: Add Deference Rule

## Priority

If main conversation has already addressed this:
- Acknowledge their approach
- Only add value if you have specific domain expertise
- Don't repeat what's already been said

Solution 3: Use Manual Invocation

Remove automatic trigger words:

# Before (automatic)
description: Use PROACTIVELY for code review

# After (manual only)
description: Review code for style and security issues when explicitly invoked

Verification

• Agent only responds when appropriate
• No conflicts with main Claude
• Agent adds value, doesn't duplicate

---

Issue: YAML Parsing Errors

Symptoms

• "Invalid YAML" error
• Agent file not loaded
• Frontmatter not recognized

Common YAML Mistakes

Mistake 1: Missing Delimiters

❌ Wrong:

name: my-agent
description: Agent description

# System Prompt

✅ Correct:

---
name: my-agent
description: Agent description
---

# System Prompt

Mistake 2: Unquoted Special Characters

❌ Wrong:

description: Use for code: review & testing

✅ Correct:

description: "Use for code: review & testing"

Mistake 3: Multiline Without Pipe

❌ Wrong:

description: This is a very long description
that spans multiple lines

✅ Correct:

description: |
  This is a very long description
  that spans multiple lines

Or:

description: "This is a very long description that spans multiple lines"

Mistake 4: Incorrect Indentation

❌ Wrong:

name: my-agent
 description: Agent description  # Extra space

✅ Correct:

name: my-agent
description: Agent description

Validation

Use YAML validator:

# Install yq if needed
brew install yq

# Validate YAML
yq eval '.claude/agents/my-agent.md'

# Or use online validator
# https://www.yamllint.com/

---

Issue: Agent Works Locally But Not for Team

Symptoms

• Agent works for you
• Teammates report agent not found
• Inconsistent behavior across machines

Diagnosis

Agent in wrong location or not committed.

Solutions

Solution 1: Move to Project Location

# Move from user agents to project agents
mv ~/.claude/agents/my-agent.md .claude/agents/my-agent.md

# Commit to version control
git add .claude/agents/my-agent.md
git commit -m "Add my-agent for team use"
git push

Solution 2: Document in README

## Available Agents

### my-agent
Use for: [description]
Invoke with: "Use my-agent to [task]"

Solution 3: Share User Agent Template

If keeping as user agent:

1. Create template in docs/
2. Team members copy to ~/.claude/agents/
3. Customize as needed

Verification

Have teammate:

1. Pull latest code
2. Check .claude/agents/ exists
3. Try invoking agent

---

Debugging Tips

Enable Verbose Output

Request detailed reasoning:

"Use the my-agent agent to [task]. Please explain your reasoning step by step."

Check Agent Configuration

# View agent file
cat .claude/agents/my-agent.md

# Check YAML is valid
head -10 .claude/agents/my-agent.md

Test Incrementally

1. Test with minimal input
2. Test with complex input
3. Test edge cases
4. Test error conditions

Compare With Working Agent

If you have a working agent:

1. Compare configuration
2. Compare system prompt structure
3. Identify differences
4. Apply successful patterns

Simplify and Rebuild

If agent is complex and broken:

1. Start with minimal version
2. Test basic functionality
3. Add features incrementally
4. Test after each addition

---

Getting Help

Information to Provide

When asking for help, include:

1. Agent File:

   cat .claude/agents/my-agent.md
   

2. What You're Trying:

   • Exact command or request
   • Expected behavior
   • Actual behavior

3. Error Messages:

   • Full error text
   • When it occurs

4. Environment:

   • Project type (Rails, Node, etc.)
   • Agent location (project vs user)
   • Claude Code version

Where to Ask

• Claude Code documentation
• Project team (for project agents)
• Claude Code community forums
• GitHub issues (if applicable)

---

Prevention Checklist

Avoid issues by following this checklist when creating agents:

• Name is lowercase-with-hyphens
• YAML frontmatter is valid
• Description is specific and action-oriented
• Tools are appropriate for task
• System prompt is detailed
• Output format is defined
• Examples are included
• Constraints are explicit
• File is in correct location
• Tested with multiple inputs
• Documented for team (if shared)

---

See Also:

• Configuration Guide
• Best Practices
• Agent Examples