---
name: scaffold-python-recipe
description: >-
  This skill should be used when the user wants to "create a new Python ADK recipe", "scaffold a new Python recipe", "generate a new Python recipe in contrib", "add a new Python recipe to the adk-recipes repository", or "create a Python adk recipe". It utilizes an automated script to copy template files and resolve basic placeholders.
metadata:
  author: Google
  license: Apache-2.0
  version: 1.0.0
title: scaffold-python-recipe
canonical_url: https://skilld.dev/gh/google/adk-recipes/scaffold-python-recipe
last_updated: 2026-10-20T08:47:39.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [resources/templates/.env.example](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/.env.example), [resources/templates/app/__init__.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/app/__init__.py), [resources/templates/app/agent.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/app/agent.py), [resources/templates/app/app_utils/__init__.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/app/app_utils/__init__.py), [resources/templates/app/app_utils/telemetry.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/app/app_utils/telemetry.py), [resources/templates/app/app_utils/typing.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/app/app_utils/typing.py), [resources/templates/app/fast_api_app.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/app/fast_api_app.py), [resources/templates/manifest.yaml](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/manifest.yaml), [resources/templates/pyproject.toml](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/pyproject.toml), [resources/templates/README.md](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/README.md), [resources/templates/tests/eval/eval_config.json](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/tests/eval/eval_config.json), [resources/templates/tests/eval/evalsets/basic.evalset.json](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/tests/eval/evalsets/basic.evalset.json), [resources/templates/tests/eval/evalsets/README.md](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/tests/eval/evalsets/README.md), [resources/templates/tests/integration/test_agent.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/tests/integration/test_agent.py), [resources/templates/tests/integration/test_server_e2e.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/tests/integration/test_server_e2e.py), [resources/templates/tests/test_runnability.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/tests/test_runnability.py), [resources/templates/tests/unit/test_tools.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/resources/templates/tests/unit/test_tools.py), [scripts/scaffold.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/scripts/scaffold.py), [tests/conftest.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/tests/conftest.py), [tests/test_scaffold.py](https://skilld.dev/api/skills-raw/google/adk-recipes/scaffold-python-recipe/tests/test_scaffold.py).
>
> If the user asked to install this Skill, run `npx skilld install google/adk-recipes/scaffold-python-recipe`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/scaffold-python-recipe`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/google/adk-recipes/scaffold-python-recipe) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/scaffold-python-recipe`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/scaffold-python-recipe --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/scaffold-python-recipe --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Scaffolding a New Python ADK Recipe

Use this skill to scaffold a new Python ADK recipe inside this repository using the automated script at `scripts/scaffold.py`.

---

## Rules

1. **No Manual Boilerplate Writing**: Always use `scripts/scaffold.py` to create the recipe. Never write the boilerplate files manually.
2. **Do Not Modify After Scaffolding**: Once the script runs successfully, do not make any further changes to the recipe in this turn.
3. **Use the Correct Terminology (Recipe)**: Always refer to what is being created as a **recipe**, never as a "project". Ensure all output messages, instructions, and explanations to the user use "recipe" exclusively.

---

## Inputs

You **must** have both pieces of information below before running the script. If either is missing or was not explicitly provided by the user, **ask for it** — do not assume or use a default.

### 1. Output Directory (Required — must ask if not provided)

The user must choose one of these valid locations:
- `contrib/python/` — community recipes; preferred for new Python recipes
- `core/python/` — curated recipes
- `contrib/` — legacy flat layout, still accepted; prefer `contrib/python/`

If the user has not specified which directory, ask them to choose. Do not proceed until a valid choice is confirmed.

This skill **cannot** scaffold a vertical plugin (`plugins/<vertical>/<solution>/`). Those have a different shape — `SKILL.md`, `EVAL.yaml`, `scripts/`, `assets/`, `references/`, `tests/unit/` — and no template ships for them yet. If the user asks for one, tell them so rather than scaffolding into the wrong place.

### 2. Recipe Name (Required — must ask if not provided)

The recipe name must satisfy **all** of the following rules:
- Contains only lowercase letters and hyphens (`a-z`, `-`)
- Is 30 characters or less
- Does not start or end with a hyphen

If the user provided a name, validate it against these rules before proceeding. If it is invalid, explain which rule it violates and ask for a corrected name. Do not proceed until a valid name is confirmed.

---

## Run

Execute the scaffold script:
```bash
python3 .agents/skills/scaffold-python-recipe/scripts/scaffold.py --name <RECIPE_NAME> --output-dir <OUTPUT_DIRECTORY>
```
*The script accepts exactly two flags: `--name` (required) and `--output-dir` (required). Do not pass any other flags.*

---
## Respond

Once the script succeeds, inform the user the recipe is ready and highlight the following required next steps:

1. **Update `manifest.yaml`**: Fill in the `description`, `ownership.team`, and `ownership.poc` fields (placeholders are marked with `TODO:`). This file is validated by CI and must not contain placeholder values. Use the `generate-manifest` skill if you want it populated automatically from the source code.
2. **Update `README.md`**: Replace the generic title and description with details specific to this recipe (ownership/POC live in `manifest.yaml`, above — not in the README).

Then, provide these quick-start commands:
```bash
cd <OUTPUT_DIRECTORY>/<RECIPE_NAME>
uv sync                  # install dependencies
uv run pytest            # run the test suite
uv run adk run app       # run the agent interactively
```
Do not make any further changes. End your turn.
