Review changes proposed by adk-bot (adk-bot-review)
This skill guides a rigorous review of adk-bot changes. It ensures documentation
updates are technically accurate, appropriately sized, and follow ADK docs
conventions, based on Google's developer documentation style.
Step 1: Verify and research the proposed adk-bot change
- Check that the PR title briefly describes the topic being updated, not only
the issue.
- Confirm changes are made directly in the
.md files and no "do not merge"
status tags were prematurely removed.
- Check the PR's mergeable state and CI status. Note git conflicts and failing
checks as findings to resolve or to fix in the consolidating PR.
- The input is one adk-bot-authored PR, or occasionally a few. From the PR,
trace back to the issue and the specific item it addresses. Identify the item
from the PR title ("Update ADK doc according to issue # - ") and
body. adk-bot often opens more than one PR for the same item. If multiple PRs
are provided, confirm they all address the same item and review them together
as one consolidation set. If they address different items, ask the user which
one to focus on before continuing.
- Search closed issues and merged/rejected PRs across the repository for similar
topics. Ensure the bot is not re-introducing changes, APIs, or stylistic
choices that human maintainers have previously debated and rejected.
- Summarize the item's intended change and stated reasoning, and carry that
intent into the technical validation in the next steps.
Step 2: Assess update criteria and architecture
- Prioritize smaller, surgical updates over comprehensive overhauls unless the
existing docs are entirely unclear.
- Verify that the update provides a useful learning experience and is actionable
for a developer.
- Ensure the content is placed appropriately within the ADK docs information
architecture.
- Confirm the update length and prioritization are appropriate for the specific
code change (check if it is already covered by existing docs or API
references).
Step 3: Validate the change against source and intent
- Never assume an AI agent's code snippet is correct.
- Cross-reference all code examples against the
https://github.com/google/adk-python repository.
- Verify the information against relevant pull requests and actual ADK code in
the
https://github.com/google/adk-python repo.
- Confirm the change actually implements what the linked issue and adk-bot PR
set out to do, and resolves the issue item it references.
- Flag any part of the change that drifts from that stated intent, or any part
of the intent the change leaves unaddressed.
Step 4: Check quality and style
Headings
- Maintain a logical h1, h2, h3 hierarchy without empty headings (stacking
headers).
- Do not number headings (Use
## This heading, not ## 1. This heading).
- Use imperative titles (e.g., "Build agents", not "Building agents").
- Do not use command names in headings; call out the task to be done.
Language
- Follow Google's developer documentation style
(https://developers.google.com/style) as the basis for conventions; consult it
for anything not covered here.
- Use active voice phrasing (e.g., "The system does X", not "X is done").
- Never use the word "this" without a noun object (e.g., "This function is
used...", not "This is used...").
Code snippets and formatting
- Enforce an 80-character line length limit for general Markdown text
(excluding long URLs, unbreakable code blocks, or tables).
- Check for rendering errors caused by spaces before backticks (```).
- Use the
!!! warning/tip/note mkdocs-material admonition format for notes and
warnings instead of quote formats (>).
- Do not use ALL CAPS except for code syntax; use bold or italics for emphasis.
Step 5: Report findings and decide the recommendation
First, summarize the findings from the verification steps above, ordered
blockers first, then required edits, then nits. Then choose one outcome below,
justified by those findings:
- Close the bot PR(s). (sometimes) The change is wrong, outdated, targets a
deprecated or unreleased API, or is already covered by live docs or a merged
PR. Record the reason and link the superseding doc or PR.
- Approve as-is (rare). The bot PR(s) are correct, well-placed, and need no
edits.
- Edit in place, then approve (sometimes). The existing branch is usable but
needs conflict resolution, corrections, consolidation, copyedits, or
relocation.
- Open a new consolidating PR (most common). Rework the change across the
1-3 bot PRs into one PR that fixes code errors and hallucinations, edits for
quality, and places the content in the correct file. Then close the superseded
bot PR(s).
Also confirm the change targets the correct file (files may have moved or been
restructured, or the edit may belong on a different page).
Step 6: Produce an action plan
Output the concrete next actions for the chosen recommendation:
- The specific local edits needed: file paths, what to change, code fixes,
consolidation of the 1-3 bot PRs, and correct placement.
- A short list of the verification findings that justify them, ordered blockers
first (unverified/hallucinated code, wrong file, failing CI checks, broken
rendering), then required edits, then nits.
- Which bot PR(s) to close.
- A PR description following the repo convention:
- a short bullet summary of what changed
Rendered page:
Agent PR: <link(s)>
Original issue: # -
Style rules to bake in
- Model strings should be
gemini-flash-latest, gemini-pro-latest, or other
valid *-latest aliases in sample code rather than specific versioned model
strings, which increase the maintenance burden when new model versions are
released.
- Imports:
from google.adk.agents import Agent; MCP uses from google.adk.tools.mcp_tool import McpToolset. Agent variable is root_agent
(Python).
- No em dashes or verbose AI-generated content: Use a colon in
**term**: definition bullets; split prose into sentences otherwise.
- When referring to ADK, use "ADK", never "Google ADK" or "The ADK".
- Do not start a sentence with an inline-code word.
- Internal ADK-docs links are site-relative (e.g.
/sessions/memory/); external
links must resolve. Do not invent links.
- Verify all code samples against actual APIs and library code. The canonical
source repositories are listed in
docs/community/contributing-guide.md.
1---
2name: adk-bot-review
3description: Reviews adk-bot pull requests by validating technical correctness against source code, checking PR states and formatting, and following Google's developer documentation style and ADK docs conventions. Triggers on "review bot PR", "check bot changes", or "verify bot issue".
4metadata:
5 source: https://skillmd.com/skills/google/adk-bot-review
6---
7
8# Review changes proposed by adk-bot (adk-bot-review)
9
10This skill guides a rigorous review of adk-bot changes. It ensures documentation
11updates are technically accurate, appropriately sized, and follow ADK docs
12conventions, based on Google's developer documentation style.
13
14## Step 1: Verify and research the proposed adk-bot change
15
16- Check that the PR title briefly describes the topic being updated, not only
17 the issue.
18- Confirm changes are made directly in the `.md` files and no "do not merge"
19 status tags were prematurely removed.
20- Check the PR's mergeable state and CI status. Note git conflicts and failing
21 checks as findings to resolve or to fix in the consolidating PR.
22- The input is one adk-bot-authored PR, or occasionally a few. From the PR,
23 trace back to the issue and the specific item it addresses. Identify the item
24 from the PR title ("Update ADK doc according to issue #<N> - <item>") and
25 body. adk-bot often opens more than one PR for the same item. If multiple PRs
26 are provided, confirm they all address the same item and review them together
27 as one consolidation set. If they address different items, ask the user which
28 one to focus on before continuing.
29- Search closed issues and merged/rejected PRs across the repository for similar
30 topics. Ensure the bot is not re-introducing changes, APIs, or stylistic
31 choices that human maintainers have previously debated and rejected.
32- Summarize the item's intended change and stated reasoning, and carry that
33 intent into the technical validation in the next steps.
34
35## Step 2: Assess update criteria and architecture
36
37- Prioritize smaller, surgical updates over comprehensive overhauls unless the
38 existing docs are entirely unclear.
39- Verify that the update provides a useful learning experience and is actionable
40 for a developer.
41- Ensure the content is placed appropriately within the ADK docs information
42 architecture.
43- Confirm the update length and prioritization are appropriate for the specific
44 code change (check if it is already covered by existing docs or API
45 references).
46
47## Step 3: Validate the change against source and intent
48
49- **Never assume an AI agent's code snippet is correct.**
50- Cross-reference all code examples against the
51 `https://github.com/google/adk-python` repository.
52- Verify the information against relevant pull requests and actual ADK code in
53 the `https://github.com/google/adk-python` repo.
54- Confirm the change actually implements what the linked issue and adk-bot PR
55 set out to do, and resolves the issue item it references.
56- Flag any part of the change that drifts from that stated intent, or any part
57 of the intent the change leaves unaddressed.
58
59## Step 4: Check quality and style
60
61### Headings
62
63- Maintain a logical h1, h2, h3 hierarchy without empty headings (stacking
64 headers).
65- Do not number headings (Use `## This heading`, not `## 1. This heading`).
66- Use imperative titles (e.g., "Build agents", not "Building agents").
67- Do not use command names in headings; call out the task to be done.
68
69### Language
70
71- Follow Google's developer documentation style
72 (https://developers.google.com/style) as the basis for conventions; consult it
73 for anything not covered here.
74- Use active voice phrasing (e.g., "The system does X", not "X is done").
75- Never use the word "this" without a noun object (e.g., "This function is
76 used...", not "This is used...").
77
78### Code snippets and formatting
79
80- **Enforce an 80-character line length limit** for general Markdown text
81 (excluding long URLs, unbreakable code blocks, or tables).
82- Check for rendering errors caused by spaces before backticks (```).
83- Use the `!!! warning/tip/note` mkdocs-material admonition format for notes and
84 warnings instead of quote formats (`>`).
85- Do not use ALL CAPS except for code syntax; use bold or italics for emphasis.
86
87## Step 5: Report findings and decide the recommendation
88
89First, summarize the findings from the verification steps above, ordered
90blockers first, then required edits, then nits. Then choose one outcome below,
91justified by those findings:
92
93- **Close the bot PR(s).** (sometimes) The change is wrong, outdated, targets a
94 deprecated or unreleased API, or is already covered by live docs or a merged
95 PR. Record the reason and link the superseding doc or PR.
96- **Approve as-is** (rare). The bot PR(s) are correct, well-placed, and need no
97 edits.
98- **Edit in place, then approve** (sometimes). The existing branch is usable but
99 needs conflict resolution, corrections, consolidation, copyedits, or
100 relocation.
101- **Open a new consolidating PR** (most common). Rework the change across the
102 1-3 bot PRs into one PR that fixes code errors and hallucinations, edits for
103 quality, and places the content in the correct file. Then close the superseded
104 bot PR(s).
105
106Also confirm the change targets the correct file (files may have moved or been
107restructured, or the edit may belong on a different page).
108
109## Step 6: Produce an action plan
110
111Output the concrete next actions for the chosen recommendation:
112
113- The specific local edits needed: file paths, what to change, code fixes,
114 consolidation of the 1-3 bot PRs, and correct placement.
115- A short list of the verification findings that justify them, ordered blockers
116 first (unverified/hallucinated code, wrong file, failing CI checks, broken
117 rendering), then required edits, then nits.
118- Which bot PR(s) to close.
119- A PR description following the repo convention:
120 - a short bullet summary of what changed
121 - `Rendered page:` <preview link>
122 - `Agent PR:` <link(s)>
123 - `Original issue:` #<N> - <item>
124
125## Style rules to bake in
126
127- Model strings should be `gemini-flash-latest`, `gemini-pro-latest`, or other
128 valid `*-latest` aliases in sample code rather than specific versioned model
129 strings, which increase the maintenance burden when new model versions are
130 released.
131- Imports: `from google.adk.agents import Agent`; MCP uses `from
132 google.adk.tools.mcp_tool import McpToolset`. Agent variable is `root_agent`
133 (Python).
134- No em dashes or verbose AI-generated content: Use a colon in `**term**:
135 definition` bullets; split prose into sentences otherwise.
136- When referring to ADK, use "ADK", never "Google ADK" or "The ADK".
137- Do not start a sentence with an inline-code word.
138- Internal ADK-docs links are site-relative (e.g. `/sessions/memory/`); external
139 links must resolve. Do not invent links.
140- Verify all code samples against actual APIs and library code. The canonical
141 source repositories are listed in `docs/community/contributing-guide.md`.