agent-introspection-debugging

Diagnose repeated AI agent failures and classify root causes into structured introspection reports.

Updated Jun 24, 2026
One-click install
npx skills add https://github.com/mostafa-ismail-2004/codex-plugin --skill agent-introspection-debugging-mostafa-ismail-2004
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: agent-introspection-debugging
Source: https://github.com/mostafa-ismail-2004/codex-plugin/tree/main/skills/agent-introspection-debugging
Command: npx skills add https://github.com/mostafa-ismail-2004/codex-plugin --skill agent-introspection-debugging-mostafa-ismail-2004

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps an AI agent diagnose why it is stuck, looping, drifting, or repeatedly failing so it can recover with a smaller, safer corrective action instead of wasting more tokens.

Core Features & Use Cases

  • Failure capture: Records the exact error, last successful step, failed tool call, and environment assumptions before another retry.
  • Root-cause diagnosis: Classifies common agent failure patterns such as tool loops, context overflow, timeouts, missing files, and wrong hypotheses.
  • Contained recovery: Recommends the smallest reversible action, such as narrowing scope, verifying state, or trimming context.
  • Introspection reporting: Produces a clear debug report for the next agent or a human handoff.
  • Use case: An agent keeps retrying the same command after a timeout; this Skill guides it to capture the failure, verify service state, and choose a targeted recovery step.

Quick Start

Use this skill to diagnose the failure pattern, confirm the current world state, and produce a concise recovery report before retrying.

Frequently Asked Questions about agent-introspection-debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I stop an AI agent from looping on the same failed tool call?

To stop agent failure loops, you need to capture the exact error, verify the current environment state, and classify the root cause before attempting a contained, targeted recovery action instead of retrying.

What is agent self-debugging for context overflow and stalled progress?

Agent self-debugging is the process of diagnosing why an agent is stuck, drifting, or repeatedly failing, allowing it to apply a smaller, safer corrective action and produce a legible introspection report rather than wasting tokens.

How do I diagnose repeated agent failures caused by environment mismatch?

Diagnose environment mismatch failures by recording the failed tool call, last successful step, and environment assumptions, then classifying the pattern to recommend the smallest reversible action to verify state and recover.

Can I generate a recovery report for a stalled agent handoff?

Yes, you can generate a concise recovery report by capturing the structured failure data, classifying the root cause of the stall, and documenting the contained recovery action needed for a clean human or agent handoff.

What is the best way to recover from agent context overload without wasting tokens?

The best way to recover from context overload is to apply contained recovery by narrowing scope, verifying state, or trimming context, which prevents further token exhaustion and guides the agent toward a targeted retry.

When should I not use an automated retry for agent timeouts?

You should avoid automated retries when a timeout indicates a deeper environment mismatch or tool loop, requiring structured failure capture and root-cause diagnosis to determine a safe, contained recovery action first.