adk-verify-snippets

Verify Markdown Snippets

Extracts every ```python block from a Markdown file, runs each one in its own subprocess via the bundled run.py harness, and writes a report covering load status, run status, and line coverage per snippet.

Read-only contract

Verifying a doc must never change the doc. Do not create, modify, or delete any file in the repository — including the Markdown being verified, its code blocks, and this SKILL.md. Report the failures; do not fix them and do not offer patches.

The script performs the only two writes that happen: temporary .py files in a system temp directory outside the repository (removed when it exits), and the report beside the source Markdown file.

Prerequisites

1. An ADK development environment — run from the repository root with the uv virtual environment active (see the adk-setup skill).

2. coverage, optional. It is not a declared project dependency, so install it explicitly; without it the Coverage column shows —.

   uv pip install coverage
   

3. A Gemini API key, needed only for snippets that build an Agent, App, or Workflow — those are executed against the live API.

   export GEMINI_API_KEY="{your_key}"
   # or
   export GOOGLE_API_KEY="{your_key}"
   

   If both are set the harness drops GOOGLE_API_KEY, so GEMINI_API_KEY wins.

Usage

uv run --no-sync python .agents/skills/adk-verify-snippets/scripts/verify_md.py {path_to_markdown_file}

The script prints per-snippet progress, then writes the report beside the source file and prints its full path.

The report filename is the source file's stem lowercased with everything except [a-z0-9_] stripped, plus _REPORT.md. Workflow-Guide.md therefore produces workflowguide_REPORT.md, not Workflow-Guide_REPORT.md — read the path the script prints rather than reconstructing it.

The report contains an Executive Summary table with one row per snippet, then a detailed section per snippet holding the code block, the execution logs (stdout plus stderr/traceback), and the coverage output.