1# Skills in Toolbox
2 
3How to attach, list, remove, and version **skills** (reusable behavioral guidelines) in a Foundry toolbox using `azd ai toolbox skill`.
4 
5Skills 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).
6 
7> 📘 For skill resource CRUD (`azd ai skill create/update/list/download/delete`), see [skill-management.md](skill-management.md).
8>
9> 📘 For consuming skills in agent code (Agent Framework SDK integration, progressive disclosure, `load_skill`), see [use-skills-in-hosted-agent.md](use-skills-in-hosted-agent.md).
10 
11## Install
12 
13```bash
14azd extension install azure.ai.skills       # skill CRUD
15azd extension install azure.ai.toolboxes    # toolbox management
16```
17 
18## CLI surface — `azd ai toolbox skill`
19 
20| Command | What it does |
21|---------|--------------|
22| `azd ai toolbox skill add <toolbox> <skill>` | Attach skill (follows default version); new immutable toolbox version. |
23| `azd ai toolbox skill add <toolbox> <skill>@<ver>` | Attach skill pinned to a specific version. |
24| `azd ai toolbox skill add <toolbox> --from-file <path>` | Attach multiple skills from JSON/YAML. |
25| `azd ai toolbox skill list <toolbox>` | List skill references in the toolbox. |
26| `azd ai toolbox skill remove <toolbox> <skill> [<skill>...] [--force]` | Detach skills; one new version. |
27 
28> 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.
29 
30## Recipe: attach skill to existing toolbox
31 
32```bash
33# 1. Create the skill (if not already uploaded)
34azd ai skill create support-style --file ./skills/support-style/
35 
36# 2. Attach to toolbox
37azd ai toolbox skill add agent-tools support-style
38 
39# 3. Promote the new toolbox version
40azd ai toolbox publish agent-tools <new-version>
41 
42# 4. Verify
43azd ai toolbox skill list agent-tools
44```
45 
46## Recipe: include skills in toolbox creation
47 
48Skills are a top-level `skills[]` array in the `--from-file` manifest:
49 
50```yaml
51description: Agent toolbox with skills
52connections:
53  - name: my-mcp-server
54skills:
55  - name: support-style
56  - name: escalation-policy
57    version: "2"         # pin to version 2; omit to follow default
58tools:
59  - type: web_search
60    name: web
61```
62 
63```bash
64azd ai toolbox create agent-tools --from-file tools.yaml
65```
66 
67When `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.
68 
69## Recipe: remove skill from toolbox
70 
71```bash
72# Remove one or more skills (one new version)
73azd ai toolbox skill remove agent-tools my-skill --force
74 
75# Promote
76azd ai toolbox publish agent-tools <new-version>
77```
78 
79Removing the last skill is allowed (the toolbox can still have connections and tools).
80 
81## Versioning behavior
82 
83- Each `skill add` / `skill remove` creates a new immutable toolbox version (default unchanged until `publish`).
84- Skill references without a pinned version follow the skill's `default_version` at read time.
85- Skill references with a pinned version (`skill@2`) stay on that version regardless of skill updates.
86- To rollback: `azd ai toolbox publish <toolbox> <previous-version>`.
87 
88## How skills appear at runtime (raw MCP protocol)
89 
90Skills are exposed through the MCP **resources** protocol (not `tools/list`):
91 
92- `resources/list` advertises each skill as a resource with a `skill://<name>/SKILL.md` URI (name + description).
93- `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.
94- `resources/read` with a `skill://` URI retrieves the full `SKILL.md` body on demand.
95 
96### Raw MCP call examples
97 
98```bash
99# Get a bearer token
100TOK=$(az account get-access-token --resource "https://ai.azure.com" --query accessToken -o tsv)
101 
102# Foundry project endpoint (no trailing slash)
103PE="<FOUNDRY_PROJECT_ENDPOINT>"
104URL="$PE/toolboxes/<toolbox>/mcp?api-version=v1"
105# List available skills (resources/list)
106curl -s -X POST "$URL" \
107  -H "Authorization: Bearer $TOK" \
108  -H "Content-Type: application/json" \
109  -H "Foundry-Features: Toolboxes=V1Preview" \
110  -d '{"jsonrpc":"2.0","id":1,"method":"resources/list","params":{}}'
111 
112# Read skill index
113curl -s -X POST "$URL" \
114  -H "Authorization: Bearer $TOK" \
115  -H "Content-Type: application/json" \
116  -H "Foundry-Features: Toolboxes=V1Preview" \
117  -d '{"jsonrpc":"2.0","id":2,"method":"resources/read","params":{"uri":"skill://index.json"}}'
118 
119# Read a specific skill's content
120curl -s -X POST "$URL" \
121  -H "Authorization: Bearer $TOK" \
122  -H "Content-Type: application/json" \
123  -H "Foundry-Features: Toolboxes=V1Preview" \
124  -d '{"jsonrpc":"2.0","id":3,"method":"resources/read","params":{"uri":"skill://my-skill/SKILL.md"}}'
125```
126 
127> 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](use-skills-in-hosted-agent.md).
128 
129## Skill + Tool Search interaction
130 
131When `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.
132 
133## Skills via Toolbox vs SkillsProvider: when to use which
134 
135See [use-skills-in-hosted-agent.md § Choosing an approach](use-skills-in-hosted-agent.md) for a comparison table.
136