Index of every page on this site: llms.txt
All skills
google avatar

/adk-unit-design

@37de74d
by googlegoogle/adk-python22k stars
4,392
Run it yourself

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`).

Use this Skill: https://skilld.dev/gh/google/adk-python/adk-unit-design

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈210 tokens for metadata: the name and description. ≈539 when used: this file. ≈329 more on demand in 1 file.

Description uses 10.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈835 characters, or 10.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    This skill assists in the creation and maintenance of software design documentation within the ADK development framework. It includes standard considerations for tools that process source code and interact with the local file system.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: LOW · No issues

Signed by skilld at 37de74d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 months ago

README badge

README badge for google/adk-python/adk-unit-design