1# Use Skills in a Hosted Agent
2 
3How to consume Foundry **skills** (reusable behavioral guidelines) from hosted agent code. Two approaches:
4 
51. **Direct download** — agent downloads skill ZIPs at startup via the Skills API, wires `SkillsProvider` (Python) or `AgentSkillsProvider` (C#).
62. **Via Toolbox MCP** — agent connects to a toolbox MCP endpoint that exposes skills as resources, wires `AgentSkillsProviderBuilder.UseMcpSkills` (C#) or `MCPStreamableHTTPTool` (Python).
7 
8> 📘 For skill resource CRUD (`azd ai skill create/update/list/download/delete`), see [skill-management.md](skill-management.md).
9>
10> 📘 For attaching skills to a toolbox (`azd ai toolbox skill add/remove/list`) and the raw MCP protocol, see [skill-toolbox.md](skill-toolbox.md).
11 
12## How progressive disclosure works
13 
14The 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.
15 
16## Choosing an approach
17 
18| | Direct Download | Via Toolbox MCP |
19|--|---|---|
20| How | Downloads ZIPs at startup, builds provider from local files | Connects to toolbox MCP; SDK reads `resources/list` → `load_skill` |
21| Provider | `SkillsProvider.from_paths()` / `AgentSkillsProvider(dir)` | `MCPStreamableHTTPTool` / `AgentSkillsProviderBuilder.UseMcpSkills()` |
22| Skill updates | Redeploy agent | Consumer endpoint picks up new version automatically |
23| Header | `Foundry-Features: Skills=V1Preview` | `Foundry-Features: Toolboxes=V1Preview` |
24| When to use | No toolbox; need explicit version control | Already have a toolbox; want dynamic updates |
25 
26---
27 
28## Approach 1: Direct Download
29 
30Downloads skill ZIPs at startup, extracts to disk, builds provider. The SDK synthesizes `load_skill` for the model.
31 
32### Env vars
33 
34| Variable | Purpose |
35|----------|---------|
36| `FOUNDRY_PROJECT_ENDPOINT` | Project endpoint for SDK calls |
37| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Model deployment for the agent |
38| `SKILL_NAMES` | Comma-separated skill names to download |
39 
40### Python
41 
42The 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.
43 
44**Key classes:** `SkillsProvider.from_paths()`, `AIProjectClient` (with `allow_preview=True`).
45 
46Full working sample: [12-foundry-skills (Python)](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/12-foundry-skills)
47 
48### C#
49 
50The sample uses `AgentAdministrationClient` (with `FoundryFeaturesPolicy` for the `Skills=V1Preview` header) to download skills via `ProjectAgentSkills.DownloadSkillAsync()`, extracts ZIPs, and attaches an `AgentSkillsProvider` via `AIContextProviders`.
51 
52**Key classes:** `AgentSkillsProvider`, `ProjectAgentSkills`, `AgentAdministrationClient`.
53 
54Full working sample: [agent-skills (C#)](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/hosted-agents/agent-framework/agent-skills)
55 
56---
57 
58## Approach 2: Via Toolbox MCP
59 
60Skills attached to a toolbox are discovered dynamically via `resources/list` and wrapped into `load_skill`. See [skill-toolbox.md](skill-toolbox.md) for MCP protocol details.
61 
62### Env vars
63 
64| Variable | Purpose |
65|----------|---------|
66| `FOUNDRY_PROJECT_ENDPOINT` | Project endpoint for SDK calls |
67| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Model deployment for the agent |
68| `TOOLBOX_ENDPOINT` | Full toolbox MCP endpoint URL (Python preferred) |
69| `TOOLBOX_NAME` | Toolbox name — SDK constructs endpoint (C# preferred) |
70 
71### C#
72 
73The 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.
74 
75**Key classes:** `AgentSkillsProviderBuilder`, `McpClient`, `BearerTokenHandler`.
76 
77Full working sample: [foundry-toolbox-mcp-skills (C#)](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/hosted-agents/agent-framework/foundry-toolbox-mcp-skills)
78 
79---
80 
81## Deployment
82 
83### Provision skills
84 
85Skills must exist in the **same project** the deployed agent connects to:
86 
87```bash
88azd ai skill create support-style --file ./skills/support-style/ --force
89azd ai skill create escalation-policy --file ./skills/escalation-policy/ --force
90```
91 
92### Direct download approach
93 
94```bash
95azd env set SKILL_NAMES "support-style,escalation-policy"
96```
97 
98`agent.yaml`:
99 
100```yaml
101environment_variables:
102  - name: SKILL_NAMES
103    value: ${SKILL_NAMES}
104```
105 
106### Toolbox approach
107 
108```bash
109# Create toolbox with skills attached
110cat > tools.yaml <<'EOF'
111description: Agent toolbox with skills and tools
112skills:
113  - name: support-style
114  - name: escalation-policy
115tools:
116  - type: web_search
117    name: web
118EOF
119azd ai toolbox create agent-tools --from-file tools.yaml
120 
121# Wire endpoint env var
122ENDPOINT=$(azd ai toolbox show agent-tools -o json | jq -r .endpoint)
123azd env set TOOLBOX_ENDPOINT "$ENDPOINT"
124```
125 
126`agent.yaml`:
127 
128```yaml
129environment_variables:
130  - name: TOOLBOX_ENDPOINT
131    value: ${TOOLBOX_ENDPOINT}
132```
133 
134Then `azd deploy`.
135 
136### RBAC
137 
138The deployed agent's managed identity needs **Foundry User** on the project:
139 
140```bash
141az role assignment create \
142  --assignee <managed-identity-object-id> \
143  --role "Foundry User" \
144  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>
145```
146 
147## Verify end-to-end
148 
149```bash
150azd ai agent run
151azd ai agent invoke --local "Hi, can I return my tent within 30 days?"
152```
153 
154## Samples
155 
156| Language | Approach | Sample |
157|----------|----------|--------|
158| Python | Direct download | [12-foundry-skills](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/12-foundry-skills) |
159| Python | Via Toolbox | [04-foundry-toolbox](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox) |
160| C# | Direct download | [agent-skills](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/hosted-agents/agent-framework/agent-skills) |
161| C# | Via Toolbox MCP | [foundry-toolbox-mcp-skills](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/hosted-agents/agent-framework/foundry-toolbox-mcp-skills) |
162 
163## Troubleshooting
164 
165| Symptom | Likely cause | Fix |
166|---------|------------|-----|
167| `SKILL.md not found` after download | ZIP doesn't contain `SKILL.md` at root | Create skill from directory with `SKILL.md` at root |
168| `403` on skill download | Identity missing RBAC | Grant **Foundry User** on project scope |
169| Agent ignores skills | Descriptions don't match user queries | Improve `description` in SKILL.md front matter |
170| Skills load but agent doesn't follow | Instructions vague or conflicting | Refine skill body; add canary token to verify loading |
171| `asyncio.TimeoutError` (Python) | Slow network or large packages | Increase bootstrap timeout (default 60s) |
172| `allow_preview` error (Python) | SDK client missing preview flag | `AIProjectClient(allow_preview=True)` |
173| HTTP 500 on skill download (C#) | Missing feature header | Add `FoundryFeaturesPolicy` for `Skills=V1Preview` |
174| `SKILL_NAMES` not in deployed agent | Env var missing from `agent.yaml` | Add to `environment_variables[]`, redeploy |
175| MCP timeout (Toolbox) | Auth token expired or wrong scope | Use `https://ai.azure.com/.default`; refresh per request |
176| Skills not discovered from toolbox | New version not published | `azd ai toolbox publish <toolbox> <version>` |
177| `Invalid skill name 'xxx:download'` | SDK bug in beta.2 | Use CLI or `agent-framework-foundry` wrapper |
178