Skip to content
Get packs

Root-Cause Analysis for Agent Insights

Diagnose why an AQuA-observed agent failed by reading its own source and conversations

Source Download skill
Repository
google/adk-recipes
Stars
10,568
Licence
Apache-2.0
Files
1 file

What it does

This skill teaches an AI agent to investigate a flagged failure (called an insight) in another AI agent. The agent looks up the code revision that produced the failure, searches and reads that source code, reviews the full conversations behind the problem, and explains the root cause with exact file and line citations. It also records a proposed code fix in the AQuA system, but it is designed to be read-only and never edits the agent's code or opens pull requests.

Great for

  • Developers debugging an agent whose behavior was flagged by AQuA quality monitoring
  • Teams who want evidence-backed explanations with file and line citations rather than guesses
  • Engineers reviewing prompt or instruction wording that caused an agent to misbehave

Skip it if

  • Projects not using AQuA or the ADK ambient quality agent, since the tools it calls are specific to that system
  • Situations expecting a verified fix: the skill states the fix is unverified and nothing is tested by it
  • Anyone expecting it to change code automatically, because the procedure forbids writing to the observed agent's source

Try asking

  • “Diagnose insight 42 ("refund loop") - what is the root cause, and how would you fix it?”
  • “Why did the agent behave that way in insight 1187? Cite the prompt lines responsible.”
  • “Read the conversations behind this insight and explain what the agent got wrong.”
Step-by-step guide: how to use Root-Cause Analysis for Agent InsightsInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 1 original files, the Apache-2.0 licence and an attribution note.

    rca.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip rca.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip rca.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 insight id and its label so the agent starts from the right failure.
  • Set a developer goal in AQuA beforehand, since the agent reads it to focus the diagnosis.
  • Treat the cited code and recorded fix as a starting point and verify with your own tests before changing anything.

What's inside

  • SKILL.md

Redistributed unmodified from google/adk-recipes under the Apache-2.0 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.