chore(agents): add the unit-guide and sample-creator authoring skills - #855
Open
AmaadMartin wants to merge 4 commits into
Open
chore(agents): add the unit-guide and sample-creator authoring skills#855AmaadMartin wants to merge 4 commits into
AmaadMartin wants to merge 4 commits into
Conversation
added 4 commits
September 3, 2026 12:29
…adk-python
Ports `.agents/skills/adk-unit-guide` and `.agents/skills/adk-sample-creator`
to the adk-js reality, keeping the intent, voice and reasoning of the Python
originals and replacing every Python-specific instruction with a verified
adk-js one.
The corrections that matter, each checked against the repository rather than
assumed:
- Samples live at `samples/{category}/…/{name}/agent.ts` and export
`rootAgent`. There is no per-sample README; all 26 existing samples carry a
header comment plus a row in their category README, so `readme-template.md`
now describes the category README and says where each section of the Python
per-sample README went.
- `workflows` is the only category today, so the sample skill spells out the
four things a new category needs — including that
`tests/integration/docs_samples` resolves `SAMPLES_ROOT` to
`samples/workflows`, so a new category gets no execution coverage.
- The "do not set `model=`" rule inverts. adk-js has no system-configured
default: `LlmAgent.canonicalModel` throws `No model found for {name}`. Both
skills now require `model: 'gemini-flash-latest'`, the floating alias every
sample already uses.
- `docs/guides/` is new here, so the guide skill keeps the mirror-the-source
and index-every-guide rules and adds the case adk-js creates by splitting a
Python module across files: a source directory holding a base class and its
implementations gets one guide.
Dropped, with the reason stated in each skill: the `docs/design/` input, since
adk-js has no design-document tree; `__init__.py` and per-sample eval sets,
which have no counterpart; the Mermaid topology diagram, which lost its home
with the per-sample README; and the `adk-style` prerequisite, since eslint,
Prettier and tsconfig are the style authority here.
Two reviewer corrections to the migrated authoring skills.
adk-unit-guide dropped the adk-js-specific exception that let a directory
holding a base class and its implementations share one guide, and restored
adk-python's rule: one source file is one unit, one unit is one directory. The
concern behind the exception was real, so it is met a different way — each
guide of a sibling set opens by naming its siblings and the reason to pick
each, and docs/guides/README.md lists the set under one shared heading, so a
reader landing on one page from search can tell in a sentence whether they are
on the right one. The related-samples depth is no longer hardcoded at four
levels, since a guide mirroring a nested source directory sits deeper.
adk-sample-creator now requires samples/{category}/{name}/README.md. That
diverges from all 26 samples on disk, which carry only a header comment and a
category-table row, and the skill says so: new samples set the convention
rather than follow it. readme-template.md covers both READMEs, with the
per-sample one first, following adk-python's section order and prompt
formatting. The Mermaid topology diagram is reinstated for samples whose
graph is not already legible in the edges array, now that it has a home.
Follow-up to the two reviewer corrections, which landed in the previous commit. Two things they left behind. adk-unit-guide illustrated a related-samples link with samples/tools/retrieval/agent.ts, carried over from the adk-python migration. No such sample exists, and no samples/tools/ category does either — every sample on disk is under samples/workflows/. The example now links samples/workflows/routes/fan_out_join/agent.ts at the four-level depth and states the five-level case as arithmetic rather than as a second invented path, so the one concrete link in a section that ends "confirm the file exists before linking it" is a file that exists. adk-sample-creator's new-category checklist said a link elsewhere is what makes "the new README" reachable. That read unambiguously when the category README was the only one; now that every sample has one, item 3 names the category README and says the per-sample ones are reached from its table.
The requirement was already in the skill, but the reason given for it was weak: that the README holds prompts and diagrams the header comment has no room for. True, and not the point. `adk web` renders the per-sample README in the UI when a sample is selected, so it is read in a browser far more often than in the repository, by someone deciding whether to run the sample who cannot see the code yet. That is a functional requirement, not a documentation convention, and the skill now leads with it. The old text also hedged -- "new samples set the convention rather than follow it", "adding a sample does not oblige you to retrofit the existing 26". The 26 are being backfilled, so the hedge was wrong about the direction of travel and invited an author to treat the README as optional. Two facts about the current state are recorded, because both change what an author should expect. The 26 existing samples have no README yet, so the template is the reference and neighbouring directories are not. And adk-js does not populate the field it declares: `AppInfo.readme` exists in dev/src/server/app_info.ts and adk_api_server.ts calls serializeAppInfo without it, where adk-python's cli/dev_server.py reads README.md from the agent directory and returns it. Write for the rendered case anyway, because closing that gap is a dev-server change rather than a sample change. The frontmatter now triggers on backfilling a README, which is the work coming.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Migrates adk-python's two authoring skills to adk-js conventions, so unit guides
and samples have a written standard here as they do there.
4 files, +859, −0. No source code is touched.
.agents/skills/adk-unit-guide/— writes a developer guide for one code unitinto
docs/guides/{topic}/{unit}/index.md.agents/skills/adk-sample-creator/— creates a sample undersamples/{category}/{name}/Split out of #854 so that PR stays retrieval-only; they share no files and
either can merge first. #854 contains the first output of both.
What migration changed
Voice, structure and reasoning are kept verbatim where they still apply.
Everything Python-specific was rewritten against adk-js as it actually is,
checked in the repository rather than assumed.
One rule inverts. adk-python says never set
model=on a sample, becausesamples inherit a system-configured default. adk-js has no such default:
LlmAgent.canonicalModelwalks to the parent and throwsNo model found for {name}(core/src/agents/llm_agent.ts:646). Both skillstherefore require a model and specify
gemini-flash-latest, the floatingalias all 12 model-using call sites under
samples/already use. That servesthe same purpose the Python rule exists for — not pinning a model that gets
retired.
Every sample gets a
README.md.adk webrenders it when a sample isselected, so it is read in a browser more often than in the repository, by
someone deciding whether to run the sample before they can see any code. Note
the field is declared but not yet populated in adk-js — #853 wires that up.
Paths.
samples/{category}/{name}/agent.ts, notcontributing/samples/.The header format is documented exactly as the existing samples write it,
including the licence block matched literally by
scripts/check_license.sh.Adding a sample category is spelled out, including the non-obvious part:
tests/integration/docs_samples/docs_samples_test.tsresolves its root tosamples/workflowsspecifically, so a new category gets lint, Prettier, licenceand
ts:check:samples— and nothing that runs it.Dropped, each with the reason stated in the skill
docs/design/{topic}/{unit}/index.mdpairing. adk-js has no design-doctree and no
adk-unit-designskill; no location was invented for one.__init__.pyand eval-set fixtures. No counterpart here.adk-styleskill first." No such skill; eslint, Prettier andtsconfig are the authority.
Verification
lint,format:checkandcheck_license.shpass. BothSKILL.mdfiles carryvalid frontmatter with
nameanddescription.These are documentation for authors; they change no runtime behaviour.