Guide · Agent skill
How to use the Agent Introspection Debugging agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Agent Introspection Debugging is a skill, meaning a set of written instructions that an AI agent reads before it works. When an agent loops on the same tool, burns tokens without progress, hits errors like ECONNREFUSED or 429, or drifts off its task, this skill tells it to stop retrying and follow a structured process. This guide shows you how to install the skill, how to ask for it, and what the agent produces, so you can get a written diagnosis you can review.
Agent Introspection Debuggingaffaan-m/ECC · MIT Download the skill Quick start
- 1Download and unzip. Download the ZIP from this page and unzip the agent-introspection-debugging folder, which contains SKILL.md and agents/openai.yaml.
- 2Place the skill folder. Move the folder into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one repository.
- 3Or upload in the Claude apps. If you use the Claude apps, go to Settings → Capabilities → Skills and upload the skill there instead.
- 4Describe the failure. Start a request by naming the symptom, such as a loop, repeated retries, ECONNREFUSED or 429 errors.
- 5Ask for a diagnosis, not a retry. Say you want a reproducible diagnosis before any retry, so the agent follows capture, diagnosis and contained recovery.
- 6Review the report. Read the Agent Self-Debug Report, check the root-cause hypothesis and the evidence, and confirm the result is success, partial or blocked.
What is an agent skill, and what does this one make the agent do?
An agent skill is a folder with a SKILL.md file that tells an AI agent how to handle a certain kind of task. The agent loads the instructions when they fit the request. This skill is a debugging workflow. It does not run in the background and does not monitor anything by itself.
When it is active, the agent works through four phases: it captures the failure (error, last successful step, last failed command, repeated patterns and environment assumptions), matches the failure to a known pattern such as a repeated command, a connection refusal, a 429 quota error or a missing file after a write, runs one direct check, and applies the smallest safe recovery action. It finishes with a structured Agent Self-Debug Report.
Install the Agent Introspection Debugging skill
Download the ZIP from this page and unzip it. The skill folder contains agents/openai.yaml and SKILL.md. Then put the folder in one of these locations:
Personal install: unzip into ~/.claude/skills/ so it is available across your projects.
Project install: unzip into the project's .claude/skills/ folder so it applies only to that repository.
In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project: .claude/skills/ inside your repository
- Claude apps: Settings → Capabilities → Skills
Trigger the skill with a natural request
You do not need special syntax. The skill's description says to use it when an agent run fails and you need a reproducible diagnosis instead of a retry, so ask for that in plain words. Name the symptom you are seeing, and say that you want a diagnosis rather than another attempt.
Good requests describe the situation: the agent has retried the same command several times, the run hit a loop limit, or the agent is getting 429 errors and you want to know why before it tries again.
- "The agent keeps running the same test command. Use the agent introspection debugging skill to capture the failure and diagnose it before retrying."
- "We're getting ECONNREFUSED from the local service during this run. Diagnose it with the debugging skill instead of retrying."
- "The run is burning tokens without progress and seems to be drifting from the task. Follow the introspection debugging workflow and give me the report."
What the output looks like
The skill asks the agent to produce a failure capture, a recovery action checklist and a final report. The report includes fields for session or task, failure, root cause, recovery action, result (success, partial or blocked), token or time burn risk, follow-up needed and a preventive change to encode later.
The skill also says the agent should not end with "I fixed it" alone. It must state the failure pattern, the root-cause hypothesis, the recovery action and the evidence that the situation is now better or still blocked.
## Agent Self-Debug Report
- Session / task:
- Failure:
- Root cause:
- Recovery action:
- Result: success | partial | blocked
- Token / time burn risk:
- Follow-up needed:
- Preventive change to encode later:Use it well: examples and what to expect
The skill favours one discriminating check over several guesses. The source gives the bad pattern as retrying the same action three times with slightly different wording, and the good pattern as: capture the failure, classify the pattern, run one direct check, and change the plan only if the check supports it.
If the failure is a code change that now needs testing, the skill says to use the verification-loop skill after recovery. If the problem is a decision rather than a technical fault, it points to the council skill instead.
- Looping on one tool: the agent inspects the last tool calls for repetition and narrows the task to one failing command.
- Connection errors: the agent verifies service health, URL and port before changing code.
- Rate limits (429): the agent counts repeated calls and checks retry spacing, which points to a missing backoff.
- Missing file after a write: the agent re-checks the path, working directory, git status and whether the file exists.
What you need and the safety notes
The skill lists no required tools or dependencies. It does not run scripts and does not use the network, according to its listing. It is written instructions and checklists only.
The skill explicitly tells the agent not to claim automatic repairs such as resetting agent state or updating harness configuration unless it actually does them through real tools in the current environment. Expect a diagnosis and a proposed smallest action, not an automatic fix.
- Requirements: none listed
- Runs scripts: no
- Uses network: no
- Licence: MIT
Tips for better results
Give the agent the real goal in one sentence at the start. The skill's first recovery step is to restate the objective, and a clear goal makes the diagnosis more useful.
Read the report before accepting the fix. The root-cause hypothesis is a hypothesis, and the report asks for the evidence that would prove the fix worked.
Keep the report. Its preventive change field is a good place to record a rule you want future runs to follow.
- Name the symptom exactly, such as ECONNREFUSED or 429, because the skill matches patterns.
- Ask for the report even if the agent seems to recover, so the outcome is written down.
- Use the skill alongside the ECC skills it references when those are relevant.
What people use it for
- Stopping an autonomous coding agent that keeps running the same command with no progress.
- Diagnosing ECONNREFUSED or timeout errors by checking service health, URL and port assumptions.
- Finding a retry storm behind 429 quota errors by counting repeated calls and checking backoff.
- Investigating a file that is missing after a write by checking cwd, branch and git status.
- Writing consistent, reviewable failure reports for a team running agents.
Frequently asked questions
Is the agent introspection debugging skill free?
The skill is published under the MIT licence, as stated in its listing and SKILL.md. The source does not mention pricing for the skill itself, so check the ECC repository for licence terms.
Do I need to install anything else to use it?
The listing says no requirements are listed. The skill runs no scripts and uses no network, so it is made of written instructions that the agent reads.
How do I install agent skills in Claude?
Unzip the skill folder into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder for one repository. In the Claude apps you can upload it under Settings → Capabilities → Skills.
Does this skill fix my agent automatically?
No. The skill tells the agent to diagnose and apply the smallest safe action, and it forbids claiming automatic repairs such as resetting agent state unless real tools perform them.
When should I use verification-loop instead?
Use verification-loop for feature verification after code changes. The skill says it is not the primary source for that task and points to verification-loop after recovery if code was changed.
Is this better than just retrying a failed agent run?
For repeated or unclear failures the skill argues it is better, because it asks for capture, one direct check and a written cause before any change. For a simple one-off error, a normal fix is usually faster.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you build or run autonomous coding agents and need a consistent, written diagnosis when they loop, stall or hit connection or rate-limit errors. Skip it for simple one-off errors, for checking feature work after code changes (use verification-loop), or if you expect it to repair your agent automatically.
Download the skill