Use Skills in a Hosted Agent

How to consume Foundry skills (reusable behavioral guidelines) from hosted agent code. Two approaches:

1. Direct download — agent downloads skill ZIPs at startup via the Skills API, wires SkillsProvider (Python) or AgentSkillsProvider (C#).
2. Via Toolbox MCP — agent connects to a toolbox MCP endpoint that exposes skills as resources, wires AgentSkillsProviderBuilder.UseMcpSkills (C#) or MCPStreamableHTTPTool (Python).

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

>

📘 For attaching skills to a toolbox (azd ai toolbox skill add/remove/list) and the raw MCP protocol, see skill-toolbox.md.

How progressive disclosure works

The Agent Framework SDK injects skill names/descriptions into the system prompt (~100 tokens each) and synthesizes a load_skill tool. When the model determines a skill is relevant, it calls load_skill(name) to retrieve the full body on demand — keeping context usage low.

Choosing an approach

Approach 1: Direct Download

Downloads skill ZIPs at startup, extracts to disk, builds provider. The SDK synthesizes load_skill for the model.

Env vars

Python

The sample downloads each skill via project.beta.skills.download(), extracts the ZIP (with zip-slip guard), and attaches a SkillsProvider to the agent as a context_providers entry.

Key classes: SkillsProvider.from_paths(), AIProjectClient (with allow_preview=True).

Full working sample: 12-foundry-skills (Python)

C#

The sample uses AgentAdministrationClient (with FoundryFeaturesPolicy for the Skills=V1Preview header) to download skills via ProjectAgentSkills.DownloadSkillAsync(), extracts ZIPs, and attaches an AgentSkillsProvider via AIContextProviders.

Key classes: AgentSkillsProvider, ProjectAgentSkills, AgentAdministrationClient.

Full working sample: agent-skills (C#)

Approach 2: Via Toolbox MCP

Skills attached to a toolbox are discovered dynamically via resources/list and wrapped into load_skill. See skill-toolbox.md for MCP protocol details.

Env vars

C#

The sample creates an McpClient pointing at the toolbox endpoint, then builds a skills provider via AgentSkillsProviderBuilder().UseMcpSkills(mcpClient).Build(). The framework handles the advertise → load → read lifecycle automatically.

Key classes: AgentSkillsProviderBuilder, McpClient, BearerTokenHandler.

Full working sample: foundry-toolbox-mcp-skills (C#)

Deployment

Provision skills

Skills must exist in the same project the deployed agent connects to:

azd ai skill create support-style --file ./skills/support-style/ --force
azd ai skill create escalation-policy --file ./skills/escalation-policy/ --force

Direct download approach

azd env set SKILL_NAMES "support-style,escalation-policy"

agent.yaml:

environment_variables:
  - name: SKILL_NAMES
    value: ${SKILL_NAMES}

Toolbox approach

# Create toolbox with skills attached
cat > tools.yaml <<'EOF'
description: Agent toolbox with skills and tools
skills:
  - name: support-style
  - name: escalation-policy
tools:
  - type: web_search
    name: web
EOF
azd ai toolbox create agent-tools --from-file tools.yaml

# Wire endpoint env var
ENDPOINT=$(azd ai toolbox show agent-tools -o json | jq -r .endpoint)
azd env set TOOLBOX_ENDPOINT "$ENDPOINT"

agent.yaml:

environment_variables:
  - name: TOOLBOX_ENDPOINT
    value: ${TOOLBOX_ENDPOINT}

Then azd deploy.

RBAC

The deployed agent's managed identity needs Foundry User on the project:

az role assignment create \
  --assignee <managed-identity-object-id> \
  --role "Foundry User" \
  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>

Verify end-to-end

azd ai agent run
azd ai agent invoke --local "Hi, can I return my tent within 30 days?"

Samples

Troubleshooting