How to use the Agent Introspection Debugging agent skill

What does the skill make the agent do?

The skill gives the agent a four-phase routine: capture the failure, diagnose the root cause against common failure patterns, apply the smallest safe recovery action, and finish with a structured introspection report. The agent is told to stop blindly retrying and to check the actual state of files, branches and processes before changing its plan.

It is a workflow, not a hidden runtime. It does not run in the background or watch the agent. It describes behaviour that the agent must carry out with its own tools.

• Capture: record the error, the last successful step, the last failing tool or command, and any repeated pattern.
• Diagnose: match the failure to patterns such as repeated tool calls, context overflow, ECONNREFUSED or timeouts, 429 quota errors, missing files after a write, and tests that keep failing after a fix.
• Recover: make one minimal change, such as narrowing the task to one failing command, file or test, or switching from guessing to direct observation.
• Report: write a debugging report covering root cause, recovery action, result (success, partial or blocked) and follow-up needed.

How do you install the skill?

You can install the skill in either of two ways. The first is to download the ZIP from this page and unzip it into your personal skills folder at ~/.claude/skills/ or into a project-level .claude/skills/ folder inside your repository. The second is to upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

The download contains a single file, SKILL.md, which holds the skill's name, description and full instructions.

• Personal install: unzip into ~/.claude/skills/ so the skill is available across your projects.
• Project install: unzip into .claude/skills/ inside the project so it applies only to that repository and can be shared with your team.
• Claude apps: go to Settings → Capabilities → Skills and upload the ZIP.

How do you trigger the skill with a natural request?

You do not need a special command. The skill is intended for moments when an agent run is failing repeatedly, consuming tokens without progress, looping on the same tool, or drifting from the task. Describe the situation in plain words and ask the agent to debug itself before retrying.

Good requests name the symptom and ask for the structured process, for example asking the agent to capture the failure first, then diagnose it, then report what it did.

• "Your last three attempts failed with the same error. Stop retrying, capture the failure, and diagnose it using the introspection debugging process."
• "You have used many tool calls without progress. Narrow the task to the single failing test and write a debugging report when you are done."
• "Before you try again, check the actual file state and git status, then tell me the root cause and your recovery action."

What does a good result look like?

A useful run ends with a report rather than a bare statement that the problem is fixed. The skill's output standard asks for the failure pattern, a root-cause hypothesis, the recovery action, and evidence showing whether the situation improved or is still blocked.

The skill also asks the agent to escalate to a human when the problem is high-risk or blocked by something outside its control. Expect the agent to say so plainly rather than keep trying.

• Failure pattern and root-cause hypothesis.
• Recovery action and why it was judged safe.
• Evidence that the fix worked, or a clear statement that the task is still blocked.
• Follow-up items and any preventive change worth recording for later.

What does the skill need, and what are the safety notes?

The skill lists no required tools or dependencies. It does not run scripts and does not use the network. Its only file is SKILL.md, so there is no code to review beyond the written instructions.

The main caution is about what the skill claims. It says the agent should not state that it has reset its memory or changed harness settings unless it actually did so through its own available tools. Check the report for those claims if they matter to you.

• Requirements: none listed.
• Scripts: none. Network: none.
• Agent memory and harness settings are not changed automatically by the skill; the agent must perform those actions itself.
• Escalate to a human when a failure is high-risk or externally blocked.

What are the limits of this skill?

The skill is not a way to verify that code changes work. For that, the skill itself points to a separate verification-loop skill. Framework-specific bugs that narrower skills already cover should be handled by those skills instead.

It also does not manage the agent's memory or configuration for you. Treat it as a reference pattern for self-diagnosis that depends on the agent following it.

• Use verification-loop after code changes.
• Use continuous-learning-v2 if a failure pattern is worth turning into a lasting instinct or future skill.
• Use council when the issue is a decision ambiguity rather than a technical failure.
• Use workspace-surface-audit when the failure comes from conflicting local state or repository drift.

Tips for getting the most from it

Ask for the capture step explicitly, because the skill's value is in writing down what happened before any retry. Keep the scope small when you ask for recovery, since the skill favours narrowing to one command, file or test. Finally, keep the report files so that teammates can see how the agent recovered from a failure.

• Name the symptom you observed, such as a repeated command or a 429 error.
• Ask the agent to check real state (cwd, branch, file presence) instead of trusting its memory.
• Avoid asking for three retries with slightly different wording; the skill explicitly treats that as a bad pattern.
• Read the report's result line to see whether the task succeeded, partly succeeded or is blocked.