agent-introspection-debugging

The agent-introspection-debugging skill provides a structured workflow for diagnosing and recovering from repeated AI agent failures. It is designed for situations where an agent becomes stuck in retry loops, consumes excessive tokens without making progress, experiences prompt drift, or repeatedly misuses tools. Instead of relying on blind retries, the skill introduces a disciplined debugging process that captures the current failure state, identifies likely root causes, applies minimal corrective actions, and produces a clear introspection report for human review if escalation becomes necessary. The workflow is intended to improve reliability and reduce wasted execution cycles during complex autonomous tasks.

The skill is organized around a four-phase debugging loop: Failure Capture, Root-Cause Diagnosis, Contained Recovery, and structured reporting. It emphasizes precise failure recording, including error messages, tool-call history, environment assumptions, and context pressure indicators such as duplicated notes or oversized logs. It also provides diagnostic guidance for common agent failure patterns, including repeated command loops, degraded reasoning caused by context overflow, service connectivity problems, quota exhaustion, stale filesystem assumptions, and incorrect debugging hypotheses. Recovery actions focus on minimal and reversible interventions such as trimming low-signal context, narrowing scope to a single failing command or file, verifying actual system state, and switching from speculative reasoning to direct observation.

This skill is useful for AI agents operating in development, automation, orchestration, or multi-step reasoning environments where failures can compound over time. It is intended for agent developers, AI workflow designers, and operators managing autonomous systems that interact with tools, filesystems, services, or external processes. The workflow is especially valuable in environments where transparency, controlled recovery, and human-readable debugging reports are required before escalation or manual intervention.