How to use the AQuA Agent Quality Monitor agent skill

What a skill is and what this one makes the agent do

An agent skill is a folder with a SKILL.md file that gives an AI agent instructions for one kind of task. Once the skill is installed, the agent reads it when a request matches the skill's description.

This skill covers AQuA. It can deploy AQuA beside your agent or attach your agent to an AQuA deployed elsewhere. It can list insights, fetch root-cause diagnoses for them, and help you fix the defects in the agent's code.

• Investigation: AQuA samples conversations from a telemetry window, reviews them and groups failures into insights. It runs daily at 12:00 UTC by default, about 15 minutes after each redeploy of an agent on Agent Runtime, and on demand.
• Insight: one deduplicated defect with a stable insight_id and a status of NEW, RECURRING or RESOLVED.
• Root cause: a diagnosis of an insight, with proposed edits against a snapshot of the agent's source.

How to install the agents-cli-aqua skill

Download the ZIP for this skill from the page. Then choose one of two install locations.

For all of your projects, unzip the folder into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.

Start a new session afterwards so the agent picks up the skill.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How to trigger the skill with natural requests

You do not need to name the skill. The skill's description lists the situations where it applies, so the agent will usually propose it when you mention AQuA or AQA, ask about traces or observability, ask what is going wrong with your agent in production, or want to fix AQuA insights.

Ask in plain language and say what you want the result to be. The skill is not the right choice for offline evaluation of a local agent (use google-agents-cli-eval instead) or for deployments without AQuA (use google-agents-cli-deploy instead).

• Is my deployed agent producing any new quality insights in AQuA?
• Deploy AQuA beside my agents-cli agent and tell me when the first investigation finishes.
• Show me the root cause for insight NEW insight in AQuA and propose code changes to fix it.
• Attach my agent in project my-project to the AQuA deployment I already have.

Deploy AQuA and attach your agent

AQuA must be deployed before it can watch anything. The skill recommends deploying AQuA on its own, because one AQuA can watch several agents, including agents in other projects. You can also deploy it beside the agent in an agents-cli project.

Attach runs gcloud and bq commands with your credentials. Its --dry-run flag shows the plan and changes nothing. Read the plan first, then run the command again with --yes. Without --yes, attach asks you on the terminal.

• Attach always grants AQuA's service account any read it is denied, and creates an audit log sink for the agent's updates.
• Check that agents-cli aqua info --resource prints a projects/…/reasoningEngines/… path to confirm AQuA is deployed.
• After attaching, run agents-cli aqua list-agents and agents-cli aqua show-config to confirm the agent is listed.

Read insights and root-cause diagnoses

Query subcommands print one JSON document on stdout and progress on stderr, so pipe stdout into jq. Run commands from the agent's project root, the folder containing agents-cli-manifest.yaml, or from AQuA's checkout if you deployed AQuA from there.

Use agents-cli aqua -- --help to list AQuA's commands. Use agents-cli aqua <command> -- --help for a command's flags and the fields of its output. The double dash matters: without it, agents-cli prints its own help instead.

• Insights stay open until they go unseen for 14 days by default. A later recurrence gets a new insight.
• Each investigation records an occurrence with evidence for up to 10 trajectories of an insight.
• A trajectory is one sampled conversation with one trace per turn.

Safety notes: scripts and network access

This skill runs scripts and uses the network. Its listed requirements are agents-cli, uv, gcloud, terraform and jq. You also need a Google Cloud project with credentials that can grant IAM roles and create log sinks.

Attaching and deploying AQuA change cloud resources and IAM permissions in that project. Do not use the skill in a project where you are not allowed to make those changes. Review the --dry-run output before every change.

• Use a project you own or are authorised to change.
• Review dry-run output before running with --yes.
• Do not use the skill without a Google Cloud project.