feat(samples): add sample for skill state injection via adk_inject_state

Demonstrates reading session state from a skill without a custom getter tool.
The code-review-skill opts in with metadata.adk_inject_state: true and
references {dev_name}/{dev_language}/{dev_level} directly; LoadSkillTool fills
them in from session state at load time, the same {var} interpolation
LlmAgent.instruction already supports. A remember_developer_profile tool
populates the state that the skill then reads.

Author: Koichi73

contributing/samples/environment_and_skills/skills_inject_state/README.md

@@ -0,0 +1,76 @@
+# ADK Skill State Injection Sample
+
+## Overview
+
+This sample demonstrates **session state injection** into a skill via the
+`adk_inject_state` metadata flag.
+
+Without this flag, a skill that needs to read a value the agent already
+holds — a user preference, conversation context, or any other state value —
+has to ship its own custom "getter" tool, wire it through
+`SkillToolset(additional_tools=[...])`, and instruct the model to call it. That
+is extra application code plus an extra LLM round-trip at runtime, just to read
+state.
+
+`adk_inject_state` removes that boilerplate. When a skill's `SKILL.md`
+frontmatter sets `metadata.adk_inject_state: true`, `LoadSkillTool` renders the
+skill body through `inject_session_state` at load time, substituting any
+`{placeholder}` with the matching value from session state. It is the same
+`{var}` / `{var?}` interpolation that `LlmAgent.instruction` already supports —
+now available to skills as a one-line, declarative change.
+
+This sample showcases:
+
+1. **Opting into injection**: Setting `metadata.adk_inject_state: true` in
+   `SKILL.md`.
+1. **Declarative state access**: Referencing session state directly with
+   `{dev_name}`, `{dev_language}`, and `{dev_level}` placeholders — no getter
+   tool required.
+1. **Populating state**: A `remember_developer_profile` tool that writes the
+   profile into session state, which the skill later reads via injection.
+
+## How It Works
+
+```mermaid
+graph TD
+    User -->|"1. introduces themselves"| Agent[Agent: skills_inject_state_agent]
+    Agent -->|writes dev_name, dev_language, dev_level| State[(Session State)]
+    User -->|"2. asks for a code review"| Agent
+    Agent -->|load_skill code-review-skill| Toolset[SkillToolset]
+    State -. injected into instructions .-> Toolset
+    Toolset -->|instructions with state filled in| Agent
+```
+
+## Sample Inputs
+
+Run from the parent directory:
+
+```shell
+adk web
+```
+
+Then, in a single session, send these turns in order:
+
+1. `Hi, I'm Alex. I mainly write Python and I'm a senior engineer.`
+
+   *The agent calls `remember_developer_profile`, storing the profile in
+   session state.*
+
+1. `Can you review this for me?  def add(a, b): return a+b`
+
+   *The agent loads `code-review-skill`. Because the skill opts into
+   `adk_inject_state`, the `{dev_name}` / `{dev_language}` / `{dev_level}`
+   placeholders are already filled in from state when the instructions are
+   returned — no separate tool call was needed to read the profile.*
+
+## Placeholder Syntax
+
+Placeholders map to session state keys:
+
+- `{key}` — required; injection fails if the key is missing.
+- `{key?}` — optional; replaced with an empty string if the key is missing.
+- `{user:key}`, `{app:key}`, `{temp:key}` — read prefixed
+  (user-/app-/temp-scoped) state.
+
+This sample uses the optional form (`{dev_name?}`) so that loading the skill
+before a profile has been set degrades gracefully instead of erroring.

contributing/samples/environment_and_skills/skills_inject_state/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from . import agent

contributing/samples/environment_and_skills/skills_inject_state/agent.py

@@ -0,0 +1,87 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Sample showing how a skill personalizes its instructions from session state.
+
+A skill whose ``SKILL.md`` frontmatter sets ``metadata.adk_inject_state: true``
+has its instructions rendered through ``inject_session_state`` at load time.
+Any ``{placeholder}`` in the instructions is replaced with the matching value
+from session state, so the same skill yields different instructions per session.
+
+Run from the parent directory with ``adk web``.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from google.adk.agents import Agent
+from google.adk.skills import load_skill_from_dir
+from google.adk.tools.skill_toolset import SkillToolset
+from google.adk.tools.tool_context import ToolContext
+
+
+def remember_developer_profile(
+    name: str,
+    primary_language: str,
+    experience_level: str,
+    tool_context: ToolContext,
+) -> dict:
+  """Saves the developer's profile into session state for later personalization.
+
+  Args:
+    name: The developer's name.
+    primary_language: The language they primarily work in, e.g. "Python".
+    experience_level: Their experience level, e.g. "junior" or "senior".
+  """
+  tool_context.state["dev_name"] = name
+  tool_context.state["dev_language"] = primary_language
+  tool_context.state["dev_level"] = experience_level
+  return {
+      "status": "ok",
+      "stored": {
+          "dev_name": name,
+          "dev_language": primary_language,
+          "dev_level": experience_level,
+      },
+  }
+
+
+# Load a directory-based skill. Its SKILL.md opts into state injection via
+# `metadata.adk_inject_state: true`, so `{dev_name}`, `{dev_language}`, and
+# `{dev_level}` in its instructions are substituted from session state when the
+# skill is loaded.
+code_review_skill = load_skill_from_dir(
+    pathlib.Path(__file__).parent / "skills" / "code-review-skill"
+)
+
+my_skill_toolset = SkillToolset(skills=[code_review_skill])
+
+root_agent = Agent(
+    name="skills_inject_state_agent",
+    description=(
+        "An agent that personalizes a code-review skill using session state."
+    ),
+    instruction=(
+        "You help developers review their code.\n"
+        "- When a user introduces themselves, call"
+        " `remember_developer_profile` to save who they are.\n"
+        "- When a user asks for a code review, load the `code-review-skill`"
+        " and follow its (personalized) instructions exactly."
+    ),
+    tools=[
+        remember_developer_profile,
+        my_skill_toolset,
+    ],
+)

contributing/samples/environment_and_skills/skills_inject_state/skills/code-review-skill/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: code-review-skill
+description: Reviews code with feedback tailored to the developer's profile in session state.
+metadata:
+  adk_inject_state: true
+---
+
+You are performing a personalized code review.
+
+The developer's profile (from session state):
+- Name: {dev_name?}
+- Primary language: {dev_language?}
+- Experience level: {dev_level?}
+
+If the profile above is empty, first ask the developer to introduce themselves
+(their name, primary language, and experience level) so the review can be
+personalized, then stop.
+
+Otherwise, follow these steps:
+
+1. Greet the developer by name.
+2. Review the code the user provided, focusing on idioms and best practices for
+   their primary language.
+3. Calibrate the depth of your feedback to their experience level: keep it
+   foundational for a junior developer, and concise and advanced for a senior
+   developer.
+4. End with one concrete, actionable suggestion.