Python style and codebase conventions for ADK (Agent Development Kit): private-by-default file visibility, imports, type hints, Pydantic v2 models, formatting, docstrings, logging, async I/O, file and test layout, and unit test structure. Use when writing or editing ADK source or tests, deciding whether a new file or symbol should be public or private, naming or placing a test file, fixing a formatter, linter, or type-check failure (pyink, isort, ruff, mypy, addlicense, compliance-checks), or asking whether code matches house style. Don't use for reviewing a whole changeset (use adk-review), writing a developer guide or design doc for a code unit (use adk-unit-guide or adk-unit-design), building or configuring agents (use adk-agent-builder), or installing the toolchain (use adk-setup).
Conventions for src/google/adk/ and tests/unittests/. Most are enforced by
a pre-commit hook or a CI job, so a violation blocks the PR rather than
surfacing in review. Read the one reference for the topic you are touching.
Pick a reference
Task
Reference
Adding a .py file; deciding public vs private; __init__.py and __all__
visibility.md
Writing import lines; relative vs absolute; circular imports; TYPE_CHECKING
imports.md
Annotating args and returns; Optional vs | None; keyword-only args; isinstance; asserts; mypy
typing.md
Defining a Pydantic model, validator, private attribute, or on-wire payload
pydantic.md
Indentation, line length, quotes; running the formatter; what each hook checks
formatting.md
Writing a docstring or an explanatory comment
documentation.md
Emitting a log record; naming the module logger; picking a level
logging.md
Anything that performs I/O — network, disk, database
async.md
Where a new file goes; license header; where its test goes and what to call it
1---2name: adk-style3description: Python style and codebase conventions for ADK (Agent Development Kit): private-by-default file visibility, imports, type hints, Pydantic v2 models, formatting, docstrings, logging, async I/O, file and test layout, and unit test structure. Use when writing or editing ADK source or tests, deciding whether a new file or symbol should be public or private, naming or placing a test file, fixing a formatter, linter, or type-check failure (pyink, isort, ruff, mypy, addlicense, compliance-checks), or asking whether code matches house style. Don't use for reviewing a whole changeset (use adk-review), writing a developer guide or design doc for a code unit (use adk-unit-guide or adk-unit-design), building or configuring agents (use adk-agent-builder), or installing the toolchain (use adk-setup).4---56# ADK Style Guide
78Conventions for `src/google/adk/` and `tests/unittests/`. Most are enforced by
9a pre-commit hook or a CI job, so a violation blocks the PR rather than
10surfacing in review. Read the one reference for the topic you are touching.
1112## Pick a reference
1314| Task | Reference |
15| --- | --- |
16| Adding a `.py` file; deciding public vs private; `__init__.py` and `__all__` | [visibility.md](references/visibility.md) |
17| Writing `import` lines; relative vs absolute; circular imports; `TYPE_CHECKING` | [imports.md](references/imports.md) |
18| Annotating args and returns; `Optional` vs `\| None`; keyword-only args; `isinstance`; asserts; mypy | [typing.md](references/typing.md) |
19| Defining a Pydantic model, validator, private attribute, or on-wire payload | [pydantic.md](references/pydantic.md) |
20| Indentation, line length, quotes; running the formatter; what each hook checks | [formatting.md](references/formatting.md) |
21| Writing a docstring or an explanatory comment | [documentation.md](references/documentation.md) |
22| Emitting a log record; naming the module logger; picking a level | [logging.md](references/logging.md) |
23| Anything that performs I/O — network, disk, database | [async.md](references/async.md) |
24| Where a new file goes; license header; where its test goes and what to call it | [file-organization.md](references/file-organization.md) |
25| Writing or restructuring a unit test | [testing.md](references/testing.md) |
2627## A check failed — where to look
2829| Failing check | Reference |
30| --- | --- |
31| `check-new-py-prefix` | [visibility.md](references/visibility.md) |
32| `compliance-checks` | [logging.md](references/logging.md) (logger name), [typing.md](references/typing.md) (`from __future__ import annotations`), [imports.md](references/imports.md) (`cli/` import direction) |
33| `pyink`, `isort`, `ruff`, `addlicense`, `codespell` | [formatting.md](references/formatting.md) |
34| Mypy Check CI job | [typing.md](references/typing.md) |
Run npx skillmds@latest add google/adk-style in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Python style and codebase conventions for ADK (Agent Development Kit): private-by-default file visibility, imports, type hints, Pydantic v2 models, formatting, docstrings, logging, async I/O, file and test layout, and unit test structure. Use when writing or editing ADK source or tests, deciding whether a new file or symbol should be public or private, naming or placing a test file, fixing a formatter, linter, or type-check failure (pyink, isort, ruff, mypy, addlicense, compliance-checks), or asking whether code matches house style. Don't use for reviewing a whole changeset (use adk-review), writing a developer guide or design doc for a code unit (use adk-unit-guide or adk-unit-design), building or configuring agents (use adk-agent-builder), or installing the toolchain (use adk-setup). It is listed under AI & ML on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
Google (@google) published this skill. Their other Agent Skills are listed on their SkillMD profile.
Google