AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

microsoft-foundry

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent, managed harness agent, Copilot harness, voice agent, create/update/invoke/evaluate agent, add tool to agent, agent insights, batch/continuous eval, continuous monitoring, agent CI/CD, optimize/improve prompt, optimize agent instructions, Agent Optimizer, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare).

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--microsoft-foundry at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 151

foundry-agent/create/references/skills/skill-manage.md

Skills (azd ai)

How to create, manage, and version skills (reusable behavioral guidelines) in a Foundry project using azd ai skill CLI and SDK.

A 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.

Install the extension

azd extension install azure.ai.skills

Skill authoring format

Each skill lives in its own directory with SKILL.md at the root:

skills/
  my-skill/
    SKILL.md       # YAML front matter + Markdown body
---
name: my-skill-name
description: What this skill does and when the agent should load it
---

# My Skill

Instructions the agent follows when this skill is loaded on demand...

The name and description values must be unquoted in YAML front matter — quoting causes HTTP 500 on import.

The 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 skill-attach.md § How progressive disclosure works for details.

CLI surface — azd ai skill

| Command | What it does | |---------|--------------| | azd ai skill create <name> --file <path> | Create skill + publish v1. Accepts SKILL.md, .zip, or directory. | | azd ai skill create <name> --description "..." --instructions "..." | Inline create (no file). | | azd ai skill create <name> --file <path> --force | Delete existing + recreate. Safe to re-run after edits. | | azd ai skill update <name> --file <path> | New immutable version, promoted to default. | | azd ai skill update <name> --set-default-version <ver> | Repoint default (rollback) without uploading new content. | | azd ai skill show <name> | Show metadata (default_version, latest_version). | | azd ai skill list | List skills in the project. | | azd ai skill download <name> | Extract to ./.agents/skills/<name>/. | | azd ai skill download <name> --version <ver> | Download a specific version. | | azd ai skill download <name> --raw | Write raw ZIP without extracting. | | azd ai skill delete <name> [--force] | Delete skill. |

Every mutation creates a new immutable version. create promotes v1 to default; update promotes the new version to default.

Four mutually exclusive input modes for create and update:

  1. Directory: --file ./skills/my-skill/ (CLI packages as ZIP; requires SKILL.md at root)
  2. SKILL.md: --file ./SKILL.md (CLI parses YAML front matter + body)
  3. ZIP: --file ./skill.zip (uploaded as multipart/form-data)
  4. Inline: --description "..." --instructions "..." (no file)

Recipe: create a skill

azd ai skill create support-style --file ./skills/support-style/

Recipe: batch provision (safe to re-run)

for dir in skills/*/; do
  name=$(basename "$dir")
  azd ai skill create "$name" --file "$dir" --force
done

Recipe: update a skill

# Edit SKILL.md locally, then:
azd ai skill update my-skill --file ./skills/my-skill/

After update:

  • Toolbox skill references (without pinned version) follow the new default_version — live immediately, no toolbox republish needed.
  • SkillsProvider downloads at agent startup — redeploy agent to pick up the new version.

Recipe: rollback a skill version

azd ai skill update my-skill --set-default-version 1

Python SDK operations

For programmatic skill CRUD (create, list, download, delete) via the Python SDK, see the provisioning script in the sample:

provision_skills.py — read the script source for the current API surface and usage patterns.

The Skills SDK API is in preview and may change across versions. Always refer to the sample for the latest usage.

RBAC

Skills require Foundry User on the Foundry project scope (for both the developer identity and the deployed agent's managed identity).

Versioning

  • Every create produces version 1 as the default.
  • Every update creates a new immutable version and promotes it to default.
  • azd ai skill update <name> --set-default-version <ver> repoints without uploading new content.
  • Toolbox skill references without a pinned version follow the skill's default_version.
  • Toolbox skill references with a pinned version (skill@2) stay on that version regardless.
  • SkillsProvider downloads the default_version at agent startup.

Troubleshooting

| Symptom | Likely cause | Fix | |---------|------------|-----| | HTTP 500 on skill create | Quoted name or description in YAML front matter | Remove quotes from front matter values | | 403 Forbidden | Missing RBAC | Grant Foundry User on the project scope | | azd ai skill not recognized | Extension not installed | azd extension install azure.ai.skills | | Agent still uses old skill content after update | Toolbox skill pinned to old version, or skills provider caches at startup | Use consumer endpoint (no version pin), or redeploy agent |

References