feat(skills): add include_list_skills to inject the L1 catalog without list_skills

[thomaslprr]

Required Information

Is your feature request related to a specific problem?

list_skills costs an extra model turn before load_skill. The only way to inject the L1 catalog as <available_skills> XML was to drop ListSkillsTool from the private _tools list. tool_filter is an allowlist, so hiding just list_skills means naming every other skill tool.

Describe the Solution You'd Like

A public SkillToolset(include_list_skills=True|False) flag.

• True (default): keep list_skills.
• False: hide list_skills and inject the local L1 catalog into the system instruction so the model can call load_skill directly.

Impact on your work

Needed to load skills without a discovery round trip, without mutating private attributes.

Willingness to contribute

Yes. I will submit a PR.

Recommended Information

Describe Alternatives You've Considered

• Mutating skill_tools._tools (works, not a public API).
• tool_filter=["load_skill", ...] (works since the tool_filter/instruction fix, but is an allowlist).

Proposed API / Implementation

SkillToolset(skills=[shopping_advice_skill], include_list_skills=False)

[vadakattu]

+💯 for this proposal. Beyond saving an extra turn, this is also a reliability issue.

When list_skills suppresses the <available_skills> XML catalog, the model receives no skill names in context. However, ADK's default injected instructions state:

"1. If a skill seems relevant to the current user query, you MUST use the load_skill tool with skill_name="<SKILL_NAME>" to read its full instructions before proceeding."

Because the instructions never direct the model to call list_skills first, the model is instructed to supply a <SKILL_NAME> it has never seen. In practice, models frequently guess their own agent.name (e.g., load_skill(skill_name=agent.name)), resulting in immediate SKILL_NOT_FOUND errors.

A bolder fix would be to include the L1 catalog (<available_skills>) by default, akin to how tools always expose their names, descriptions, and argument schemas in the model declaration. Dynamic discovery (list_skills / search_skills) only really makes sense for large, remote registries where context limits warrant pagination. For locally registered skills, L1 metadata should be present upfront so load_skill works reliably out of the box.

[thomaslprr]

+💯 for this proposal. Beyond saving an extra turn, this is also a reliability issue.

When list_skills suppresses the <available_skills> XML catalog, the model receives no skill names in context. However, ADK's default injected instructions state:

"1. If a skill seems relevant to the current user query, you MUST use the load_skill tool with skill_name="<SKILL_NAME>" to read its full instructions before proceeding."

Because the instructions never direct the model to call list_skills first, the model is instructed to supply a <SKILL_NAME> it has never seen. In practice, models frequently guess their own agent.name (e.g., load_skill(skill_name=agent.name)), resulting in immediate SKILL_NOT_FOUND errors.

A bolder fix would be to include the L1 catalog (<available_skills>) by default, akin to how tools always expose their names, descriptions, and argument schemas in the model declaration. Dynamic discovery (list_skills / search_skills) only really makes sense for large, remote registries where context limits warrant pagination. For locally registered skills, L1 metadata should be present upfront so load_skill works reliably out of the box.

Thanks, I completely agree this is a reliability issue, not just a latency win.

Making EAGER the default for local skills (and keeping list/search for large or remote registries) also sounds right to me. Worth being careful though: flipping the default could be a breaking change for anyone already relying on list_skills / the current prompt shape.

Longer term, I see two follow-ups (phase 2):

1. Either make EAGER the default for local skills, or adapt the default system instruction per discovery mode so it doesn't tell the model to call load_skill with a name it has never seen.
2. Revisit the L1 catalog format ; XML works, but it may not be the most token-efficient representation.

For this PR, I'd keep the scope to landing the discovery mode itself and follow whatever default the maintainers prefer.