Skip to content

diegosouzapw/awesome-omni-skill / skills/ai-agents/agent-chain-analyzer

agent-chain-analyzer

Verified

Detects and analyzes agent chain anti-patterns where agents invoke other agents sequentially causing massive context load

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.

<CRITICAL_RULES>

  1. ALWAYS detect ALL agent chains in project (not just obvious ones)
  2. ALWAYS calculate full chain depth and context impact
  3. ALWAYS map complete dependency graph
  4. ALWAYS return structured JSON output
  5. NEVER modify project files (read-only analysis)
  6. 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:

  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

<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:

  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)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall