feat(skills): inject session state into SKILL.md via adk_inject_state

Merge #5405

### Link to Issue or Description of Change

- Closes: #5404

**Problem:** SKILL.md bodies cannot reference session state the same way `LlmAgent.instruction` can. Today the only way to surface a state value inside a skill is to register a custom getter tool through `SkillToolset(additional_tools=[...])` and tell the model to call it. That is boilerplate for a capability the agent already has.

**Solution:** Reuse the existing `instructions_utils.inject_session_state` helper from `LoadSkillTool`. When a skill opts in with `metadata.adk_inject_state: true` in its frontmatter, the skill body is interpolated with the same `{var}` / `{var?}` / `{artifact.name}` syntax that `LlmAgent.instruction` supports. The feature is strictly additive and gated on an opt-in flag, so existing SKILL.md files are unaffected.

### Testing Plan

**Unit Tests:**

- [x] I have added or updated unit tests for my change.
- [x] All unit tests pass locally.

Added to `tests/unittests/tools/test_skill_toolset.py`:

- `test_load_skill_run_async_injects_state_when_opt_in`
- `test_load_skill_run_async_skips_injection_when_opt_out`
- `test_load_skill_run_async_skips_injection_when_metadata_absent`

Added to `tests/unittests/skills/test_models.py`:

- `test_metadata_adk_inject_state_bool`
- `test_metadata_adk_inject_state_rejected_as_string`

Existing mock fixtures for `skill1` / `skill2` frontmatter now explicitly set `metadata = {}`, documenting the default and preventing autospec-mock leakage into the new opt-in check.

`pytest` summary:

```
$ pytest tests/unittests/tools/test_skill_toolset.py tests/unittests/skills/test_models.py
111 passed, 7 warnings in 11.39s
```

**Manual End-to-End (E2E) Tests:**

1. In a skill directory, add `metadata: {adk_inject_state: true}` to `SKILL.md` frontmatter and reference a state variable in the body, e.g. `The user prefers {temperature_unit?}.`
2. Seed session state with `session.state["temperature_unit"] = "celsius"` before the agent runs.
3. Run the agent (`adk run` or `adk web`) and trigger the skill. The `load_skill` tool response now contains the instructions with `{temperature_unit}` expanded to `celsius`.
4. Remove or set `adk_inject_state: false` and re-run — the same SKILL.md returns the literal `{temperature_unit?}` string, confirming backward compatibility.

### Checklist

- [x] I have read the [CONTRIBUTING.md](https://github.com/google/adk-python/blob/main/CONTRIBUTING.md) document.
- [x] I have performed a self-review of my own code.
- [x] I have commented my code, particularly in hard-to-understand areas.
- [x] I have added tests that prove my fix is effective or that my feature works.
- [x] New and existing unit tests pass locally with my changes.
- [x] I have manually tested my changes end-to-end.
- [x] Any dependent changes have been merged and published in downstream modules.

### Additional context

This is the read side of a two-part effort to connect SKILL.md with session state. A follow-up PR will propose an `output_key`-style facility for writing state from a skill. Splitting the two keeps each review small and focused.

Co-authored-by: Haran Rajkumar <haranrk@google.com>
COPYBARA_INTEGRATE_REVIEW=#5405 from Koichi73:feat/skill-md-inject-state 44067c2
PiperOrigin-RevId: 936248442

Author: 2 people

src/google/adk/skills/models.py

@@ -50,7 +50,13 @@ class Frontmatter(BaseModel):
         https://agentskills.io/specification#allowed-tools-field.
       metadata: Key-value pairs for client-specific properties (defaults to
         empty dict). For example, to include additional tools, use the
-        ``adk_additional_tools`` key with a list of tools.
+        ``adk_additional_tools`` key with a list of tools. Set
+        ``adk_inject_state: true`` to enable ``{var}`` interpolation in the
+        SKILL.md body when the skill is loaded via ``load_skill`` (same syntax
+        as ``LlmAgent.instruction``). Each ``{var}`` is replaced with the
+        matching value read from the invocation's session state; use ``{var?}``
+        to substitute an empty string when the key is absent (instead of
+        raising), and ``{artifact.name}`` to inject artifact contents.
   """
 
   model_config = ConfigDict(
@@ -76,6 +82,8 @@ def _validate_metadata(cls, v: dict[str, Any]) -> dict[str, Any]:
       tools = v["adk_additional_tools"]
       if not isinstance(tools, list):
         raise ValueError("adk_additional_tools must be a list of strings")
+    if "adk_inject_state" in v and not isinstance(v["adk_inject_state"], bool):
+      raise ValueError("adk_inject_state must be a bool")
     return v
 
   @field_validator("name")

src/google/adk/tools/skill_toolset.py

@@ -36,6 +36,7 @@
 from ..skills import models
 from ..skills import prompt
 from ..skills import SkillRegistry
+from ..utils import instructions_utils
 from .base_tool import BaseTool
 from .base_toolset import BaseToolset
 from .base_toolset import ToolPredicate
@@ -251,9 +252,16 @@ async def run_async(
       activated_skills.append(skill_name)
       tool_context.state[state_key] = activated_skills
 
+    instructions = skill.instructions
+    if skill.frontmatter.metadata.get("adk_inject_state"):
+      instructions = await instructions_utils.inject_session_state(
+          instructions,
+          tool_context,
+      )
+
     return {
         "skill_name": skill_name,
-        "instructions": skill.instructions,
+        "instructions": instructions,
         "frontmatter": skill.frontmatter.model_dump(),
     }
 

tests/unittests/skills/test_models.py

@@ -232,3 +232,21 @@ def test_metadata_adk_additional_tools_invalid_type():
         "description": "desc",
         "metadata": {"adk_additional_tools": 123},
     })
+
+
+def test_metadata_adk_inject_state_bool():
+  fm = models.Frontmatter.model_validate({
+      "name": "my-skill",
+      "description": "desc",
+      "metadata": {"adk_inject_state": True},
+  })
+  assert fm.metadata["adk_inject_state"] is True
+
+
+def test_metadata_adk_inject_state_rejected_as_string():
+  with pytest.raises(ValidationError, match="adk_inject_state must be a bool"):
+    models.Frontmatter.model_validate({
+        "name": "my-skill",
+        "description": "desc",
+        "metadata": {"adk_inject_state": "true"},
+    })

tests/unittests/tools/test_skill_toolset.py

@@ -38,6 +38,7 @@ def _mock_skill1_frontmatter():
   frontmatter.name = "skill1"
   frontmatter.description = "Skill 1 description"
   frontmatter.allowed_tools = ["test_tool"]
+  frontmatter.metadata = {}
   frontmatter.model_dump.return_value = {
       "name": "skill1",
       "description": "Skill 1 description",
@@ -107,6 +108,7 @@ def _mock_skill2_frontmatter():
   frontmatter.name = "skill2"
   frontmatter.description = "Skill 2 description"
   frontmatter.allowed_tools = []
+  frontmatter.metadata = {}
   frontmatter.model_dump.return_value = {
       "name": "skill2",
       "description": "Skill 2 description",
@@ -310,6 +312,74 @@ async def test_load_skill_run_async_state_none(
   )
 
 
+@pytest.mark.asyncio
+async def test_load_skill_run_async_injects_state_when_opt_in(
+    mock_skill1, mock_skill1_frontmatter, tool_context_instance
+):
+  mock_skill1.instructions = "Hello {user_name}!"
+  mock_skill1_frontmatter.metadata = {"adk_inject_state": True}
+  toolset = skill_toolset.SkillToolset([mock_skill1])
+  tool = skill_toolset.LoadSkillTool(toolset)
+
+  with mock.patch.object(
+      skill_toolset.instructions_utils,
+      "inject_session_state",
+      autospec=True,
+  ) as mock_inject:
+    mock_inject.return_value = "Hello Alice!"
+    result = await tool.run_async(
+        args={"skill_name": "skill1"}, tool_context=tool_context_instance
+    )
+
+  mock_inject.assert_awaited_once()
+  call_args = mock_inject.await_args
+  assert call_args.args[0] == "Hello {user_name}!"
+  assert result["instructions"] == "Hello Alice!"
+
+
+@pytest.mark.asyncio
+async def test_load_skill_run_async_skips_injection_when_opt_out(
+    mock_skill1, mock_skill1_frontmatter, tool_context_instance
+):
+  mock_skill1.instructions = "Hello {user_name}!"
+  mock_skill1_frontmatter.metadata = {"adk_inject_state": False}
+  toolset = skill_toolset.SkillToolset([mock_skill1])
+  tool = skill_toolset.LoadSkillTool(toolset)
+
+  with mock.patch.object(
+      skill_toolset.instructions_utils,
+      "inject_session_state",
+      autospec=True,
+  ) as mock_inject:
+    result = await tool.run_async(
+        args={"skill_name": "skill1"}, tool_context=tool_context_instance
+    )
+
+  mock_inject.assert_not_called()
+  assert result["instructions"] == "Hello {user_name}!"
+
+
+@pytest.mark.asyncio
+async def test_load_skill_run_async_skips_injection_when_metadata_absent(
+    mock_skill1, tool_context_instance
+):
+  mock_skill1.instructions = "Hello {user_name}!"
+  toolset = skill_toolset.SkillToolset([mock_skill1])
+  tool = skill_toolset.LoadSkillTool(toolset)
+
+  with mock.patch.object(
+      skill_toolset.instructions_utils,
+      "inject_session_state",
+      autospec=True,
+  ) as mock_inject:
+    result = await tool.run_async(
+        args={"skill_name": "skill1"}, tool_context=tool_context_instance
+    )
+
+  mock_inject.assert_not_called()
+  assert result["instructions"] == "Hello {user_name}!"
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     "args, expected_result",