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

[Koichi73]

Link to Issue or Description of Change

• Closes: Support session state interpolation in SKILL.md via adk_inject_state #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:

• I have added or updated unit tests for my change.
• 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

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• 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.

[rohityan]

Hi @Koichi73 , Thank you for your contribution! We appreciate you taking the time to submit this pull request. Can you please fix the failing unit tests before we can proceed with the review.

[Koichi73]

Hi @rohityan, the failing test is test_parallel_function_execution_timing, a known-flaky timing-based test (see b92b288) unrelated to this PR's changes. It passes 5/5 locally on Python 3.12 (macOS).

I've pushed an empty commit to retrigger CI, but the workflow is waiting for maintainer approval. Could you approve it when you have a moment? 🙏

[Koichi73]

Hi @rohityan, gentle ping on this — it's been a week since my last reply.

To summarize where things stand:

• The CI failure (test_parallel_function_execution_timing) is a known-flaky timing test (b92b288), unrelated to this PR. It passes locally and is not touched by these changes.
• The workflow re-run from my empty commit on 4/21 is still pending maintainer approval to start, so I can't get a green CI run on my own.

Could you (or another maintainer) approve the CI run when you have a minute? Thanks for your time.

[rohityan]

Hi @Jacksunwei , can you please review this.

[Koichi73]

Hi @Jacksunwei, I've merged the latest main and resolved the conflict in skill_toolset.py.
It was only an import collision, so I've kept both SkillRegistry and instructions_utils.
Please take a look whenever you have a moment. Thanks!

[adk-bot]

Thank you @Koichi73 for your contribution! 🎉

Your changes have been successfully imported and merged via Copybara in commit 3afdb08.

Closing this PR as the changes are now in the main branch.