integration-review

# ADK Integration Page Reviewer (integration-review) This skill guides a rigorous review of integration documentation pages in the [adk-docs](https://github.com/google/adk-docs) repository. Integration pages live under `docs/integrations/` and document third-party tools, plugins, observability platforms, data stores, MCP servers, connectors, and other extensions to ADK agents. The authoritative sources of truth for this review are: 1. The repository's `CONTRIBUTING.md` (see the "Integrations" section and its acceptance criteria). 2. The **existing shipping integration pages**, which are the real template. Always open and compare against peers of the same category: - MCP tools: `docs/integrations/github.md`, `docs/integrations/notion.md` - Observability: `docs/integrations/phoenix.md`, `docs/integrations/arize-ax.md` - Plugins: `docs/integrations/daytona.md`, `docs/integrations/goodmem.md` 3. The catalog rendering logic in `scripts/integrations.py`. > [!NOTE] > Read this skill and follow its steps whenever asked to review an integration > page or an integration PR. ## Review workflow ### Step 1: Gather the change - If reviewing a PR, use `gh` to pull it and read the **full cumulative diff**, not a single commit: `gh pr view <n> --repo google/adk-docs` and `gh pr diff <n> --repo google/adk-docs`. A stale `mkdocs.yml` entry or asset can hide in files that only show in the full diff. - Check whether "Allow edits from maintainers" is enabled (`maintainerCanModify`) so fixes can be pushed directly if requested later. - Confirm the CLA is signed (the `google-cla` bot). An unsigned CLA is a 🔴 Critical finding and blocks merge until signed. - If reviewing a local file, run `git status` and `git diff` to see the change. ### Step 2: Find and read similar pages Find 5 or more similar pages and read them in full. Identify candidates in one pass by scanning `catalog_tags` (`grep catalog_tags docs/integrations/*.md`) and matching the tag under review (e.g. `mcp`, `observability`); widen the set with other signals such as product domain, structural template, and language support (they need not all be the exact same category). Reading the full pages, not just frontmatter, grounds the review in live examples and repo conventions rather than inferring everything from the templates in this skill. ### Step 3: Run the checklist Work through every dimension in the review checklist below. ### Step 4: Verify code, packages, and links Do real verification, not a surface read (see "Deep verification"). ### Step 5: Research developer value and maturity Gather objective evidence about the project's maturity, adoption, and whether it genuinely integrates with ADK (see "Developer value and maturity"). Base the assessment on verifiable facts, not impressions or the PR's own marketing. ### Step 6: Report, decide, and stop Produce the prioritized report (see "Report format"), then emit the three follow-on outputs in "Review decision and response": a top-level review response, a decision (approve, request changes, or close PR), and draft line-anchored comments. Do **not** edit files, post to GitHub, or offer to fix issues by default. Stop and wait for an explicit instruction to fix. ### Step 7 (only if asked): Apply fixes If, and only if, the user explicitly asks you to fix findings: apply precise edits, keep the contributor's wording where possible, fix only ADK-owned issues unless told otherwise (leave vendor-SDK bugs for the author), and verify with `mkdocs serve` where practical. ## Review checklist ### 1. Frontmatter (catalog metadata) Every page starts with exactly these four YAML fields: ```yaml --- catalog_title: <Display Name> catalog_description: <short verb-led phrase> catalog_icon: /integrations/assets/<slug>.png catalog_tags: ["<tag>", "<tag>"] --- ``` - **`catalog_title`**: the human-readable product name shown on the card. - **`catalog_description`**: short, verb-led, roughly 45 to 75 characters (about 6 to 11 words). Flag anything over ~80 characters as likely to wrap awkwardly on a card. It must **not repeat the product name** (the title already shows it). No verbose lists of technologies; describe what the integration does. No overclaims. - **`catalog_icon`**: `/integrations/assets/<slug>.png` (or `.svg` or `.jpg`). The referenced asset file must actually exist in `docs/integrations/assets/` and be a real image. - **`catalog_tags`**: a JSON array of lowercase tags. **Use only tags that already exist in the catalog; never invent a new one.** Tags combine (e.g. `["data", "mcp"]`). Any page that uses MCP in its body must carry the `mcp` tag. Enumerate the valid tags in one pass with `grep catalog_tags docs/integrations/*.md`. ### 2. Structure and required elements - **H1** follows `# <Product> <type> for ADK`, where `<type>` matches the category (e.g. `# GitHub MCP tool for ADK`, `# AgentOps observability for ADK`, `# Daytona plugin for ADK`). - **Language support tag** immediately after the H1, as HTML (not bold markdown): ```html <div class="language-support-tag"> <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python</span><span class="lst-typescript">TypeScript</span> </div> ``` - Drop the TypeScript span for Python-only integrations. - **Spans must be on a single line.** No multi-line span splitting. - Using plain bold markdown instead of this div is a defect. - **Section order** should match one of the three category templates: - **MCP tool**: `## Use cases` -> `## Prerequisites` -> `## Use with agent` (tabbed Python / TypeScript) -> `## Available tools` -> `## Configuration` (optional) -> `## Additional resources` - **Observability**: intro -> `## Overview` -> `## Installation` -> `## Setup` -> `## Observe` -> `## Support and Resources` - **Plugin**: `## Use cases` -> `## Prerequisites` -> `## Installation` -> `## Use with agent` -> `## Available tools` -> `## Configuration` (optional) -> `## Additional resources` - **Section names**: prefer `## Use with agent` over `## Usage` or verbose `## Example: ...` headings. Prefer `## Installation` for the install step. Prefer specific names (`Available tools`, `Available methods`) over a bare `## API`. - Flag **thin or over-fragmented sections** (many H2s that are each a single code block); recommend consolidating into a `## Setup` with numbered steps. A single copy-pasteable end-to-end code block is acceptable and often better for the user than a split Setup/Observe. ### 3. Code correctness - 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. - Canonical imports: `from google.adk.agents import Agent` (short form), and for MCP `from google.adk.tools.mcp_tool import McpToolset`. - Agent variable is `root_agent` (Python) / `rootAgent` (TypeScript); TypeScript files end with `export { rootAgent };`. - MCP examples should use MkDocs Material tabs (`=== "Python"` / `=== "TypeScript"`, with nested sub-tabs like `=== "Local MCP Server"` where relevant). Admonitions inside tabs use 8-space indentation. - Code must be complete and runnable, and must match the real ADK and vendor API (see "Deep verification"). ### 4. Style and typography - **Little to no use of em dashes or other overly used AI-generated content.** In `**term** — definition` bullets replace the em dash with a colon; in prose split into two sentences or use commas / parentheses. On third-party-owned content, flag but leave to the author; on anything you edit, remove them. - Agent Development Kit should be referred to as "ADK", never "Google ADK" or "The ADK", in prose and code comments. - **Do not start a sentence with an inline-code word.** Rephrase (e.g. "The `package-name` library adds..." rather than "`package-name` adds..."). - **No marketing bias.** These are the ADK docs: remove copy that reads like marketing and makes sweeping claims. ### 5. Links and assets - Internal ADK-docs links should be **site-relative** (e.g. `/sessions/memory/`), not absolute `https://adk.dev/...` or legacy `https://google.github.io/...`. Relative links resolve in PR previews, survive domain changes, and are caught by the link checker. This is a nit on vendor-owned pages but generally fix it. - Image references from a page in `docs/integrations/` should use `assets/<img>.png`, not `../assets/...` unless the image genuinely lives in `docs/assets/`. Trace the path against what peer pages actually do; do not theorize. - External links must resolve (HTTP 200). Hunt for **hallucinated links** to nonexistent repos, samples, or docs. When you find one, suggest removing it or ask the author for the real target rather than assuming. ### 6. Catalog mechanics - Integration pages are **auto-discovered** by `render_catalog('integrations/*.md')` in `docs/integrations/index.md`. **No `mkdocs.yml` nav entry is needed**; adding one is an error. - Cards sort **alphabetically by filename**. Choose filenames that sort sensibly and **drop package-name prefixes** (e.g. `mongodb.md`, not `mongodb-mcp-server.md`; avoid `adk-`-prefixed names that float to the top). - Add a **redirect** in `mkdocs.yml` only when a page is renamed or moved from an existing URL. Point redirects directly at the final destination; **never chain** them. - Adding a new integration requires only the `.md` file with correct frontmatter plus the icon asset in `assets/`. ## Deep verification Verify all code samples against actual APIs and library code. The canonical source repositories are listed in `docs/community/contributing-guide.md`. - **Package reality**: confirm the PyPI (or npm) package exists and that any stated version and Python requirement match the prose. - **ADK API**: verify every ADK symbol and pattern used in the code samples against the canonical source repositories (listed in `docs/community/contributing-guide.md`) for the relevant language SDK (e.g. `Runner`, `run_async`, `create_session`, `append_event`, `save_artifact`, session/artifact service URIs, `adk web` / `adk run` CLI flags, genai types). Do not assume a local checkout: fetch the source with `gh` or `git` (or use a local clone if one exists), and check the **released version** the docs target rather than a main branch that may be ahead of or behind the release. Note the version you verified against, and flag mismatches. - **Vendor SDK**: verify the vendor's classes, methods, and arguments against the vendor SDK source or docs. - **Ownership of bugs**: distinguish ADK-owned issues from vendor-SDK-owned issues (flag and leave for the author). - **Test by hand** when practical: run the example with a real ADK agent, or at minimum `mkdocs serve` to confirm the card renders and the icon loads. ## Developer value and maturity Integration pages are official ADK documentation, so an integration must earn its place by offering real, demonstrated value to developers. The goal here is to research and determine if the integration is for an established platform with genuine utility, a track record, and real adoption vs. for a brand-new or low-adoption project with little substance behind it. Do the research and report the evidence; do not infer value from the PR's own description or marketing. Gather objective, verifiable signals and cite each with a source: - **Package reality and age**: confirm a real published package exists. Query the PyPI JSON API (`https://pypi.org/pypi/<pkg>/json`) or the npm registry (`https://registry.npmjs.org/<pkg>`) for the first-release date, number of releases, and latest version, and check download counts (pypistats or the npm downloads API). A missing package, or one published the same day as the PR, is a strong negative signal. - **Source repository signals**: use `gh api repos/<owner>/<repo>` to read `created_at`, stars, forks, contributor count, commit count, releases, license, and last-commit date. A repository created within the last few weeks, with a handful of commits, a single author, or no license is a negative signal. - **Adoption and track record**: gauge real usage from verifiable signals: package download counts (see above), repository stars, forks, and dependent projects, plus any documented production users, case studies, or independent third-party coverage found via web search, and how long the product has operated. Broad, verifiable usage is a positive signal; its absence across every source is a negative one. - **Genuine ADK integration**: confirm the project actually uses ADK extension points (callbacks, plugins, toolsets, MCP) rather than patching a dependency such as `google-genai`, or wrapping a REST API with plain functions and presenting that as an ADK integration (cross-check against "Deep verification" and the scope trigger below). - **Website liveness**: confirm the linked site is a real, live product site, not a parked domain or placeholder. **Weighing the evidence.** A new project is not automatically low-value: an established vendor shipping a brand-new package, or a project with clear utility plus a real source repository, tests, and a license, is credible and should not be treated as a value concern. Genuine concern is the accumulation of negative signals: brand-new and unpublished, no adoption or track record, no source or license, no real ADK extension use, and claims the page makes that your verification could not confirm. When the evidence is mixed, give the contributor the benefit of the doubt, lay out the facts, and recommend closing as a judgment call for the maintainer rather than asserting a verdict. Keep the write-up neutral and factual. ## Acceptance and rejection **Rejection triggers (close the PR):** - Documents unreleased, unmerged, or fabricated APIs. We cannot document functionality that does not exist yet. - Duplicates a page that already exists (vendor-specific features belong in the vendor's own docs, with at most a one-line link from the existing ADK page). - Code that does not match the real ADK or vendor API. - Broken or hallucinated links. - Unsigned CLA. - Insufficient developer value or maturity: a brand-new repository, an unpublished or same-day package, no adoption or track record, or no source repository or license. Support this with the evidence from "Developer value and maturity" and treat it as a maintainer judgment call, not an automatic verdict. - Misrepresented integration: manual code that ignores ADK's extension points while claiming to integrate with ADK. - Out of scope: a generic "wrap a REST API as a function tool" page with no ADK-specific artifact. The ADK docs are not an API directory. - Spam signals (no connection to either project, no ADK-specific functionality, contribution-graph padding, very new integrations with low usage). **A good page:** complete four-field frontmatter with a short verb-led description and a valid existing tag; correct H1 and single-line language-support div; the right category template with specific, non-fragmented sections; complete, runnable, hand-tested code using `gemini-flash-latest` (or a valid `*-latest` alias) and canonical imports (plus Python and TypeScript tabs for MCP); relative internal links, working external links, valid icon asset; no verbose AI-generated language, correct use when referring to "ADK", no overclaims or marketing bias; auto-discovered with no nav edits. ## Report format Produce a Markdown report categorized by priority, each finding with an exact `file:line` and context. Derive line numbers from the file under review (the local page, or the PR via `gh pr diff` or a fetched copy) using a line-numbered read, `grep -n`, or the diff's hunk headers; never approximate (no `~`). **Always list all four tiers in order and print `None` under any tier with no findings**, so the absence of Critical issues is stated, not merely implied. A finding you consider genuinely take-or-leave belongs under 🔵 **Nits**; keep 🔴, 🟠, and 🟡 reserved for items that must be fixed before merge. - 🔴 **Critical**: fabricated/unreleased APIs, non-working code, broken or hallucinated links, unsigned CLA, wrong destination directory, duplicate page. - 🟠 **Quality**: structure or template mismatch, missing/misnamed sections, overclaims, incorrect vendor/ADK API details. - 🟡 **Style**: verbose AI-generated language, improper usage of "ADK", inline-code sentence starts, word-choice, model string, imports, description length, marketing tone. - 🔵 **Nits**: tag comma spacing, absolute-vs-relative ADK links on vendor-owned pages, image size, heading-capitalization variants. Every finding you list here must produce at least one line-anchored comment in output 3 (a finding that spans multiple locations gets one comment per location); the report and the comments must cover the same items. After the tiers, add a short **Developer value and maturity** narrative paragraph: summarize the evidence gathered in the "Research developer value and maturity" step (package age, adoption and track record, repository signals, genuine ADK extension use), cite each signal with a source link, and end with a provisional lean. When the research concludes value or maturity is insufficient, also record it as a 🔴 **Critical** finding tagged "judgment call" so it stays consistent with the approve gate. After the prioritized report, produce the outputs in "Review decision and response" below. ## Review decision and response After the prioritized report, emit these three outputs in order. They map onto a GitHub PR review (review body + decision + inline comments). Everything here is a **draft**: do not post to GitHub, do not run `gh`, and do not edit files unless the user explicitly asks. ### 1. Top-level review response A short review body (a few sentences), suitable to paste as the GitHub PR review summary. State what the integration is, the overall assessment, the headline reasons, and what needs to happen next. Use the "Feedback tone" below: short, direct, diplomatic, and actionable. For a Close PR outcome, adapt the matching snippet from "Decline response templates" and fill in the specific evidence. ### 2. Decision Choose exactly one, justified by citing the specific findings from the report