Support session state injection in skill instructions (like system prompt)

[lwangverizon]

🔴 Required Information

Is your feature request related to a specific problem?

Agent instructions (system prompt) support injecting dynamic session state via
template variables — {var_name}, {app:var}, {artifact.file_name}, and the
optional {var?} form — through inject_session_state
(flows/llm_flows/instructions.py). Skill instructions do not. When the
load_skill tool returns a skill's SKILL.md body, the text is emitted
verbatim, so a skill cannot reference per-session state the way a system prompt
can.

This matters because of where skill content lands in the context window.
Skill instructions are delivered as a tool response, i.e. near the end of the
conversation, right before the model acts. Important instructions —
especially output/response-format directives — are generally best placed toward
the end of the prompt, where the model attends to them most strongly. That makes
skills a natural place to put format guidance, yet today that guidance has to be
fully static.

Concretely: I want a skill whose response-format section adapts to session
state — e.g. the user's preferred language, or an output schema/format that was
selected earlier and stored in state — and to have that section appear late in
context via the loaded skill. Today I cannot, because skill bodies do not
support state injection.

Describe the Solution You'd Like

Let skills opt in to the same session-state injection that system prompts
already use. Proposed: an opt-in frontmatter metadata flag
adk_inject_session_state (mirroring the existing adk_additional_tools
convention). When true, load_skill runs the instructions through the
existing inject_session_state utility before returning them; when absent,
behavior is unchanged.

Opt-in (default off) is important: skill markdown routinely contains literal
braces (code samples, JSON, templates), and inject_session_state raises on an
unknown {identifier}. Always-on injection would break existing skills.

Example SKILL.md:

---
name: report-writer
description: Writes a report and formats the final answer per the user's prefs.
metadata:
  adk_inject_session_state: true
---
... skill steps ...

## Response format (read this last)
Respond in {user_language}. Use the {output_format} structure.{extra_format_note?}

Impact on your work

Without this, dynamic, state-aware response-format guidance must live in the
system prompt (far from the action) or be duplicated/hard-coded per skill.
With it, skills become a clean place to put late-context, state-aware
instructions. Not time-critical, but it removes a recurring inconvenience when
building skills.

Willingness to contribute

Yes — I have an implementation ready and will open a PR alongside this issue.

---

🟡 Recommended Information

Describe Alternatives You've Considered

• InstructionProvider on the agent: works for the system prompt but not for
  skill bodies, and doesn't address late-context placement via load_skill.
• Pre-rendering skills before registration: requires state at load time,
  which isn't available per-invocation.
• Always-on injection in load_skill: rejected — breaks existing skills
  that contain literal {...} braces.

Proposed API / Implementation

# tools/skill_toolset.py  (LoadSkillTool.run_async)
instructions = skill.instructions
if skill.frontmatter.metadata.get("adk_inject_session_state"):
    try:
        instructions = await inject_session_state(instructions, tool_context)
    except (KeyError, ValueError) as e:
        return {
            "error": f"Failed to inject session state into skill "
                     f"'{skill_name}' instructions: {e}",
            "error_code": "STATE_INJECTION_ERROR",
        }
return {"skill_name": skill_name, "instructions": instructions, ...}

Plus validation in Frontmatter that adk_inject_session_state is a bool.
ToolContext is a ReadonlyContext, so it satisfies inject_session_state
directly.

Additional Context

Scope limited to load_skill instructions; load_skill_resource content could
follow the same pattern later.

[adk-bot]

I have analyzed the GitHub issue google/adk-python#5973 following the adk-issue-analyze guidelines.

The full, detailed triage report has been saved to the workspace artifact:

• analysis_results.md

Executive Summary

1. What is broken?
   • Standard skill instructions returned by the load_skill tool do not support dynamic state or artifact variable injection. As a result, developers cannot cleanly inject session context (such as preferred user language or response schemas) into late-context instructions.
2. Is there a linked PR that fixes this issue?
   • Yes, there is an open PR: PR #5974 (feat(skills): Allow opt-in session state injection in skill instructions), submitted by the issue author.
3. Recommendation: Should Fix (High Priority)
   • The proposed solution implements a clean, opt-in flag adk_inject_session_state inside the skill's Frontmatter metadata. It is fully backward-compatible, well-tested, and adheres completely to adk-architecture and adk-style conventions.
   • The PR currently awaits standard Contributor License Agreement (CLA) signing by the author. Once the CLA verification succeeds, the pull request is ready to be merged.

Please let me know if you would like me to assist with the code review process or if you have any questions!