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 must stay consistent across every conversation. A support agent follows a fixed escalation policy. A code-review agent applies the same checklist each time. A sales agent respects set messaging constraints. When you embed these guidelines in each agent’s system prompt or code, you create duplication. If the policy changes, you 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 that you author once and store centrally in Foundry through the versioned Skills API. You then deliver it to agents in two modes. Attach to a toolbox so any MCP client discovers and loads skills alongside tools. Or download directly into a Hosted or local agent project to inject the content into each session’s context. Skills are versioned: every update creates a new immutable version, and the parent skill tracks a default_version. To 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.

If you use Skills with any third-party servers, agents, code, or non-Azure Direct models (“Third-Party Systems”), you do so at your own risk. Microsoft has no responsibility to you or others in relation to these uses. Third-Party Systems are Non-Microsoft Products under the Microsoft Product Terms and are governed by their own third-party license terms.  You are responsible for any usage and associated costs.

Review all data shared with and received from Third-Party Systems. Be aware of third-party practices for handling, sharing, retention, and location of data. It’s your responsibility to manage whether your data flows outside of your organization’s Azure compliance and geographic boundaries and any related implications. Ensure that appropriate permissions, boundaries, and approvals are provisioned.

You’re responsible for carefully reviewing and testing applications you build in the context of your specific use cases, and making all appropriate decisions and customizations.  This responsibility includes implementing your own responsible AI mitigations, such as metaprompts, content filters, or other safety systems, and ensuring your applications meet appropriate quality, reliability, security, and trustworthiness standards. Learn more.

Feature support

Feature	REST API	Python	.NET	JavaScript	VS Code	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

Limitations

Skills don’t support private networking. The Skills API isn’t accessible over a private endpoint, so you can’t create, manage, or download skills from a Foundry resource that has public network access disabled.

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.

• Visual Studio Code (VS Code).
• Install the Microsoft Foundry Toolkit for Visual Studio Code extension from the Visual Studio Code Marketplace.

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.

Create a toolbox version that references the greeting skill you created earlier. Omit version to follow the skill’s default_version, or pin a version string to lock the reference to an immutable snapshot.

For the full toolbox workflow — including connections, versioning, and the azd ai toolbox skill add, azd ai toolbox skill list, and azd ai toolbox skill remove commands — see the Attach skills to a toolbox section in the toolbox article. Changes from the imperative azd skill commands don’t take effect for MCP clients until you promote the new version with azd ai toolbox publish.

Consume toolbox skills in Microsoft Agent Framework

After you attach skills to a toolbox, an agent can discover and load them from the toolbox MCP endpoint at runtime instead of bundling SKILL.md files locally. For a complete C# example, see the Skills in Toolbox sample. The sample hosts an agent with the Microsoft Agent Framework Responses hosting layer and uses an AgentSkillsProvider, built with AgentSkillsProviderBuilder.UseMcpSkills, to apply the Agent Skills progressive-disclosure pattern:

1. Advertise: The provider injects skill names and descriptions into the system prompt so the agent knows which skills are available.
2. Load: When the agent decides a skill is relevant, it retrieves the full skill body from the toolbox.
3. Read resources: If a skill includes supplementary content, such as reference documents or assets, the agent reads them on demand.

The agent fetches the full skill body and resources from the toolbox only when it needs them, which reduces token usage. The sample consumes skills from an existing toolbox; it doesn’t create or provision them.

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

To inspect a specific skill version, use the REST API, Python, .NET, or JavaScript tab.

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. Use it when you want to bundle specific skill versions 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’s azure.yaml:

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

Set the required GitHub token:

azd env set GITHUB_TOKEN="github_pat_..."

The scaffolded project includes a root azure.yaml, agent code, configuration files, and a sample joke skill:

|-- azure.yaml
`-- src/
    `-- <agent-name>/
        |-- main.py          # agent code that loads skills via CopilotClient
        |-- 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:

|-- azure.yaml
`-- src/
    `-- <agent-name>/
        |-- main.py
        |-- 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