Guide · Agent skill
How to use the Custom Investigation Selector agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The custom-investigation skill lets an AI agent review a chosen set of another agent's recorded conversations instead of a random sample. You describe what you are looking for, such as conversations that hit an error or used a particular tool, and the agent writes a SQL selector over the telemetry table to pick them. This guide explains what the skill does, how to install it, how to trigger it, and what it needs before you run it.
Custom Investigation Selectorgoogle/adk-recipes · Apache-2.0 Download the skill Quick start
- 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Confirm your deployment. Check that you have a running AQuA deployment in session_review mode and access to the observed agent's telemetry table in BigQuery.
- 3Make a natural request. Ask the agent to investigate a specific set of conversations, such as those with an error, a tool, slow latency, or a topic.
- 4Agree on the focus. Answer the agent's question about what you are trying to find out so it knows which filter to write.
- 5Preview the selection. Review the matched count, the would-review count, and the example links the preview returns.
- 6Approve and start. If the examples look right, approve the preview and let the agent start the investigation with the same arguments.
What an agent skill is and what this one does
An agent skill is a folder of instructions and reference files that an AI agent loads when a request matches the skill's description. This one is designed for the ambient quality agent (AQuA), which reviews the recorded conversations of another deployed agent.
By default an ambient sweep reviews a random sample of a time window. With this skill, the agent writes a SQL query, called a selector, over telemetry data to choose conversations matching criteria such as errors, a specific tool, slow latency, a topic, looping, or abandonment. It previews the matches with you, starts the review after your approval, and can narrow the reviewer's focus to a particular kind of problem.
- Selects conversations by error, tool, latency, deployment revision, or content
- Previews the count and example conversations before anything is reviewed
- Can re-review conversations already seen with a different focus
Install the skill from the ZIP
Download the ZIP of the skill from this page and unzip it. Place the resulting folder in one of two locations: ~/.claude/skills/ to make it available to you across projects, or a project's .claude/skills/ folder to share it with that project.
To use it in the Claude apps instead, upload the skill under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Project: unzip into .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills
Check the requirements before you start
The skill only works against a running AQuA deployment in session_review mode. Deployments that score sessions rather than review them refuse these tools outright, so the skill cannot run there.
You also need access to the observed agent's telemetry table in BigQuery. The selector can only read that one table. The bundled reference files describe the Google Cloud tooling involved: BigQuery, Cloud Logging and Cloud Ops.
- A running AQuA deployment in session_review mode
- Access to the observed agent's telemetry table via BigQuery
- Familiarity with the Google Cloud tooling in the bundled references (BigQuery, Cloud Logging, Cloud Ops)
Trigger the skill with a natural request
You do not need a special command. Ask the agent to investigate a specific slice of conversations. The skill's description names the kinds of requests it handles: conversations that hit an error, used a particular tool, ran slowly, mention a topic, looped, or were abandoned, or conversations already seen that you want re-reviewed with a different focus.
The agent will first state what it can narrow by, then ask what you are trying to find out. It checks the telemetry table's columns and only offers filters those columns can express.
- "Investigate only the conversations where the search tool returned an error."
- "Review the sessions that took longer than two minutes this week."
- "Re-review the conversations we already looked at, focusing on how the agent handles refunds."
Preview, check the examples, then start
The agent writes the selector and runs a preview. The preview reports how many conversations matched, how many the budget will sample, and up to five example conversations, each shown as a link to its case view. Open the examples to confirm the selector picked the right conversations.
Preview and run each take their own random sample, so the examples you see are not guaranteed to be the conversations the run reviews. Approve the preview and the agent starts the investigation with the same arguments.
If the selector is rejected, the agent can fix it and preview again. A rejection is limited to three attempts per conversation, after which the agent shows you the rejection instead of rewriting the SQL further.
- Look for the matched count and the example links before approving
- Expect the run's sample to differ from the preview's examples
- A preview that times out returns no count; narrow the selector and try again
Safety notes: scripts and network access
This skill runs scripts and uses the network. It reads telemetry through BigQuery, and the selector is checked before anything runs: it must project a single target_id column, must reference the bound window and agent name, must not reference the limit, and may read only the selector table. Any other table is refused before the query executes.
Because the skill queries live telemetry, review the selector and the preview counts before approving a run. Cloud Trace links in the examples appear only when a trace id was recorded for that conversation.
- Selectors may read only the designated selector table
- Selectors that query no table are rejected
- Review the preview before approving the run
Tips for better selectors
Describe the problem in concrete terms, such as the tool name, the error, or a latency threshold. The more specific the request, the more directly the selector maps onto the table's columns.
Conditions about a whole conversation, such as a tool called several times or a user message never answered, belong in a grouped HAVING clause, not a row-level WHERE clause. The agent handles this, but you can ask it to explain the selector if the matches look wrong.
If the table lacks a column you mentioned, the agent will tell you rather than guessing. Empty columns are possible, so a preview with zero matches can mean the data is missing rather than that nothing happened.
- Name the tool, error, or threshold you care about
- Ask the agent to explain the selector if matches look wrong
- Treat zero matches as a possible data gap, not proof of absence
What people use it for
- Reviewing only conversations where a specific tool returned an error
- Finding slow conversations for a latency investigation
- Re-reviewing past conversations with a different reviewer focus
- Checking conversations that mention a particular topic
- Looking for conversations that looped or were abandoned
Frequently asked questions
How do I install the custom-investigation agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What do I need to use this skill?
You need a running ambient quality agent (AQuA) deployment in session_review mode and access to the observed agent's telemetry table through BigQuery. Deployments that score sessions instead of reviewing them will refuse the tools.
Is this skill free to use?
The source material provided here does not state pricing or licence terms beyond the listed Apache-2.0 licence. Check the repository's licence file for the terms that apply to you.
Why do the preview examples differ from the conversations the run reviews?
The preview and the run each take their own random sample from the matched conversations, so they will almost certainly differ. The examples help you check the selector, but they are not the set that gets reviewed.
Why does my selector get rejected?
A selector must project a single target_id column, reference the bound window and agent name, must not reference the limit, and may read only the selector table. Selectors that query no table are also rejected. The rejection reason and explanation tell you which rule was broken.
Can I use this skill on a deployment that scores sessions?
No. The tools refuse outright on deployments that score sessions rather than review them, because selectors exist only in session_review mode. No selector will make it run in that mode.
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 run the ambient quality agent in session_review mode and want to examine specific failing, slow, or unusual conversations rather than a random sample. Pick something else if your deployment scores sessions, or if you lack access to the observed agent's telemetry table, since the skill cannot run without them.
Download the skill