How to use the rca agent skill for root-cause analysis

What an agent skill is and what rca makes the agent do

An agent skill is a folder with a SKILL.md file that tells an AI agent how to handle a particular kind of task. The agent reads these instructions when a request matches the skill's description.

The rca skill covers root-cause analysis of one AQuA insight against the observed agent's own source code. The agent looks up the code revision the failure ran on, searches and reads that source, pulls the full conversations behind the insight, and explains the mechanism with citations in the form path:start-end. It then records a proposed code fix against the insight in AQuA.

• Reads the developer's goal and memories first, as reference data rather than as the defect itself.
• Finds the revision the failure ran on and the most recent occurrence of the insight.
• Searches and reads the source at that revision.
• Reviews the complete conversations behind the insight, noting any partial or truncated ones.
• Records the proposed fix in AQuA and writes a reply that explains the mechanism and states that the fix is unverified.

Install the rca skill from the ZIP or the Claude apps

Download the ZIP from the rca page on this site and unzip it. The skill is a folder that contains SKILL.md, so the folder must end up in a skills directory.

For a personal install, unzip it into ~/.claude/skills/. To scope it to one project, unzip it into that project's .claude/skills/ folder instead.

In the Claude apps, you can instead upload the skill under Settings, then Capabilities, then Skills.

• Personal: ~/.claude/skills/
• Project only: the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills

Check the requirements before you run it

The skill does not work on its own. It calls specific AQuA ambient quality agent tools, and it needs access to the AQuA service and to the observed agent's source snapshots. If you do not use AQuA or the ADK ambient quality agent, the tools it calls will not be available.

The tools it relies on include get_insight, get_full_trajectories, search_source, read_source_file, record_root_cause and related calls such as list_revisions and list_source_files.

• Google ADK AQuA ambient quality agent tooling
• Access to the AQuA service
• Access to the observed agent's source snapshots
• Network access, because the skill calls the AQuA service

Trigger the skill with a natural request

The skill is meant to be triggered by a message that names an insight and asks about its cause. The description gives this example: Diagnose insight <id> ("<label>") — what is the root cause, and how would you fix it? You can also ask why the agent behaved a certain way, or ask it to diagnose a failure.

Include the insight id so the agent can call get_insight. The label helps you confirm you are looking at the right insight.

• Diagnose insight <id> ("<label>") — what is the root cause, and how would you fix it?
• Why did the agent behave that way for insight <id>?
• Diagnose the failure in insight <id> and tell me how to fix it.

Read the answer and check its revision and occurrence

A good answer has two parts. The first explains the mechanism, cites the code with path:start-end, and states the revision the code was read at. The second says that the fix is unverified, because nothing in the analysis ran or tested it. The reply names the revision and the occurrence together.

The proposed fix itself is stored as a record in AQuA, shown above the reply on the dashboard. The reply should point to that record rather than repeat the edit. If the record was refused, the reply should give the fix in prose and say it was not saved.

If the revision has no snapshot, or the sighting names no deployment, the reply should say which code it read instead and that the file may have changed since.

• Mechanism with path:start-end citations at a named revision
• A sentence stating the fix is unverified
• Notes on partial, truncated or not_archived conversations
• No pasted patch, diff or replacement text

Safety: read-only, no scripts, network use

The skill is designed to be read-only. Its procedure forbids writing to the observed agent's source, opening a change list, or opening a pull request. Its only write action is recording the proposed fix in AQuA.

The skill runs no scripts. It does use the network, because its tool calls reach the AQuA service. It also tells the agent not to call remember on its own initiative, so it does not save new memories unless you ask.

• Never edits the observed agent's source code
• Never opens a CL or a pull request
• Runs no scripts
• Uses the network to reach AQuA

Tips for getting a useful diagnosis

Give the insight id and ask a specific question. The skill reads the conversations as evidence, so a single sighting may not be enough. If it is not, ask the agent to look at more of the insight's recent sightings.

Keep the goal and memories in AQuA up to date. The skill uses them to find files, but checks them against the snapshot because they can be out of date.

• Ask for the root cause and the fix in one request, as in the example.
• If the answer says the evidence is partial, ask for more recent sightings.
• Treat the fix as a starting point to test yourself, since the skill does not test it.
• Expect prompt or instruction wording to be the most common cause.