Agent Chain Analyzer

Agent Chain Analyzer Skill

Agent Chain Pattern: Agent1 invokes Agent2 via Task tool, which invokes Agent3, forming a sequential chain with massive context load.

Impact:

• 180K+ tokens for 4-agent chain (4 × 45K)
• No state persistence across chain
• No user approval workflow
• Fragile (single failure breaks chain)

Solution: Convert to Manager-as-Agent + Skills (53% context reduction)

You execute deterministic scripts to detect chains, map dependencies, calculate depth, and estimate context impact.

detect-agent-chains

Detect all agent chain patterns in project.

Input:

• project_path: Path to Claude Code project root

Process:

1. Execute: scripts/detect-agent-chains.sh "{project_path}"
2. Parse JSON output
3. Return chain detection results

Output:

{
  "status": "success",
  "chains_detected": true,
  "chain_count": 2,
  "chains": [
    {
      "chain_id": "catalog-process-chain",
      "entry_point": "catalog-fetcher",
      "agents": ["catalog-fetcher", "catalog-analyzer", "catalog-validator", "catalog-reporter"],
      "depth": 4,
      "locations": [
        ".claude/agents/catalog-fetcher.md",
        ".claude/agents/catalog-analyzer.md",
        ".claude/agents/catalog-validator.md",
        ".claude/agents/catalog-reporter.md"
      ],
      "invocation_pattern": "Task tool",
      "context_estimate": 180000
    }
  ],
  "total_agents_in_chains": 7,
  "max_chain_depth": 4
}

analyze-chain-depth

Analyze chain depth and complexity for each detected chain.

Input:

• project_path: Path to Claude Code project root
• chains: Detected chains from detect-agent-chains operation

Process:

1. Execute: scripts/analyze-chain-depth.sh "{project_path}" "{chains_json}"
2. Calculate depth metrics
3. Identify complexity factors

Output:

{
  "status": "success",
  "depth_analysis": [
    {
      "chain_id": "catalog-process-chain",
      "depth": 4,
      "complexity_score": 0.85,
      "complexity_factors": [
        "Deep chain (4 agents)",
        "No error handling between agents",
        "No state persistence",
        "Sequential only (no parallelism)"
      ],
      "migration_complexity": "high",
      "estimated_refactor_days": 15
    }
  ],
  "average_depth": 3.5,
  "deepest_chain": {
    "chain_id": "catalog-process-chain",
    "depth": 4
  }
}

map-chain-dependencies

Map complete dependency graph for agent chains.

Input:

• project_path: Path to Claude Code project root
• chains: Detected chains from detect-agent-chains operation

Process:

1. Execute: scripts/map-chain-dependencies.sh "{project_path}" "{chains_json}"
2. Build dependency graph
3. Identify data flow between agents

Output:

{
  "status": "success",
  "dependency_graph": {
    "nodes": [
      {"id": "catalog-fetcher", "type": "entry_point"},
      {"id": "catalog-analyzer", "type": "intermediate"},
      {"id": "catalog-validator", "type": "intermediate"},
      {"id": "catalog-reporter", "type": "terminal"}
    ],
    "edges": [
      {
        "from": "catalog-fetcher",
        "to": "catalog-analyzer",
        "data_passed": ["catalog_data", "metadata"],
        "invocation_method": "Task tool"
      },
      {
        "from": "catalog-analyzer",
        "to": "catalog-validator",
        "data_passed": ["analysis_results"],
        "invocation_method": "Task tool"
      },
      {
        "from": "catalog-validator",
        "to": "catalog-reporter",
        "data_passed": ["validation_results"],
        "invocation_method": "Task tool"
      }
    ]
  },
  "data_flow": [
    "catalog_data (fetcher → analyzer)",
    "analysis_results (analyzer → validator)",
    "validation_results (validator → reporter)"
  ],
  "parallelization_opportunities": [
    "analyzer and validator could run in parallel if refactored"
  ]
}

estimate-chain-context

Calculate context load impact for agent chains.

Input:

• project_path: Path to Claude Code project root
• chains: Detected chains from detect-agent-chains operation

Process:

1. Execute: scripts/estimate-chain-context.sh "{project_path}" "{chains_json}"
2. Calculate current context load
3. Estimate post-migration load
4. Calculate reduction percentage

Output:

{
  "status": "success",
  "context_estimates": [
    {
      "chain_id": "catalog-process-chain",
      "current_context": {
        "agents": 4,
        "tokens_per_agent": 45000,
        "total_tokens": 180000,
        "overhead_tokens": 40000,
        "grand_total": 220000
      },
      "projected_context": {
        "manager_agent": 45000,
        "skills": 4,
        "tokens_per_skill": 5000,
        "skills_total": 20000,
        "overhead_tokens": 10000,
        "grand_total": 75000
      },
      "reduction": {
        "tokens_saved": 145000,
        "percentage": 0.66,
        "description": "66% context reduction (220K → 75K)"
      }
    }
  ],
  "total_current_context": 220000,
  "total_projected_context": 75000,
  "total_reduction": 0.66
}

✅ COMPLETED: Agent Chain Analyzer
Project: {project_path}
───────────────────────────────────────
Chains Detected: {count}
Max Depth: {depth} agents
Context Impact: {tokens} tokens
Reduction Potential: {percentage}% ({tokens} saved)
───────────────────────────────────────
Results returned to: project-auditor agent

No chains detected:

{
  "status": "success",
  "chains_detected": false,
  "chain_count": 0,
  "chains": [],
  "message": "No agent chains found - project uses modern architecture"
}

Script execution failed:

{
  "status": "error",
  "error": "script_failed",
  "script": "{script_name}",
  "message": "{error_output}",
  "resolution": "Check script permissions and agent file access"
}

Invalid chain data:

{
  "status": "error",
  "error": "invalid_chain_data",
  "message": "Chain structure malformed",
  "resolution": "Ensure detect-agent-chains returned valid JSON"
}

Integration

Invoked By:

• project-auditor agent (Phase 5: Execute - detailed analysis)

Depends On:

• Agent files in .claude/agents/
• Grep patterns for Task tool invocations
• Agent invocation patterns (@agent-*, Task tool)

Outputs To:

• Anti-patterns list in audit report
• Migration roadmap generator
• Context optimization calculator

Design Notes

Why CRITICAL?

Agent chains are the #1 context load issue in pre-skills projects:

• 4-agent chain = 180K tokens (53% of budget)
• 6-agent chain = 270K tokens (exceeds budget)
• Migration = 58-72% context reduction

Detection Strategy:

1. Direct Detection: Grep for Task tool, Task(, @agent- in agent files
2. Indirect Detection: Follow invocation chains recursively
3. Validation: Ensure invoked entity is an agent (not skill)
4. Mapping: Build complete dependency graph

Common Chain Patterns:

• Linear Chain: A → B → C → D (most common)
• Branching Chain: A → B → (C, D) (rare, more complex)
• Recursive Chain: A → B → A (dangerous, infinite loop risk)