Adk Verify Snippets

Verify Markdown Snippets Skill

This skill extracts all python ` blocks from a Markdown file, executes each

one in a process-isolated environment using the bundled run.py harness, and

generates a structured report covering load status, run status, and line

coverage.

> [!CAUTION] **STRICT READ-ONLY CONSTRAINT — READ THIS BEFORE DOING ANYTHING

> ELSE**

>

> This skill is read-only. The agent MUST NOT: - Modify any file in

> the repository (source, test, config, docs, or skill files — including this

> SKILL.md). - Delete any file in the repository. - Create any new file

> in the repository.

>

> The only two write operations permitted are: 1. Writing temporary .py

> snippet files to a system temp directory outside the repository. 2.

> Writing the final <filename>_REPORT.md into the **same directory as the

> source Markdown file**.

>

> If in doubt, do not write. Any other mutation is a violation of this skill's

> contract.

--------------------------------------------------------------------------------

🔧 Prerequisites

• ADK Python environment: Run from the repository root with the uv

virtual environment active.

• coverage package *(optional)*: Enables per-snippet coverage reporting.

Without it, coverage columns show —.

    uv pip install coverage

• Gemini API key: Required only for snippets that instantiate an Agent,

App, or Workflow (which make live Gemini API calls). Set one of:

    export GEMINI_API_KEY="your-key-here"
    # or
    export GOOGLE_API_KEY="your-key-here"

If both are set, GEMINI_API_KEY takes precedence.

--------------------------------------------------------------------------------

🛠️ Usage

uv run --no-sync python .agents/skills/adk-verify-snippets/scripts/verify_md.py <path_to_markdown_file.md>

The script prints progress for each snippet, then writes a report to

<filename>_REPORT.md in the same directory as the source file and prints

the full path on completion.

Report contents: :- Executive Summary table — one row per snippet:

preceding heading, Load phase status, Run phase status, coverage %, and error

detail.

• Detailed section — for each snippet: the extracted code block, full

execution logs (stdout + stderr/traceback), and the coverage report.

--------------------------------------------------------------------------------

📝 How Snippets Are Classified

Each python ` block falls into one of these categories:

1. Runnability Test (has a module-level ADK component)

If the snippet assigns a Workflow, Agent, or App to a **module-level

variable**, the runner executes it against the Gemini API.

• The variable name does not matter — the runner finds it automatically via

vars(module).

• For multi-agent snippets, the runner identifies the root agent by excluding

any agent that appears in another agent's sub_agents list.

• To use a custom test prompt instead of the default "Test input topic",

define a module-level test_input string in the snippet.

If no module-level ADK component is found, the run phase is skipped and the

report shows ➖ NO ADK COMPONENT.

2. Loadability-Only (no ADK component)

The runner verifies the snippet compiles and imports without error. No API call

is made.

3. Skipped (annotated with ignore)

Place <!-- verify-snippets: ignore --> immediately before the opening

python ` fence to exclude a block entirely. Use this for pseudo-code,

illustrative examples, or snippets that require external setup.

<!-- verify-snippets: ignore -->

pseudo-code — not runnable as-is

my_agent = Agent(model="gemini-ultra-hypothetical", ...)

The report shows these as ⏭️ SKIPPED.

--------------------------------------------------------------------------------

⚠️ Known Limitations

• No shared state between snippets: Each snippet runs in a fresh

subprocess with no imports or variables carried over from previous snippets.

A snippet that depends on code from an earlier block will fail with

NameError or ImportError. Make each snippet self-contained, or annotate

it with <!-- verify-snippets: ignore -->.

• 120-second timeout: Each snippet is killed after 120 seconds. Annotate

long-running or blocking snippets with <!-- verify-snippets: ignore -->.

• Ignore annotation placement: The <!-- verify-snippets: ignore -->

annotation applies to the next python ` fence encountered. Blank lines

between the annotation and the fence are tolerated, but any non-blank line

(prose or a heading) cancels the annotation.

• Bare ` closes the block: The parser closes a Python block on the

first bare line (no language tag). A bare appearing as

content inside a snippet (e.g. to demonstrate Markdown syntax) will

prematurely close the block. Annotate such snippets with

<!-- verify-snippets: ignore -->.

--------------------------------------------------------------------------------

⚠️ Behavioral Constraints (For AI Agents)

• Read-only: See the caution block at the top. The constraint is absolute.
• Report only, do not fix: The agent MUST NOT rewrite the source Markdown,

modify code blocks, or generate patches. Present the summary table to the

user and stop.

• Present the summary table verbatim: After the script completes, read the

generated _REPORT.md and copy the Executive Summary table to the user

exactly as written — same six columns, same order, no renaming or

dropping: `Snippet | Preceding Heading | Load Phase | Run Phase | Coverage |

Details`