| name | agent-chain-analyzer |
| description | Detects and analyzes agent chain anti-patterns where agents invoke other agents sequentially causing massive context load |
| model | claude-haiku-4-5 |
Agent Chain Analyzer Skill
You detect and analyze the **Agent Chain anti-pattern** - one of the most severe architectural issues in pre-skills Claude Code projects.
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.
<CRITICAL_RULES>
- ALWAYS detect ALL agent chains in project (not just obvious ones)
- ALWAYS calculate full chain depth and context impact
- ALWAYS map complete dependency graph
- ALWAYS return structured JSON output
- NEVER modify project files (read-only analysis)
- NEVER miss indirect chains (Agent1 → Agent2 → Agent3 → Agent4)
</CRITICAL_RULES>
detect-agent-chains
Detect all agent chain patterns in project.
Input:
project_path: Path to Claude Code project root
Process:
- Execute:
scripts/detect-agent-chains.sh "{project_path}"
- Parse JSON output
- 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"
analyze-chain-depth
Analyze chain depth and complexity for each detected chain.
Input:
project_path: Path to Claude Code project rootchains: Detected chains from detect-agent-chains operation
Process:
- Execute:
scripts/analyze-chain-depth.sh "{project_path}" "{chains_json}"
- Calculate depth metrics
- 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"
map-chain-dependencies
Map complete dependency graph for agent chains.
Input:
project_path: Path to Claude Code project rootchains: Detected chains from detect-agent-chains operation
Process:
- Execute:
scripts/map-chain-dependencies.sh "{project_path}" "{chains_json}"
- Build dependency graph
- 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":
estimate-chain-context
Calculate context load impact for agent chains.
Input:
project_path: Path to Claude Code project rootchains: Detected chains from detect-agent-chains operation
Process:
- Execute:
scripts/estimate-chain-context.sh "{project_path}" "{chains_json}"
- Calculate current context load
- Estimate post-migration load
- 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,
Upon completion of analysis, output:
✅ 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
<ERROR_HANDLING>
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"
}
</ERROR_HANDLING>
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:
- Direct Detection: Grep for
Task tool, Task(, @agent- in agent files
- Indirect Detection: Follow invocation chains recursively
- Validation: Ensure invoked entity is an agent (not skill)
- 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)
