Azure AI Foundry Toolbox Skills Not Being Discovered or Read by Agents

Yes. Skill discovery through a Toolbox is supported in the current preview, but several conditions must be met for the agent runtime to discover and load the skill.

Key requirements:

1. Skill and toolbox must be in the same Foundry project Cross-project skill references are not supported. If the skill was created in a different Foundry project, the toolbox can’t expose it correctly to the agent runtime.
2. The toolbox version must actually include the skill reference A toolbox version can contain tools, skills, or both. When attaching a skill, the reference uses the skill name and optionally a version.
   • If version is omitted, the toolbox uses the skill’s default_version.
   • If version is specified, it pins that immutable version.
3. The client/runtime must support MCP Resources Skills attached to a toolbox are exposed through the toolbox MCP endpoint as MCP Resources, not ordinary callable tools. The agent framework or MCP client must support the MCP Resources protocol to auto-discover and load them.
4. Verify discovery at the toolbox MCP endpoint The documented validation step is to call resources/list on the toolbox MCP endpoint and confirm the skill name appears. If the skill does not appear there, the problem is in toolbox/skill attachment or publishing, not in prompting.
5. Publish the toolbox version after imperative changes If the skill was added with imperative azd commands, the toolbox version must be published before clients can discover the attached skill.
6. Skill package and markdown must be valid If the skill definition itself is malformed, creation may succeed inconsistently or the skill may not behave correctly. The documented checks are:
   • SKILL.md must contain unquoted name and description values.
   • name must use lowercase letters, numbers, and hyphens.
   • The file name must match the skill name supplied to the CLI.
   • If uploaded as an archive, use a ZIP containing SKILL.md, or supported individual files.
7. For downloaded/hosted agent loading scenarios, folder layout matters If the issue is with a hosted agent loading a downloaded skill package, each skill must be extracted into its own subdirectory such as skills/greeting/SKILL.md, then the agent must be restarted so it reads the skill at startup.

What the current behavior means:

• If the agent does not “see” the skill, that is usually a discovery problem, not an instruction problem.
• Prompting the agent to “read the skill” will not fix discovery if the skill is not being exposed as an MCP Resource.
• This is not documented as an unsupported scenario. The preview documentation explicitly states that skills can be attached to a toolbox and made available to agents through the toolbox MCP endpoint.

Recommended troubleshooting path:

1. Confirm the skill and toolbox are in the same Foundry project.
2. Confirm the toolbox version includes the skill reference by name, and the intended version/default version is valid.
3. If the skill was added after toolbox creation, publish the toolbox version.
4. Validate the skill appears from the toolbox MCP endpoint via resources/list.
5. Validate the skill definition format in SKILL.md:
   • unquoted name and description
   • lowercase/hyphenated name
   • matching file name
6. If the skill was uploaded as a ZIP, confirm the archive shape is supported.
7. If using a hosted agent with downloaded skills, confirm the extracted folder structure and restart the agent.
8. If discovery still fails, review project networking, especially if private networking is enabled.

Based on the documented behavior, the most likely causes are:

• skill and toolbox are in different projects
• toolbox version was not published after adding the skill
• runtime/client does not support MCP Resources
• the skill package or SKILL.md structure is invalid

• Create and manage a toolbox in Foundry (azd)
• Use skills in Foundry (preview) (azd)
• Create and manage a toolbox in Foundry (rest-api)