align-recipe-pyproject

Aligns a Python recipe's pyproject.toml with the repo's standards enforced by .github/workflows/python-validate-recipe.yml, plus one critical [build-system] presence check. Scope is pyproject.toml only — standalone ruff.toml / .ruff.toml files (also forbidden in recipes) are caught by the CI workflow instead, not by this skill. Runs in two modes: a read-only --dry-run that reports what needs alignment, and an apply mode that rewrites pyproject.toml (and optionally manifest.yaml) using comment-preserving TOML/YAML editors. Use when the user wants to "align the recipe's pyproject.toml", "fix pyproject to match the repo standard", "check what needs changing in a recipe's pyproject", or clean up a recipe before submitting a PR.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

An unusually actionable, well-sequenced driver document: exact commands, explicit dry-run-before-apply validation, per-status decision rules, and a script reference that checks out against the actual bundle. The main cost is token efficiency — the 'Rules for the Agent' and 'Respond' sections overlap substantially and one table cell carries a paragraph of rationale — plus oversized inlined content that could live in a reference file.

Suggestions

Collapse the duplication between 'Rules for the Agent' (rules 5–9) and the 'Respond'/'Closing action' status guidance into a single per-status section; each rule currently appears twice in nearly identical wording.

Move the `python-version-floor` fix semantics (specifier rewriting rules, refusal cases) out of the rule table cell into a short subsection or reference file — the cell is ~180 words inside a table meant for scanning.

Trim tutorial-style explanation of rationale where the operational rule already implies it (e.g. the 'why the runnability test matters' prose in rule 9 duplicates the table's own 'the recipe looks tested while its import-smoke test silently never executes' wording).

Dimension	Reasoning	Score
Conciseness	The guidance is dense and operational, but there is real duplication: Rules 5–9 in 'Rules for the Agent' restate nearly verbatim the status-specific guidance in 'Respond'/'Closing action' (e.g. rule 7's 'Show the user the current url from details.current_url and ask whether it's deliberate' vs. 'quote details.current_url... and ask whether it's intentional'), and the `python-version-floor` table cell is a ~180-word essay inside a table. It fits 'mostly efficient but includes some unnecessary explanation or could be tightened' better than the minor-trimming anchor at 4.	3 / 5
Actionability	Every command is copy-paste ready — exact `uv run --no-project --with tomlkit --with 'ruamel.yaml' --with packaging python .agents/skills/align-recipe-pyproject/scripts/align_pyproject.py` invocations, flag values, exit-code semantics, JSON fields (`details.current_url`, `details.files`, `details.testpaths`), and complete TOML template snippets — covering dry-run, apply, and each resolution path.	5 / 5
Workflow Clarity	The sequence is explicit with validation checkpoints and feedback loops: ask for the recipe directory rather than guess, always dry-run first, a preview mode combining `--dry-run --description-source` to validate a choice before writing, per-status escalation rules, and an 'error rows → do not offer to apply' guardrail — a batch-rewriting skill whose write gate is a verified read-only pass.	5 / 5
Progressive Disclosure	The bundle structure is sound: all logic lives in the real one-level-deep `scripts/align_pyproject.py` (verified present, with all eight check functions and the documented flags), and SKILL.md is the operational driver. Below a 5 because some content that would sit better in a reference file is inlined — notably the very long rule-table cells and the two build-system template blocks appear inside response-format guidance rather than being split out.	4 / 5
	Total	17 / 20 Passed

Description

95%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: concrete actions, real file references, two clearly explained modes, and four natural quoted trigger phrases. The only weakness is mild verbosity — the scope-exclusion sentence about ruff.toml is precise but could live in the body — which keeps specificity just below full marks.

Dimension	Reasoning	Score
Specificity	Concrete actions are named — 'a read-only --dry-run that reports what needs alignment', 'an apply mode that rewrites pyproject.toml (and optionally manifest.yaml)', plus the '[build-system] presence check' — with real file paths. It stops short of a 5 because the actual standards being aligned against are deferred to the workflow file rather than enumerated, leaving minor coverage gaps in the description itself.	4 / 5
Completeness	Explicitly answers both: what ('Aligns a Python recipe's pyproject.toml with the repo's standards... rewrites pyproject.toml (and optionally manifest.yaml)') and when ('Use when the user wants to...') with concrete trigger phrases — the exact anchor-5 pattern.	5 / 5
Trigger Term Quality	Four quoted natural user phrases — '"align the recipe's pyproject.toml"', '"fix pyproject to match the repo standard"', '"check what needs changing in a recipe's pyproject"', 'clean up a recipe before submitting a PR' — cover synonyms across check/fix/align/clean-up intents, matching the comprehensive-coverage anchor.	5 / 5
Distinctiveness Conflict Risk	A clear niche (recipe pyproject.toml conformance in this repo) with an explicit scope boundary — 'standalone ruff.toml / .ruff.toml files... are caught by the CI workflow instead, not by this skill' — minimizing overlap with any neighboring skill.	5 / 5
	Total	19 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: google/adk-samples
Path: .agents/skills/align-recipe-pyproject/SKILL.md
Commit: 2f902cb

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.