How to use the Align Recipe pyproject.toml agent skill

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder containing a SKILL.md file and any supporting scripts. When it is installed, an AI agent that supports skills can load the instructions and run the scripts when your request matches the skill's description.

This skill targets a Python recipe's pyproject.toml, and sometimes its manifest.yaml description. It checks eight rules that the repo's CI enforces, such as removing local ruff config, making requires-python accept Python 3.11, setting the project name to match the folder, and confirming a [build-system] block exists. Some rules are fixed automatically and others are only reported, because they need a human decision.

• Works on recipes under core/, contrib/ or plugins/ in google/adk-recipes.
• Dry-run mode reports problems without changing any file.
• Apply mode rewrites only the recipe's own files and tries to keep comments intact.
• It does not migrate a recipe to a new google-adk major version; that is a code change the skill is not designed to make.

Install the align-recipe-pyproject skill

Download the skill ZIP from this page and unzip it. To make the skill available to Claude Code for all of your projects, place the unzipped folder in ~/.claude/skills/. To limit it to a single project, place it in that project's .claude/skills/ folder instead.

If you use the Claude apps, you can upload the ZIP instead. Go to Settings, then Capabilities, then Skills, and add the skill there.

• Personal install: ~/.claude/skills/align-recipe-pyproject
• Project install: <your-project>/.claude/skills/align-recipe-pyproject
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP.

Install the Python libraries the scripts need

The script scripts/align_pyproject.py needs a Python interpreter and two libraries: tomlkit, which edits TOML while preserving comments, and ruamel.yaml, which does the same for YAML. The source does not give a specific install command, so use whatever method your environment already uses for Python packages.

• A Python interpreter to run scripts/align_pyproject.py.
• The tomlkit library (comment-preserving TOML edits).
• The ruamel.yaml library (comment-preserving YAML edits, used only when the description is synced to manifest.yaml).

How to trigger the skill with a natural request

You do not need to name a command. The skill's description lists phrases that match it, so ask the agent in plain language and give it the recipe directory. The agent will ask for the directory if you leave it out, because it is not supposed to guess.

Recipe roots live under core/python/<name>/, contrib/python/<name>/, or plugins/<vertical>/<solution>/. If you say nothing about applying changes, the agent runs a dry run first and shows you what would change.

• "Check what needs changing in the pyproject.toml of core/python/my-recipe."
• "Align the recipe's pyproject.toml with the repo standard before I open a PR."
• "Fix pyproject to match the repo standard for contrib/python/my-recipe, just do it."
• "Clean up plugins/retail/product-search before submitting."

Read and act on the report

The script checks every rule, but the agent only shows the ones that need attention. If nothing needs attention, you get a single positive line. If something does, you see only the failing checks.

Some results need your input. If description-matches-manifest returns needs_input, the agent shows the two descriptions side by side and asks you to choose one. If requires-python would still exclude Python 3.11 after the rewrite, the skill refuses to apply and returns needs_input, usually meaning you should relax a ceiling or raise the question with the maintainers about CI's pinned interpreter.

• no-local-ruff-config and project-name-matches-folder: auto-fixed in apply mode.
• python-version-floor: auto-rewritten when the result still accepts 3.11; otherwise needs_input.
• build-system-present, stale-python-version-refs and runnability-test-in-testpaths: report only, fixed by a human.
• default-pypi-index: appended when the block is missing; reported when a default index points elsewhere.

Safety notes: scripts, files and network

This skill runs a script, so review it before installing, as you would any code you run. According to the source, the skill does not use the network. It only modifies files inside the recipe directory. The workflow file, the root pyproject.toml and other recipes are not touched.

Files are rewritten only if at least one auto-fix actually ran. Otherwise the bytes on disk stay the same, so a dry run is safe to use at any time.

• Runs scripts: yes (scripts/align_pyproject.py).
• Uses network: no.
• Writes only inside the recipe directory.
• Start with a dry run and review the report before applying.

Tips for getting clean results

Run the dry run before every pull request, and again after any manual edits. Keep the rules in mind: the skill is designed for this repo's conventions, including the pinned Python 3.11 floor and the required test file. Outside those conventions the rules may be wrong, so do not use it for unrelated projects.

Expect some items to stay open. Editorial decisions such as the build backend, the wording of stale version references and the testpaths setting are left to you.

• Pass the exact recipe folder, not the repo root.
• Check the rest of the report for report-only items after an apply run.
• If a rule seems wrong for your recipe, ask the maintainers rather than overriding the check.