Guide · Agent skill
How to use the Generate Python Runnability Test agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Generate Python Runnability Test skill lets an AI agent write a small test file, tests/test_runnability.py, for a Python recipe in the google/adk-recipes repository. The generated test checks that the recipe's agent module imports and defines root_agent (and app, if the module defines one). This guide explains what the skill does, how to install it, how to ask for it in plain language, and what to check before you let it write files.
Generate Python Runnability Testgoogle/adk-recipes · Apache-2.0 Download the skill Quick start
- 1Download and unzip. Download the skill ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
- 2Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.
- 3Make sure Python is ready. Install Python and the packages the recipe's own agent code uses, since the generated test imports that code. Ruff is optional.
- 4Ask for the test. Tell the agent which recipe to work on, such as core/python/<name>/, and ask it to add a runnability test.
- 5Review the dry-run. Read the report and preview. Check the detected side effects, env vars and import_support value before approving.
- 6Apply the change. Ask the agent to apply the result. It writes tests/test_runnability.py and, if needed, tests/conftest.py.
- 7Run the recipe's tests. Run the recipe's tests to confirm the module imports and root_agent is defined.
What the skill makes the agent do
Agent skills are instruction folders that an agent such as Claude can load when a request matches them. This skill is for one specific job: adding the runnability test that every Python recipe is expected to ship.
The skill reads the recipe's agent code without running it. It looks for import-time side effects, such as vertexai.init or google.auth.default calls, and for environment variables the code reads, such as GOOGLE_CLOUD_PROJECT and INTEGRATION_TEST. It then adds only the mocks and environment defaults the recipe needs for the import to succeed. It can also add a tests/conftest.py so the recipe's code is importable.
- Locates agent.py in the recipe, skipping folders such as .venv, build, dist and tests.
- Checks whether root_agent and app are defined at module level.
- Writes a minimal test when no side effects are found, or a guarded test with patches and env defaults when they are.
- Previews the result, or writes it to disk when you ask it to apply.
Install the skill
You can install the skill in two ways. Download the ZIP from this page and unzip it into one of the following folders, depending on where you want it available.
For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Ask for the test in plain language
The skill loads when your request matches its description. You do not need to name a script. Requests that match the skill include asking to add a runnability test, generate test_runnability.py, create a smoke test for the recipe, or fix the missing-required-file failure from python-validate-recipe.yml.
If you do not give a recipe directory, the agent will ask for one. Recipe roots live under core/python/<name>/, contrib/python/<name>/, or plugins/<vertical>/<solution>/.
- Add a runnability test to core/python/my-recipe.
- Generate test_runnability.py for the recipe in contrib/python/my-recipe.
- Fix the missing-required-file failure from python-validate-recipe.yml for this plugin.
Preview first, then apply
The agent starts in dry-run mode unless you explicitly say to apply or write the file. Dry-run produces a report and a preview of what would be written, so you can review it before anything lands on disk.
Existing tests are protected. The skill will not overwrite tests/test_runnability.py unless you explicitly pass the overwrite option. An existing tests/conftest.py is never overwritten, even with that option.
- Dry-run: report and preview only, no files written.
- Apply: writes tests/test_runnability.py, and tests/conftest.py if it is needed.
- --agent-file: use this if the shallowest agent.py is not the one you want.
- --overwrite: required to replace an existing tests/test_runnability.py.
Understand import support and the conftest file
The generated test imports the recipe by module name, which only works if the recipe root is on the Python path. The skill checks this and reports an import_support value. If the recipe already provides a path through pyproject.toml, pytest settings or an existing conftest.py, it uses that. If none of these apply, it writes tests/conftest.py with a path shim.
If the generated conftest.py is created, the skill suggests adding a [build-system] to pyproject.toml as the better fix. Once you do that, you can delete the generated conftest.py.
- installable: pyproject.toml has a [build-system], so the package is importable.
- pythonpath-ini: pytest's pythonpath setting includes '.'.
- existing-conftest: a usable conftest.py already exists.
- generated-conftest: the skill wrote tests/conftest.py with a path shim.
Check the result
The skill says the generated file passes ruff check and ruff format --check under the root config. Ruff is optional for running the skill, but it is used to format the output when available.
After applying, run the test in the recipe as your project normally does. The test only proves that the module imports and defines the expected globals. It does not test business logic or agent behaviour.
- Confirm the test file exists at tests/test_runnability.py.
- Check whether a tests/conftest.py was added and why.
- Run the recipe's tests to confirm the import works.
What people use it for
- Fixing the missing runnability test failure in CI for an existing Python recipe in google/adk-recipes.
- Adding a basic import check to a new Python agent recipe so it matches repository conventions.
- Creating a smoke test for a vertical plugin under plugins/ that needs a path shim to import.
- Checking which env vars and import-time calls a recipe depends on before writing its test.
Frequently asked questions
What is the generate-python-runnability-test skill?
It is an agent skill that generates a small tests/test_runnability.py for a Python recipe in the google/adk-recipes repository. The test imports the recipe's agent module and checks that root_agent, and app if defined, exist. It does not test business logic.
How do I install the generate-python-runnability-test skill?
Download the ZIP from the page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.
What does the skill require?
It requires Python and the Python packages that the recipe's own agent code uses, because the generated test imports that code. Ruff is optional and is used to format output when it is available. The skill runs scripts but does not use the network.
Will the skill overwrite my existing tests?
Not by default. It refuses to replace an existing tests/test_runnability.py unless you explicitly pass the overwrite option. An existing tests/conftest.py is never overwritten, even with that option.
Does the skill run my recipe's code?
The skill reads the agent code without running it. It uses that reading to decide which mocks and environment variables the generated test needs.
Can this skill be used for recipes outside google/adk-recipes?
Not reliably. The skill assumes the google/adk-recipes layout and its CI check, so recipes outside that structure may not work as expected.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you maintain or add Python recipes in google/adk-recipes and need a consistent runnability test, especially to fix the missing-file CI failure. Pick something else if you need tests of agent behaviour or business logic, or if your project does not follow the google/adk-recipes layout.
Download the skill