adk-verify-snippets
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 report with per-snippet coverage. Use when the user asks to verify, test, or validate the code samples in a README, a guide, or a documentation page; wants to know which snippets in a Markdown file are broken or out of date; or asks for a snippet verification report. Don't use for running the project's test suite (run pytest directly), for checking code style or formatting (use `adk-style`), or for authoring a new runnable sample agent (use `adk-sample-creator`).
How do I install this agent skill?
npx skills add https://github.com/google/adk-python --skill adk-verify-snippetsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill includes several security considerations, such as command execution and dynamic module loading, which are used to verify and test code snippets in Markdown files. These operations are essential for the skill's primary purpose of code verification and are implemented with safety measures like process isolation and temporary file management.
- Socketwarn
2 alerts: gptSecurity
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
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
-
An ADK development environment — run from the repository root with the
uvvirtual environment active (see theadk-setupskill). -
coverage, optional. It is not a declared project dependency, so install it explicitly; without it the Coverage column shows—.uv pip install coverage -
A Gemini API key, needed only for snippets that build an
Agent,App, orWorkflow— 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, soGEMINI_API_KEYwins.
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.
How each snippet is classified
Runnable — has a module-level ADK component
If the snippet assigns a Workflow, Agent, or App to a module-level
variable, the harness executes it against the Gemini API.
- The variable name does not matter; the harness scans
vars(module). - Precedence is
Workflow, then rootAgent, thenApp. AWorkflowanywhere in the snippet wins over any agent in it. - The root agent is the first agent that appears in no other agent's
sub_agents, so multi-agent snippets resolve correctly whatever order the agents are defined in. - An
Appmust have been constructed with aroot_agentor the snippet fails to load. - The prompt sent is
"Test input topic". Override it by defining a module-leveltest_inputstring in the snippet.
Load-only — no ADK component
The harness confirms the snippet compiles and imports, and makes no API call.
The report shows ➖ NO ADK COMPONENT.
Skipped — annotated with ignore
Put <!-- verify-snippets: ignore --> alone on a line immediately before the
opening ```python fence to exclude a block. Use it for pseudo-code,
illustrative fragments, and snippets that need external setup. The report shows
⏭️ SKIPPED.
<!-- verify-snippets: ignore -->
```python
# pseudo-code — not runnable as-is
my_agent = Agent(model="gemini-ultra-hypothetical", ...)
```
Limitations that make correct snippets report as broken
Annotate with <!-- verify-snippets: ignore --> instead of editing the doc to
work around any of these.
- No shared state between snippets. Each snippet runs in a fresh
subprocess, so one that relies on an import or variable from an earlier
block fails with
NameErrororImportError. - 120-second timeout per snippet, after which the process is killed and the snippet reports as a run failure.
- Annotation placement. The annotation applies to the next
```pythonfence. Blank lines between the two are fine; any prose line or heading between them cancels it. - A bare
```closes the block. The parser closes a Python block at the first fence carrying no language tag, so a bare fence used as content inside a snippet truncates it. A tagged fence (for example```bash) is kept as literal content and is safe. - Module-level
asyncio.run()executes while the snippet loads, so an error inside it reports as a load failure. Snippets should keep top-level async calls behindif __name__ == "__main__":.
Reporting back to the user
Read the generated report and copy the Executive Summary table across exactly as
written — same six columns, same order, nothing renamed or dropped:
Snippet | Preceding Heading | Load Phase | Run Phase | Coverage | Details.
Present it and stop.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/google/adk-python/adk-verify-snippets">View adk-verify-snippets on skillZs</a>