Use skills with Microsoft Foundry agents (preview)

Manage versioned skills in Microsoft Foundry using the Skills REST API. Author SKILL.md files, store them centrally with version control, and attach them to toolboxes or hosted agents.

Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

As agents grow beyond simple prototypes, teams accumulate behavioral guidelines that need to be consistent across every conversation. A support agent should always follow a specific escalation policy, a code-review agent should always apply the same checklist, and a sales agent should always respect certain messaging constraints. Embedding these guidelines directly in each agent’s system prompt or code creates duplication: when the policy changes, you need to update and redeploy every agent that uses it.

Skills solve this problem by decoupling behavioral guidelines from agent code. A skill is a SKILL.md file you author once, store centrally in Foundry through the versioned Skills API, and then deliver to agents in two modes: attach to a toolbox so any MCP client can discover and load them alongside tools, or download directly into a Hosted or local agent project for direct injection into each session’s context. Skills are versioned: every update creates a new immutable version while the parent skill tracks a default_version. When you update a skill, you create a new version, test it, then promote it to default without changing any agent code.

In this article, you learn how to:

• Create versioned skills and manage them through the Skills API.
• List, get, and delete skills and skill versions.
• Download skill content for use in a Hosted agent.
• Attach skills to a toolbox.

Feature support

Feature	REST API	Python	.NET	JavaScript	Toolbox	Hosted agent
Create skill version (JSON inline content)	??	??	??	??	N/A	N/A
Create skill version (ZIP file upload)	??	??	??	??	N/A	N/A
List, get, and delete skills and versions	??	??	??	??	N/A	N/A
Download skill content	??	??	??	??	N/A	N/A
Update skill default version	??	??	??	??	N/A	N/A
Attach skills to a toolbox	??	??	??	??	??	N/A

Prerequisites

• An active Microsoft Foundry project.
• RBAC: Foundry User role on the Foundry project.

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

Author a skill

Skills follow the Agent Skills specification format. A skill is a Markdown file with a YAML front matter block:

---
name: greeting
description: Generate a personalized greeting for the user.
---

# Greeting Skill

You're a friendly greeting assistant for Foundry Hosted Agents.

## Instructions

- Include the user's name if they provided one.
- Keep greetings concise, 1 to 2 sentences.
- Thank the user for trying out Foundry Hosted Agents and this sample skill.

Field	Required	Rules
name	Yes	Skill name used as the URL path key. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen or contain consecutive hyphens. Maximum 64 characters. Pattern: ^[a-z0-9]([a-z0-9/-]*[a-z0-9])?$. Must be unquoted in YAML.
description	Yes	One-liner shown in skill listings. Maximum 1,024 characters. Must be unquoted in YAML.
Body	Yes	Free Markdown. Becomes the skill’s injected instructions.

• The name and description values must be unquoted in the YAML front matter.
• Skill names follow the pattern ^[a-z0-9]([a-z0-9/-]*[a-z0-9])?$ (lowercase, numbers, and hyphens, no leading/trailing hyphens, max 64 characters). Invalid names cause an invalid_payload error on version creation.

Place each skill in its own subdirectory under the agent root directory. For example, greeting/SKILL.md, not SKILL.md at the root.

Attach skills to a toolbox (preview)

After you create skill versions, attach them to a toolbox version so any MCP client can discover and load them alongside tools from the same endpoint. Toolbox-based skill discovery is in preview and follows the Skills extension for the Model Context Protocol specification (SEP-2640).

Skills attached to a toolbox must exist in the same Foundry project. Cross-project references aren’t supported.

When an agent or MCP client connects to the toolbox endpoint, skills appear as MCP Resources. Clients that support the MCP Resources protocol call resources/list once at startup to discover all attached skills, then resources/read to download the content. Any MCP client — GitHub Copilot, Claude Code, or your own agent harness — can consume skills this way without any Foundry SDK.

For REST, Python, .NET, JavaScript, and azd examples of adding skill references to a toolbox version, see the Attach skills to a toolbox section in the toolbox article. The Azure Developer CLI exposes skill references both declaratively (a skills: block in azd ai toolbox create --from-file) and imperatively (azd ai toolbox skill add, azd ai toolbox skill list, azd ai toolbox skill remove); changes don’t take effect for MCP clients until you promote the new version with azd ai toolbox publish.

Manage skills with the REST API

The Skills API is versioned: creating a skill version auto-creates the skill if it doesn’t exist yet. Each update creates a new immutable SkillVersion. The parent Skill object tracks default_version (the active version) and latest_version.

Skills endpoint: {FOUNDRY_PROJECT_ENDPOINT}/skills

Authentication: Bearer token from DefaultAzureCredential with scope https://ai.azure.com/.default.

Preview header: All Skills API calls require Foundry-Features: Skills=V1Preview.

Object	Key fields	Description
Skill	id, name, description, created_at, default_version, latest_version	The skill container. default_version points to the active version.
SkillVersion	id, skill_id, name, version, description, created_at	An immutable snapshot of the skill content.

For an end-to-end Python CRUD walkthrough — create two versions, switch default_version, fetch, list, delete — see the sample_skills_crud.py sample in the azure-ai-projects SDK.

Create a skill version

Creating a version auto-creates the parent skill if it doesn’t exist. After creating a version, call Update default version to make it the active version.

You can create a version in two ways: submit the content directly as JSON via inline_content, or upload a ZIP archive containing a SKILL.md file.

Option 1: Create from inline content (JSON)

Use this option when you want to supply the skill’s instructions text directly without packaging a file.

Example response (SkillVersion object):

{
  "id": "skillver_abc123",
  "skill_id": "skill_abc123",
  "name": "greeting",
  "version": "v1",
  "description": "Generate a personalized greeting for the user.",
  "created_at": 1741305600
}

Option 2: Create from a SKILL.md ZIP

Use multipart form upload when you have a SKILL.md file. The skill name comes from the {name} path parameter. Upload a single ZIP file or multiple individual files. The SKILL.md is parsed to populate the version description and instructions.

For ZIP uploads, the server extracts and validates the SKILL.md content. For individual file uploads, files are validated as-is.

Example response (SkillVersion object):

{
  "id": "skillver_def456",
  "skill_id": "skill_def456",
  "name": "greeting",
  "version": "v1",
  "description": "Generate a personalized greeting for the user.",
  "created_at": 1741305600
}

List skills

Example response:

{
  "data": [
    {
      "id": "skill_abc123",
      "name": "greeting",
      "description": "Generate a personalized greeting for the user.",
      "created_at": 1741305600,
      "default_version": "v1",
      "latest_version": "v1"
    }
  ],
  "has_more": false,
  "first_id": "skill_abc123",
  "last_id": "skill_abc123"
}

Use last_id with the after query parameter for forward cursor-based pagination.

Get a skill

Returns the skill metadata. Returns HTTP 404 if the skill doesn’t exist.

Download skill content

Downloads the skill content as a ZIP archive. Use the default version endpoint to get the active version, or the version-specific endpoint to get a specific version.

The response body is a binary ZIP archive (Content-Type: application/zip).

Delete a skill

Returns HTTP 200 on success:

{
  "id": "skill_abc123",
  "name": "greeting",
  "deleted": true
}

List skill versions

Example response:

{
  "data": [
    {
      "id": "skillver_abc123",
      "skill_id": "skill_abc123",
      "name": "greeting",
      "version": "v1",
      "description": "Generate a personalized greeting for the user.",
      "created_at": 1741305600
    }
  ],
  "has_more": false
}

Get a skill version

Delete a skill version

Returns HTTP 200 on success:

{
  "id": "skillver_abc123",
  "name": "greeting",
  "deleted": true,
  "version": "v1"
}

Update default version

Change which version the skill resolves to by default. Toolboxes and agents that reference the skill without pinning a version use the default_version.

Use skills in a hosted agent

In direct injection mode, you download skills from the Foundry Skills API into your agent project directory. The agent reads the SKILL.md files at startup and injects their content as extra system instructions for each session. This mode works without a toolbox and is appropriate when you want to bundle specific skill versions directly with your agent code.

For the alternative mode — where skills and tools share a single discoverable endpoint that any MCP client can reach — see Attach skills to a toolbox (preview).

The following walkthrough uses a GitHub Copilot SDK sample that reads SKILL.md files from a local skills/ directory. Use the Download skill content operation to pull skills from Foundry into this directory.

This sample requires a GitHub fine-grained personal access token (PAT) with Copilot requests: Read-only permission. Create one at github.com/settings/personal-access-tokens/new. Classic tokens (ghp_) aren’t supported. Use a fine-grained PAT (github_pat_).

Step 1: Initialize the agent project

Scaffold the project from the sample manifest:

azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/invocations/github-copilot/agent.manifest.yaml

Set the required GitHub token:

azd env set GITHUB_TOKEN="github_pat_..."

The scaffolded project includes main.py, configuration files, and a sample joke skill:

+-- main.py                  ? agent code that loads skills via CopilotClient
+-- agent.yaml
+-- agent.manifest.yaml
+-- requirements.txt
+-- skills/
    +-- joke/
        +-- SKILL.md         ? bundled sample skill

In main.py, the skill_directories parameter tells the Copilot SDK where to find skill files. Any SKILL.md in a subdirectory of skills/ is loaded as extra instructions when a session starts.

Step 2: Populate skills from Foundry

Use the Download skill content operation to pull the greeting skill from Foundry. Extract the SKILL.md from the downloaded ZIP and save it to skills/greeting/SKILL.md:

mkdir skills/greeting

If you haven’t stored the greeting skill in Foundry yet, copy the skill content from Author a skill directly into skills/greeting/SKILL.md.

The project now includes both skills:

+-- main.py
+-- agent.yaml
+-- agent.manifest.yaml
+-- requirements.txt
+-- skills/
    +-- greeting/
    —   +-- SKILL.md         ? your greeting skill
    +-- joke/
        +-- SKILL.md

Step 3: Run and test locally

Start the agent:

azd ai agent run

In a separate terminal, test the greeting skill:

azd ai agent invoke --local '{"input": "Hi, my name is Alex!"}'

On PowerShell, escape the inner quotes: azd ai agent invoke --local '{\"input\": \"Hi, my name is Alex!\"}'

Step 4: Deploy and test remotely

Create Azure resources and deploy the agent:

azd provision
azd deploy

Test the deployed agent on Foundry:

azd ai agent invoke '{"input": "Hi, my name is Alex!"}'

Related content

• Curate intent-based toolbox in Foundry
• Deploy a Hosted agent
• Agent Skills overview