When Agents Fail: Systematic Bug Diagnosis for LLM Agent Systems

This skill equips Claude with a structured diagnostic framework for identifying, classifying, and fixing bugs in LLM agent-based software. Derived from a study of 1,187 real bug reports across Stack Overflow, GitHub, and Hugging Face forums, it covers agents built with LangChain, LangGraph, CrewAI, AutoGen, LlamaIndex, Semantic Kernel, Hugging Face Transformers Agents, and custom implementations. Rather than guessing at fixes, Claude systematically narrows the bug by type, root cause, affected component, and observable effect to produce targeted solutions.

When to Use

• When a user reports a crash, error, or unexpected behavior in an LLM agent system
• When an agent produces empty responses, partial output, or ignores available tools
• When an agent enters an infinite loop or hangs during multi-step reasoning
• When a user is getting parsing errors from LLM output that doesn't match expected formats
• When upgrading an agent framework breaks previously working code
• When an agent loses conversation context or memory between turns
• When reviewing or building agent code and the user wants to proactively catch common bug patterns
• When a user asks "why does my agent keep failing" without a clear error message

Key Technique: Component-Aware Bug Taxonomy

LLM agents consist of four architectural components, each with distinct failure modes: