New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Official agent skill

Adk Debug

by google in google/adk-python

Diagnoses misbehaving ADK agents by inspecting sessions, events, tool calls, and the exact request that reached the model.

OfficialApache-2.0Auto-check passedAgent Workflows

Install Adk Debug

skills CLI
$ npx skills add google/adk-python --skill adk-debug -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install google/adk-python adk-debug --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/google/adk-python.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/adk-debug .claude/skills/adk-debug && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
adk-debug
GitHub stars
22k
Token cost
~837 tokens
SKILL.md length
331 words
Files
6 (incl. references)
Skills in repo
13
Repo updated
First seen
Licence
Apache-2.0

At a glance

Diagnoses misbehaving ADK agents by inspecting sessions, events, tool calls, and the exact request that reached the model.

  • Works in 5 steps: Reproduce headlessly: adk run --jsonl… → Read the log file. adk run writes to… → Match the symptom in failure-modes.md… → …
  • An agent returns the wrong answer
  • SKILL.md covers First moves, References and Ground rules
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Adk Debug is an agent skill from google/adk-python, published by the product's own GitHub organization. Diagnoses misbehaving ADK agents by inspecting sessions, events, tool calls, and the exact request that reached the model. Covers the adk run CLI and the adk web dev server with its session, trace, and debug HTTP endpoints. Use when an agent returns the wrong answer, ignores a tool or swallows a tool error, hangs, loops, emits raw JSON instead of calling tools, is not discovered by adk web, when a sub-agent cannot see the parent conversation, or when you need the LLM request/response, token counts, or logs for a…

Its SKILL.md is about 840 tokens, which your agent loads only when the skill is triggered. The skill folder holds 6 other files, including reference files (for example `references/cli-run.md`, `references/event-flow.md` and `references/failure-modes.md`).

It sits in Agent Workflows, covering Building AI agents, Subagents and Debugging. The repository describes itself as: An open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control. The licence is Apache-2.0.

When your agent uses it

  • An agent returns the wrong answer
  • Swallows a tool error
  • Emits raw JSON instead of calling tools
  • Is not discovered by adk web

Example prompts

  • “Use the adk-debug skill to diagnose misbehaving ADK agents by inspecting sessions, events, tool calls, and the exact request that reached the model”
  • “/adk-debug”

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. Reproduce headlessly: adk run --jsonl {agent_dir} "{query}". Without
  2. Read the log file. adk run writes to /tmp/agents_log/agent.latest.log and
  3. Match the symptom in failure-modes.md before
  4. If the text is fine but the routing is not, dump the events and read
  5. If the model itself misbehaved, read what it actually received from the

What it can do on your machine

Read from SKILL.md and the folder at commit 666c26d. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Adk Debug loads about 837 tokens when it runs, and up to ~6.5k if it reads all its reference files. Until then it costs about 196 tokens; SKILL.md has 331 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~196
When it runs · the whole SKILL.md, loaded when a task matches
~837
With references · SKILL.md plus every file in references/, read only if the agent opens them
~6.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from google/adk-python at commit 666c26d, republished under its Apache-2.0 licence (© google). 331 words, ~837 tokens.

Download SKILL.mdSave it as .claude/skills/adk-debug/SKILL.md (or your agent's skills folder). This skill also uses 5 other files; get the full folder from GitHub.
name
adk-debug
description
Diagnoses misbehaving ADK agents by inspecting sessions, events, tool calls, and the exact request that reached the model. Covers the `adk run` CLI and the `adk web` dev server with its session, trace, and debug HTTP endpoints. Use when an agent returns the wrong answer, ignores a tool or swallows a tool error, hangs, loops, emits raw JSON instead of calling tools, is not discovered by `adk web`, when a sub-agent cannot see the parent conversation, or when you need the LLM request/response, token counts, or logs for a run. Don't use for how ADK is designed internally (use `adk-architecture`), for building a new agent or workflow (use `adk-agent-builder`), for environment or dependency setup failures (use `adk-setup`), or for lint and style nits (use `adk-style`).

Debugging ADK agents

Two entry points. Default to adk run: one process, no server, and --jsonl output that pipes straight into grep or python3. Switch to adk web when you need the browser UI, a persisted session you can click through, or the trace endpoints that expose the exact LLM request.

First moves

  1. Reproduce headlessly: adk run --jsonl {agent_dir} "{query}". Without --jsonl, adk run prints only text parts — tool calls and tool errors are invisible.
  2. Read the log file. adk run writes to /tmp/agents_log/agent.latest.log and nothing to the terminal; adk web does the opposite. See logs-and-traces.md.
  3. Match the symptom in failure-modes.md before reading source — most reports are one of a handful of known shapes.
  4. If the text is fine but the routing is not, dump the events and read author, branch, nodeInfo.path, and actions — event-flow.md.
  5. If the model itself misbehaved, read what it actually received from the call_llm span rather than guessing from the agent definition — logs-and-traces.md.

References

  • cli-run.md — adk run flags, the JSONL event shape, multi-turn and human-in-the-loop resume, exit codes, driving a Runner from Python.
  • web-api.md — starting adk web, listing and reading sessions over HTTP, posting test messages to /run_sse.
  • logs-and-traces.md — log levels and where each command writes them, the trace endpoints, span attributes, and the env vars that control whether prompts appear in spans.
  • failure-modes.md — ADK-specific symptoms with the cause and a concrete check for each.
  • event-flow.md — how an invocation becomes events, callback order, the event fields that matter, and where each stage lives in the source.

Ground rules

  • Leave sessions in place when you finish. The user may still want to open them in the web UI, and adk web has no undelete.
  • Delete any throwaway agent you created for a repro, unless the user asked to keep it.
  • Reach for a unit test in tests/unittests/ when the bug is inside one component, and for a sample under contributing/samples/ (see adk-sample-creator) when it only reproduces with runner, agent, and workflow wired together.

© google, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 5 other files (references) in .agents/skills/adk-debug of google/adk-python.

  • SKILL.md
  • references/cli-run.md
  • references/event-flow.md
  • references/failure-modes.md
  • references/logs-and-traces.md
  • references/web-api.md

Open the folder on GitHubat commit 666c26d

Compare with similar skills

Adk Debug next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Adk Debug compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Adk Debug this skillgoogle/adk-python22k—~837Automated safety check: PassApache-2.0
Astra Orchestratordonvito/codex-astra-luna-orchestrator1.7k—~3.1kAutomated safety check: PassApache-2.0
Coral ExtendHuman-Agent-Society/CORAL1k—~1.6kAutomated safety check: PassApache-2.0
Skill Architectcuriositech/some_claude_skills243—~5.7kAutomated safety check: NotesMIT
Skill Architectcuriositech/some_claude_skills243—~6kAutomated safety check: NotesMIT
Create Agentvectorize-io/hindsight46k—~1.1kAutomated safety check: PassMIT

Similar skills

  • Astra Orchestrator

    donvito/codex-astra-luna-orchestrator

    Orchestrate complex Codex coding work for the Pro profile with GPT-6 Astra at medium reasoning as planner/integrator, Luna subagents for exploration, implementation, testing, and research, and an…

    1.7k GitHub stars~3.1k tokensUpdated 6 days ago
    Agent WorkflowsAuto-check passed

  • Coral Extend

    Human-Agent-Society/CORAL

    Add a new component to the CORAL framework itself — a new agent runtime under coral/agent/builtin/ (claudecode/codex/cursoragent style), a new CLI command in coral/cli/, a new bundled skill or…

    1k GitHub stars~1.6k tokensUpdated 29 days ago
    Agent WorkflowsAuto-check passed

  • Skill Architect

    curiositech/some_claude_skills

    Design, create, audit, and improve Claude Agent Skills with expert-level progressive disclosure.

    243 GitHub stars~5.7k tokensUpdated 1 mo ago
    Agent WorkflowsAuto-check: notes

  • Skill Architect

    curiositech/some_claude_skills

    Design, create, audit, and improve Claude Agent Skills with expert-level progressive disclosure.

    243 GitHub stars~6k tokensUpdated 1 mo ago
    Agent WorkflowsAuto-check: notes

  • Create Agent

    vectorize-io/hindsight

    Create a new Hindsight-powered subagent with long-term memory.

    46k GitHub stars~1.1k tokensUpdated today
    Agent WorkflowsAuto-check passed

  • Analyze Trajectory

    yologdev/yoyo-evolve

    Diagnoses a recurring failure such as a stuck task, repeated CI error or frequent reverts by sending sub-agents through the logs and returning one root-cause diagnosis.

    1.9k GitHub stars~3.6k tokensUpdated today
    Agent WorkflowsAuto-check passed

More from google/adk-python

All 13 skills in this repo

  • Adk Verify Snippets

    google/adk-python

    Official

    Checks that every Python code block in a Markdown file actually compiles and runs, by extracting each block to a temporary file, executing it in an isolated subprocess, and writing a pass/fail…

    22k GitHub stars~1.4k tokensUpdated today
    Auto-check passed

  • Adk Sample Creator

    google/adk-python

    Official

    Creates a new sample agent in the ADK Python repository — the sample directory, its agent.py, and its README.md — following the conventions the existing samples already use.

    22k GitHub stars~1.3k tokensUpdated today
    Auto-check passed

  • Adk Unit Guide

    google/adk-python

    Official

    Writes a hands-on developer guide for one ADK code unit — a minimal runnable example, how it works, a configuration-option table, advanced uses, limitations, and links to related samples — to…

    22k GitHub stars~2.6k tokensUpdated today
    Auto-check passed

  • Adk Git

    google/adk-python

    Official

    Writes commit messages and pull request descriptions for the adk-python repository: Conventional Commits types and scopes, subject lines that say why a change was made, and the linked-issue and…

    22k GitHub stars~1.3k tokensUpdated today
    Auto-check passed

  • Adk Setup

    google/adk-python

    Official

    Sets up a local ADK Python development environment in a git clone of the open-source adk-python repository: a uv virtual environment, all dependency extras, pre-commit hooks, and a first unit-test…

    22k GitHub stars~993 tokensUpdated today
    Auto-check: notes

  • Adk Agent Builder

    google/adk-python

    Official

    Builds ADK (Agent Development Kit) Python agents: LLM agents with tools, graph workflows of function and agent nodes, conditional routing, fan-out and join, schema-validated delegation between…

    22k GitHub stars~879 tokensUpdated today
    Auto-check passed

Categories

Questions about Adk Debug

What does Adk Debug do?

Diagnoses misbehaving ADK agents by inspecting sessions, events, tool calls, and the exact request that reached the model. Adk Debug is an agent skill from google/adk-python, published by the product's own GitHub organization. Diagnoses misbehaving ADK agents by inspecting sessions, events, tool calls, and the exact request that reached the model.

When should I use Adk Debug?

Adk Debug fits situations like: an agent returns the wrong answer; swallows a tool error; emits raw JSON instead of calling tools; is not discovered by adk web.

How do I install Adk Debug in Claude Code?

Run `npx skills add google/adk-python --skill adk-debug -a claude-code`. Or copy the skill folder (.agents/skills/adk-debug in google/adk-python) into .claude/skills/adk-debug in your project. Claude Code loads it when a task matches its description.

How do I install Adk Debug in Codex?

Run `npx skills add google/adk-python --skill adk-debug -a codex`. Or copy the skill folder (.agents/skills/adk-debug in google/adk-python) into .agents/skills/adk-debug in your project. Codex loads it when a task matches its description.

Can I use Adk Debug in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add google/adk-python --skill adk-debug -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/adk-debug, .gemini/skills/adk-debug, .github/skills/adk-debug and .opencode/skills/adk-debug in your project.

What does Adk Debug need to run?

SKILL.md names no scripts, command-line tools or credentials: Adk Debug is instructions for the agent only.

Does Adk Debug access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Adk Debug safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Adk Debug use?

Adk Debug is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Adk Debug use?

About 837 tokens (SKILL.md is roughly 3.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 5.7k tokens, read only when the agent opens those files.

What are the alternatives to Adk Debug?

Skills that share tags, products or a category with Adk Debug: Astra Orchestrator (donvito/codex-astra-luna-orchestrator, 1.7k stars), Coral Extend (Human-Agent-Society/CORAL, 1k stars), Skill Architect (curiositech/some_claude_skills, 243 stars) and Skill Architect (curiositech/some_claude_skills, 243 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Adk Debug?

google (a GitHub organization, an official publisher) maintains it in google/adk-python, which has 21,729 GitHub stars. The repository holds 13 skills in this directory. The repository was last updated on October 7, 2026.

Source: google/adk-python on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.