Skills in Toolbox

How to attach, list, remove, and version skills (reusable behavioral guidelines) in a Foundry toolbox using azd ai toolbox skill.

Skills are not a tool type — they live in a separate skills[] array in the toolbox manifest. At the MCP level, skills are exposed as resources (resources/list / resources/read with skill:// URIs).

📘 For skill resource CRUD (azd ai skill create/update/list/download/delete), see skill-management.md.

>

📘 For consuming skills in agent code (Agent Framework SDK integration, progressive disclosure, load_skill), see use-skills-in-hosted-agent.md.

Install

azd extension install azure.ai.skills       # skill CRUD
azd extension install azure.ai.toolboxes    # toolbox management

CLI surface — azd ai toolbox skill

Every skill add / skill remove creates a new immutable toolbox version but does not change the default. Run azd ai toolbox publish <toolbox> <version> to promote.

Recipe: attach skill to existing toolbox

# 1. Create the skill (if not already uploaded)
azd ai skill create support-style --file ./skills/support-style/

# 2. Attach to toolbox
azd ai toolbox skill add agent-tools support-style

# 3. Promote the new toolbox version
azd ai toolbox publish agent-tools <new-version>

# 4. Verify
azd ai toolbox skill list agent-tools

Recipe: include skills in toolbox creation

Skills are a top-level skills[] array in the --from-file manifest:

description: Agent toolbox with skills
connections:
  - name: my-mcp-server
skills:
  - name: support-style
  - name: escalation-policy
    version: "2"         # pin to version 2; omit to follow default
tools:
  - type: web_search
    name: web

azd ai toolbox create agent-tools --from-file tools.yaml

When version is omitted from a skill entry, the toolbox resolves the skill's default_version at read time. If the skill is updated (azd ai skill update), agents on the consumer endpoint pick up the new content without a toolbox republish.

Recipe: remove skill from toolbox

# Remove one or more skills (one new version)
azd ai toolbox skill remove agent-tools my-skill --force

# Promote
azd ai toolbox publish agent-tools <new-version>

Removing the last skill is allowed (the toolbox can still have connections and tools).

Versioning behavior

• Each skill add / skill remove creates a new immutable toolbox version (default unchanged until publish).
• Skill references without a pinned version follow the skill's default_version at read time.
• Skill references with a pinned version (skill@2) stay on that version regardless of skill updates.
• To rollback: azd ai toolbox publish <toolbox> <previous-version>.

How skills appear at runtime (raw MCP protocol)

Skills are exposed through the MCP resources protocol (not tools/list):

• resources/list advertises each skill as a resource with a skill://<name>/SKILL.md URI (name + description).
• resources/list also exposes skill://index.json — a discovery index listing every skill on the toolbox version with URLs to read each skill's SKILL.md and (for multi-file skills) its ZIP archive.
• resources/read with a skill:// URI retrieves the full SKILL.md body on demand.

Raw MCP call examples

# Get a bearer token
TOK=$(az account get-access-token --resource "https://ai.azure.com" --query accessToken -o tsv)

# Foundry project endpoint (no trailing slash)
PE="<FOUNDRY_PROJECT_ENDPOINT>"
URL="$PE/toolboxes/<toolbox>/mcp?api-version=v1"
# List available skills (resources/list)
curl -s -X POST "$URL" \
  -H "Authorization: Bearer $TOK" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Toolboxes=V1Preview" \
  -d '{"jsonrpc":"2.0","id":1,"method":"resources/list","params":{}}'

# Read skill index
curl -s -X POST "$URL" \
  -H "Authorization: Bearer $TOK" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Toolboxes=V1Preview" \
  -d '{"jsonrpc":"2.0","id":2,"method":"resources/read","params":{"uri":"skill://index.json"}}'

# Read a specific skill's content
curl -s -X POST "$URL" \
  -H "Authorization: Bearer $TOK" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Toolboxes=V1Preview" \
  -d '{"jsonrpc":"2.0","id":3,"method":"resources/read","params":{"uri":"skill://my-skill/SKILL.md"}}'

For how the Agent Framework SDK wraps these MCP resources into a load_skill tool for progressive disclosure, see use-skills-in-hosted-agent.md.

Skill + Tool Search interaction

When toolbox_search_preview is enabled, regular tools are hidden from tools/list and discovered via tool_search. Skills remain in resources/list regardless of this setting — they are not affected by Tool Search.

Skills via Toolbox vs SkillsProvider: when to use which

See use-skills-in-hosted-agent.md § Choosing an approach for a comparison table.