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-style
3description: >-
4 Python style and codebase conventions for ADK (Agent Development Kit):
5 private-by-default file visibility, imports, type hints, Pydantic v2 models,
6 formatting, docstrings, logging, async I/O, file and test layout, and unit
7 test structure. Use when writing or editing ADK source or tests, deciding
8 whether a new file or symbol should be public or private, naming or placing
9 a test file, fixing a formatter, linter, or type-check failure (pyink,
10 isort, ruff, mypy, addlicense, compliance-checks), or asking whether code
11 matches house style. Don't use for reviewing a whole changeset (use
12 adk-review), writing a developer guide or design doc for a code unit (use
13 adk-unit-guide or adk-unit-design), building or configuring agents (use
14 adk-agent-builder), or installing the toolchain (use adk-setup).
15metadata:
16 source: https://skillmd.com/skills/google/adk-style
17---
1819# ADK Style Guide
2021Conventions for `src/google/adk/` and `tests/unittests/`. Most are enforced by
22a pre-commit hook or a CI job, so a violation blocks the PR rather than
23surfacing in review. Read the one reference for the topic you are touching.
2425## Pick a reference
2627| Task | Reference |
28| --- | --- |
29| Adding a `.py` file; deciding public vs private; `__init__.py` and `__all__` | [visibility.md](references/visibility.md) |
30| Writing `import` lines; relative vs absolute; circular imports; `TYPE_CHECKING` | [imports.md](references/imports.md) |
31| Annotating args and returns; `Optional` vs `\| None`; keyword-only args; `isinstance`; asserts; mypy | [typing.md](references/typing.md) |
32| Defining a Pydantic model, validator, private attribute, or on-wire payload | [pydantic.md](references/pydantic.md) |
33| Indentation, line length, quotes; running the formatter; what each hook checks | [formatting.md](references/formatting.md) |
34| Writing a docstring or an explanatory comment | [documentation.md](references/documentation.md) |
35| Emitting a log record; naming the module logger; picking a level | [logging.md](references/logging.md) |
36| Anything that performs I/O — network, disk, database | [async.md](references/async.md) |
37| Where a new file goes; license header; where its test goes and what to call it | [file-organization.md](references/file-organization.md) |
38| Writing or restructuring a unit test | [testing.md](references/testing.md) |
3940## A check failed — where to look
4142| Failing check | Reference |
43| --- | --- |
44| `check-new-py-prefix` | [visibility.md](references/visibility.md) |
45| `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) |
46| `pyink`, `isort`, `ruff`, `addlicense`, `codespell` | [formatting.md](references/formatting.md) |
47| Mypy Check CI job | [typing.md](references/typing.md) |
Run npx get-skill 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.