1# Skills (azd ai)
2 
3How to create, manage, and version **skills** (reusable behavioral guidelines) in a Foundry project using `azd ai skill` and the Python SDK.
4 
5A **skill** is a Markdown file with YAML front matter (`SKILL.md`), uploaded to a Foundry project, and attached to agents at runtime. Skills enable updating agent behavior **without code changes**.
6 
7> 📘 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).
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 the extension
12 
13```bash
14azd extension install azure.ai.skills
15```
16 
17## Skill authoring format
18 
19Each skill lives in its own directory with `SKILL.md` at the root:
20 
21```
22skills/
23  my-skill/
24    SKILL.md       # YAML front matter + Markdown body
25```
26 
27```yaml
28---
29name: my-skill-name
30description: What this skill does and when the agent should load it
31---
32 
33# My Skill
34 
35Instructions the agent follows when this skill is loaded on demand...
36```
37 
38> **The `name` and `description` values must be unquoted** in YAML front matter — quoting causes HTTP 500 on import.
39 
40The `description` field drives skill discovery at runtime: the Agent Framework SDK uses it to decide when to load the skill. Write descriptions that clearly state **when** the agent should use the skill. See [use-skills-in-hosted-agent.md § How progressive disclosure works](use-skills-in-hosted-agent.md) for details.
41 
42## CLI surface — `azd ai skill`
43 
44| Command | What it does |
45|---------|--------------|
46| `azd ai skill create <name> --file <path>` | Create skill + publish v1. Accepts SKILL.md, .zip, or directory. |
47| `azd ai skill create <name> --description "..." --instructions "..."` | Inline create (no file). |
48| `azd ai skill create <name> --file <path> --force` | Delete existing + recreate. Safe to re-run after edits. |
49| `azd ai skill update <name> --file <path>` | New immutable version, promoted to default. |
50| `azd ai skill update <name> --set-default-version <ver>` | Repoint default (rollback) without uploading new content. |
51| `azd ai skill show <name>` | Show metadata (default_version, latest_version). |
52| `azd ai skill list` | List skills in the project. |
53| `azd ai skill download <name>` | Extract to `./.agents/skills/<name>/`. |
54| `azd ai skill download <name> --version <ver>` | Download a specific version. |
55| `azd ai skill download <name> --raw` | Write raw ZIP without extracting. |
56| `azd ai skill delete <name> [--force]` | Delete skill. |
57 
58Every mutation creates a new immutable version. `create` promotes v1 to default; `update` promotes the new version to default.
59 
60Four mutually exclusive input modes for `create` and `update`:
61 
621. **Directory:** `--file ./skills/my-skill/` (CLI packages as ZIP; requires `SKILL.md` at root)
632. **SKILL.md:** `--file ./SKILL.md` (CLI parses YAML front matter + body)
643. **ZIP:** `--file ./skill.zip` (uploaded as multipart/form-data)
654. **Inline:** `--description "..." --instructions "..."` (no file)
66 
67## Recipe: create a skill
68 
69```bash
70azd ai skill create support-style --file ./skills/support-style/
71```
72 
73## Recipe: batch provision (safe to re-run)
74 
75```bash
76for dir in skills/*/; do
77  name=$(basename "$dir")
78  azd ai skill create "$name" --file "$dir" --force
79done
80```
81 
82## Recipe: update a skill
83 
84```bash
85# Edit SKILL.md locally, then:
86azd ai skill update my-skill --file ./skills/my-skill/
87```
88 
89After update:
90- Toolbox skill references (without pinned version) follow the new `default_version` — live immediately, no toolbox republish needed.
91- `SkillsProvider` downloads at agent startup — redeploy agent to pick up the new version.
92 
93## Recipe: rollback a skill version
94 
95```bash
96azd ai skill update my-skill --set-default-version 1
97```
98 
99## Python SDK operations
100 
101The SDK uses `AIProjectClient.beta.skills` (preview API surface, requires `allow_preview=True`).
102 
103```python
104import os
105from azure.ai.projects.aio import AIProjectClient
106from azure.identity.aio import DefaultAzureCredential
107 
108async with (
109    DefaultAzureCredential() as credential,
110    AIProjectClient(
111        endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
112        credential=credential,
113        allow_preview=True,
114    ) as project,
115):
116    # Create from package (in-memory ZIP)
117    imported = await project.beta.skills.create_from_package(zip_bytes)
118 
119    # List
120    async for skill in project.beta.skills.list():
121        print(f"{skill.name}: {skill.description}")
122 
123    # Download
124    stream = await project.beta.skills.download("my-skill")
125    zip_bytes = b"".join([chunk async for chunk in stream])
126 
127    # Delete
128    await project.beta.skills.delete("my-skill")
129```
130 
131Full provisioning script: [provision_skills.py](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/12-foundry-skills/provision_skills.py).
132 
133## RBAC
134 
135Skills require **Foundry User** on the Foundry project scope (for both the developer identity and the deployed agent's managed identity).
136 
137## Versioning
138 
139- Every `create` produces version 1 as the default.
140- Every `update` creates a new immutable version and promotes it to default.
141- `azd ai skill update <name> --set-default-version <ver>` repoints without uploading new content.
142- Toolbox skill references without a pinned version follow the skill's `default_version`.
143- Toolbox skill references with a pinned version (`skill@2`) stay on that version regardless.
144- `SkillsProvider` downloads the `default_version` at agent startup.
145 
146## Troubleshooting
147 
148| Symptom | Likely cause | Fix |
149|---------|------------|-----|
150| HTTP 500 on skill create | Quoted `name` or `description` in YAML front matter | Remove quotes from front matter values |
151| `403 Forbidden` | Missing RBAC | Grant **Foundry User** on the project scope |
152| `azd ai skill` not recognized | Extension not installed | `azd extension install azure.ai.skills` |
153| Skill attached but agent doesn't use it | Description too vague for progressive disclosure | Improve `description` in SKILL.md front matter |
154| Agent still uses old skill content after `update` | Toolbox skill pinned to old version, or `SkillsProvider` caches at startup | Use consumer endpoint (no version pin), or redeploy agent |
155| `create_from_package` fails | SDK client missing preview flag | `AIProjectClient(allow_preview=True)` |
156