Skip to content
Get packs

Agent Introspection Debugging

Guides an AI agent to diagnose its own repeated failures before retrying, and to write a structured debug report.

Source Download skill
Repository
affaan-m/ECC
Stars
295,127
Licence
MIT
Files
2 files

What it does

When an AI agent gets stuck, for example looping on the same tool, burning tokens without progress, hitting rate limits or connection errors, or drifting off the task, this skill tells the agent to stop blindly retrying. It makes the agent first record what failed, match the failure to a known pattern, run one direct check, and then apply the smallest safe fix. It ends with a structured report explaining the cause and outcome. It is a set of written instructions and checklists, not a separate program running in the background.

Great for

  • Developers building or running autonomous coding agents who see loops, retry storms or stalled runs
  • Teams that want agent failures written up in a consistent, reviewable format
  • People using the ECC skill collection who want a debugging workflow that hands off to other ECC skills

Skip it if

  • Simple one-off errors where a normal fix is faster; the four-phase process adds overhead
  • Feature verification after code changes, which the skill itself says should use the verification-loop skill instead
  • Anyone expecting it to automatically repair the agent or its configuration; the text explicitly forbids claiming such auto-healing unless real tools do it

Try asking

  • “My agent keeps calling the same tool over and over and hitting the max tool call limit. Diagnose it before retrying.”
  • “The agent got 429 errors from the API. Work out whether it is a retry storm and write a debug report.”
  • “Tests still fail after the agent's last fix. Isolate the failing test and re-derive the bug.”
  • “The file the agent wrote is missing on disk. Check the working directory, branch and file existence.”
Step-by-step guide: how to use Agent Introspection DebuggingInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 2 original files, the MIT licence and an attribution note.

    agent-introspection-debugging.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip agent-introspection-debugging.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip agent-introspection-debugging.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Give the agent the actual error text and logs so the capture phase has real evidence to work from.
  • Ask for the debug report at the end so the failure pattern and outcome are recorded for later review.
  • Pair it with verification-loop after any code change made during recovery, as the skill recommends.

What's inside

  • agents/openai.yaml
  • SKILL.md

Redistributed unmodified from affaan-m/ECC under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.