Guide · Agent skill

How to use the Foundry Agent Sync agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The foundry-agent-sync skill teaches an AI agent to create and update prompt-based agents inside Azure AI Foundry. You give it a JSON file that lists your agents by name, description and system instructions, and it registers them on the Foundry service through its REST API so they can be invoked from your Azure account. This guide covers what the skill does, how to install it, how to trigger it, and what you need before running a sync.

Foundry Agent Syncgithub/awesome-copilot · MIT Download the skill

Quick start

1Install the skill. Download the ZIP from this page and unzip the foundry-agent-sync folder into ~/.claude/skills/ or your project's .claude/skills/, or upload the ZIP under Settings → Capabilities → Skills.
2Confirm prerequisites. Make sure you have an Azure AI Foundry project with a deployed model, Azure CLI signed in, and the Azure AI User role on the project.
3Ask for a manifest. Ask the assistant to create a foundry agent manifest, describing each agent's name, purpose and instructions.
4Review the manifest. Check each useCaseId, description and baseInstruction in the generated foundry-agents.json before anything is sent to Azure.
5Run the sync. Ask the assistant to sync foundry agents, providing the subscription ID, project endpoint, model deployment name and agent name prefix.
6Verify the agents. Ask the assistant to list the agents, or run the list call from the skill, to confirm each agent is registered.

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file that gives an AI assistant instructions for a specific task. When the assistant recognises a matching request, it follows those instructions. This skill is for one job: taking agent definitions from a local manifest and pushing them to Azure AI Foundry.

Unlike scaffolding skills that only generate local code, this skill registers agents in the Foundry service itself, so they become immediately available for invocation, evaluation and management through the Foundry portal or API. Each agent is created or updated with a named POST call, which means running the sync again updates existing agents rather than duplicating them.

Reads a JSON manifest of agents (useCaseId, description, baseInstruction)
Creates or updates each agent in Azure AI Foundry via the Agent Service REST API
Can scaffold the manifest and a PowerShell or Bash sync script if your repo does not have them
Walks through Azure CLI login and the parameters needed

Install the foundry-agent-sync skill

Download the ZIP for this skill from this page. Unzip it so that the foundry-agent-sync folder (containing SKILL.md) sits in one of these locations:

For a personal install across projects, unzip into ~/.claude/skills/. For a single repository, unzip into that project's .claude/skills/ folder.

In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

Personal: ~/.claude/skills/foundry-agent-sync/
Project: .claude/skills/foundry-agent-sync/ inside your repository
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the prerequisites before you start

The skill cannot create an Azure AI Foundry project or deploy a model for you. Confirm that you have these before asking for a sync, or the sync will fail.

An Azure AI Foundry project with a deployed model (the source example uses gpt-5-4)
Azure CLI (az) installed and authenticated with access to the Foundry project
The Azure AI User role (or higher) on the Foundry project resource
PowerShell for the interactive script, or Bash for the Bicep deployment script
Optional: Bicep and a User-Assigned Managed Identity for automated deployment

az account show --query id -o tsv

Trigger the skill with natural requests

You do not need to name the skill. Ask in plain language, and the assistant will match the request against the skill's trigger phrases. Useful phrasings include the ones below.

Be specific about the goal. If you only want a manifest created, say so. If you want agents pushed live, say that, since the sync writes to the service.

create agent in foundry
sync foundry agents
deploy agents to foundry
register agents in foundry
push agents
create foundry agent manifest
scaffold agent sync
update agent instructions

Write a manifest and run the sync

The manifest is a JSON array with one entry per agent. The skill looks for foundry-agents.json in infra/ or the repo root, or .foundry/agents.json. If none exists, it asks what agents you need and scaffolds one. Each entry needs useCaseId (kebab-case, used to build the agent name as {prefix}-{useCaseId}), description, and baseInstruction (the system prompt).

The skill then creates or locates a sync script (the canonical path is infra/scripts/sync-foundry-agents.ps1), asks you for the project endpoint, subscription ID, model deployment name and agent name prefix, and runs the script. Afterwards it can list the agents to confirm they were synced.

useCaseId: required, kebab-case identifier
description: required, stored as agent metadata
baseInstruction: required, the system prompt

[
  {
    "useCaseId": "alert-triage",
    "description": "Short description of what this agent does.",
    "baseInstruction": "You are an assistant that... <system prompt for the agent>"
  }
]

Safety notes: scripts and network access

This skill runs scripts and makes network calls. The sync script sets the Azure subscription, acquires an access token with az, and sends POST requests to your Foundry project endpoint. Read the script before running it, and confirm the endpoint and subscription are the ones you intend.

The script overwrites existing agents that have the same name, and it has no confirmation step. If live agent instructions must be reviewed first, export or review the manifest and run the sync against a non-production project before production.

Runs PowerShell or Bash scripts on your machine
Uses the network to call the Foundry REST API
Overwrites same-named agents without confirmation
Do not use it for local agent code or container scaffolding; use the microsoft-foundry create sub-skill for that

What people use it for

Keeping agent system prompts in source control and pushing changes to Foundry on each release
Deploying the same set of agents to dev, test and production with a repeatable sync
Adding a Bicep deployment step that registers agents through a managed identity in a CI pipeline
Scaffolding a manifest and PowerShell sync script for a new repository

Frequently asked questions

Is the foundry-agent-sync skill free to use?

The skill is published under the MIT licence on github/awesome-copilot. Using it does not cost anything in itself, but the Azure AI Foundry project, the deployed model and the service usage are billed through your Azure account.

What do I need before I can use the foundry-agent-sync skill?

You need an Azure AI Foundry project with a deployed model, Azure CLI installed and authenticated, and the Azure AI User role or higher on the Foundry project. PowerShell or Bash is needed to run the sync script.

How do I install the foundry-agent-sync skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for a personal install, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

What is the difference between this skill and a scaffolding skill?

This skill registers agents inside the Azure AI Foundry service so they are callable right away. Scaffolding skills only generate local code. For local agent code or container images, the skill's own documentation points to the microsoft-foundry create sub-skill.

Why does my agent sync fail with a 401 Unauthorized error?

The source lists a 401 Unauthorized error as usually caused by an expired token or the wrong audience. The fix is to re-run az account get-access-token with --resource https://ai.azure.com/ and then run the sync again.

Will running the sync overwrite my existing agents?

Yes. Agents are created or updated by name, and the script overwrites existing agents with the same name without a confirmation step. Review the manifest and test against a non-production project first.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you already run Azure AI Foundry and want agent definitions kept in source control and pushed to the service repeatably, especially through Bicep or CI with a managed identity. Pick something else if you have no Foundry project and model yet, or if you only need local agent code or container scaffolding.

Download the skill