adk-unit-design
Writes an as-built architecture document for one ADK code unit — purpose, execution flow, data flow, cross-class dependencies, extension points, and the parts that must not change — to docs/design/{topic}/{unit}/index.md. It describes the code as implemented, not a proposed design, and its reader is a developer about to change or extend that unit. Use when asked to "write a design doc for {file}", "document the architecture of {class}", "document the extension points of {unit}", or after adding a core class, node type, or plugin base. Don't use for documentation aimed at developers who only call the unit from their own application — that is a usage guide with runnable examples under docs/guides/ (use adk-unit-guide). Don't use to answer a framework-wide architecture question (use adk-architecture).
- Installs
- 68
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/google/adk-python --skill adk-unit-design- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads adk-unit-design automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
ADK code unit design
A unit design documents a code unit as implemented, the way a unit test exercises it as implemented. Nothing proposed or aspirational belongs in one. The reader is deciding what they may safely change, so answer "what breaks if I touch this?" — not "how do I call this?".
Inputs
Require the source file, or a class or method named inside it. Also read, when they exist: the base classes and interfaces the unit implements, its unit tests (the best evidence of intended behaviour), and example usage.
Analyse before writing
Answer each of these from the source. Anything the code does not show stays out of the document — do not infer a design intent from a name.
- Purpose and intended use of the unit.
- Execution flow, and the data that flows in and out.
- Upstream dependencies, and which classes depend on this unit.
- Extension surfaces: abstract methods, hooks, callbacks, configurable fields.
- Constraints — what a subclass or caller must not change, and why.
- Operational limitations.
Where the document goes
Mirror the source path under docs/design/, one directory per unit, document
named index.md. Drop the leading underscore of a private module:
| Source | Design document |
|---|---|
src/google/adk/workflow/_function_node.py | docs/design/workflow/function_node/index.md |
src/google/adk/events/event.py | docs/design/events/event/index.md |
If a document already exists at that path, update it in place and keep the existing wording wherever the code has not changed, so the diff shows only what the change actually altered.
docs/design/ does not exist in this repository yet — the first design document
creates it. docs/guides/ is the established sibling tree; match its directory
shape.
Link to GitHub, not to local paths
These documents render on GitHub, where a local filesystem path is dead.
Rewrite {repo_root}/src/google/adk/{topic}/{unit}.py#L93 as
https://github.com/google/adk-python/blob/main/src/google/adk/{topic}/{unit}.py#L93.
Structure
Follow references/design-template.md section by section.
FAQ
What does the adk-unit-design skill do?
Writes an as-built architecture document for one ADK code unit — purpose, execution flow, data flow, cross-class dependencies, extension points, and the parts that must not change — to docs/design/{topic}/{unit}/index.md. It describes the code as implemented, not a proposed design, and its reader is a developer about to change or extend that unit. Use when asked to "write a design doc for {file}", "document the architecture of {class}", "document the extension points of {unit}", or after adding a core class, node type, or plugin base. Don't use for documentation aimed at developers who only call the unit from their own application — that is a usage guide with runnable examples under docs/guides/ (use adk-unit-guide). Don't use to answer a framework-wide architecture question (use adk-architecture).
How do I install adk-unit-design?
Run npx skills add https://github.com/google/adk-python --skill adk-unit-design in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/adk-unit-design/ (personal) or .claude/skills/adk-unit-design/ (project).
Which AI agents can use adk-unit-design?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is adk-unit-design safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains adk-unit-design?
It is published by google in google/adk-python. It has 68 recorded installs.
More from google/adk-python
adk-agent-builder
google/adk-python
Builds ADK (Agent Development Kit) Python agents: LLM agents with tools, graph workflows of function and agent nodes, conditional routing, fan-out and join, schema-validated delegation between agents, human-in-the-loop pauses, and pytest coverage for all of it. Use when asked to create an agent or a workflow, add a tool to one, branch or loop between nodes, run steps in parallel, pause for user approval, or test an agent. Don't use for explaining how ADK works internally or designing its core components (use adk-architecture), for an agent that already runs but misbehaves (use adk-debug), for authoring a sample under contributing/ (use adk-sample-creator), or for naming, typing, and formatting conventions (use adk-style).
adk-architecture
google/adk-python
Explains how the ADK runtime fits together: the node and graph execution model, Context and Event flow, checkpoint and resume, tracing, and the rules governing the public API surface. Use when answering "how does X work" about ADK internals, tracing where an event or a piece of state comes from, deciding where a new capability belongs, reviewing a change to BaseNode, Workflow, Runner, Agent, Event or Context, working out why a node re-ran or stayed waiting after a resume, or judging whether a change breaks the public API. Don't use for assembling an agent from existing pieces (use adk-agent-builder), diagnosing one failing run or test (use adk-debug), or formatting and naming conventions (use adk-style).
adk-debug
google/adk-python
Diagnoses misbehaving ADK agents by inspecting sessions, events, tool calls, and the exact request that reached the model. Covers the adk run CLI and the adk web dev server with its session, trace, and debug HTTP endpoints. Use when an agent returns the wrong answer, ignores a tool or swallows a tool error, hangs, loops, emits raw JSON instead of calling tools, is not discovered by adk web, when a sub-agent cannot see the parent conversation, or when you need the LLM request/response, token counts, or logs for a run. Don't use for how ADK is designed internally (use adk-architecture), for building a new agent or workflow (use adk-agent-builder), for environment or dependency setup failures (use adk-setup), or for lint and style nits (use adk-style).
adk-style
google/adk-python
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).
adk-setup
google/adk-python
Sets up a local ADK Python development environment in a git clone of the open-source adk-python repository: a uv virtual environment, all dependency extras, pre-commit hooks, and a first unit-test run. Runs only when explicitly requested, never on its own. Use when asked to set up, bootstrap, or repair a development checkout, install project dependencies, fix a missing or broken .venv, or prepare a machine for contributing a pull request. Don't use for debugging a running agent (use adk-debug), for commit and pull-request mechanics (use adk-git), or for re-running formatters on a checkout that is already set up (pre-commit run --all-files).
adk-sample-creator
google/adk-python
Creates a new sample agent in the ADK Python repository — the sample directory, its agent.py, and its README.md — following the conventions the existing samples already use. Use when the user wants to add a sample or example demonstrating a feature or agent pattern (dynamic nodes, fan-out/fan-in, a standalone tool-using agent), asks where a new sample belongs under contributing/samples/, or wants an existing sample's README brought up to the standard structure. Don't use for building a real working agent for the user's own project (use adk-agent-builder), or for checking whether the Python blocks in a Markdown file run (use adk-verify-snippets).
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.