Add skills to a declarative agent created with Microsoft 365 Agents Toolkit

Important

In tenants that use Microsoft Purview Information Barriers (IB), admins can deploy declarative agents with skills, but end users can't add skills to declarative agents they create.

Support for independent software vendors (ISVs) to publish declarative agents with skills through Partner Center isn't available yet and is coming soon. ISVs shouldn't submit declarative agent packages that include skills to Partner Center.

A skill is a modular, reusable component that you add to a declarative agent to package instructions, resources, and scripts for a specific task. This article describes how to add a skill to a declarative agent by using the Microsoft 365 Agents Toolkit (ATK) command-line interface (CLI) or the Visual Studio Code extension.

To learn what skills are, why to use them, and the full support matrix, supported file types, sandbox behavior, and governance, see Skills in declarative agents.

Important

This guide assumes you completed the Create declarative agents by using Microsoft 365 Agents Toolkit and JSON tutorial. Adding a skill requires declarative agent manifest version 1.9. If you're using an agent created with an older version of Agents Toolkit, you might need to update the version of your agent manifest. For more information, see Declarative agent manifest reference.

Prerequisites

• Microsoft 365 Agents Toolkit CLI or the Microsoft 365 Agents Toolkit Visual Studio Code extension

Enable agent skills

Agent skills support is controlled by the TEAMSFX_AGENT_SKILLS environment variable. Set it before you launch the CLI or Visual Studio Code.

• Windows (PowerShell) - To persist the variable across sessions, add it to your user environment variables:

  [System.Environment]::SetEnvironmentVariable("TEAMSFX_AGENT_SKILLS", "true", "User")
  

• macOS or Linux - Set the variable:

  export TEAMSFX_AGENT_SKILLS=true
  

  To persist the variable, add the export line to your ~/.bashrc, ~/.zshrc, or equivalent shell profile.

If you set the variable after you install the Visual Studio Code extension, restart Visual Studio Code completely.

Add a skill to your agent

CLI

1. In your existing project, add a skill. To create a new skill, provide a name and description:

   atk add skill --name skill-name --description description
   

   To add an existing skill folder, use the --from option:

   atk add skill --from PATH_TO_SKILL
   

2. Provision the declarative agent to make it available in your environment:

   atk provision --env local
   

Visual Studio Code

1. Open your agent project in Visual Studio Code.

2. Select Microsoft 365 Agents Toolkit, and then select Add Skill in the Agents Toolkit pane on the left.

   

3. Select Create a new skill.

   

4. Enter a name for the skill, and then enter a description.

5. Choose whether you want to keep the skill scoped to this agent only or expose it to all Copilot surfaces.

6. Select manifest.json when prompted for the manifest, and then select Add.

7. Open manifest.json and ensure that the declarative agent manifest version is set to 1.9.

8. Open the ./appPackage/skills/your-skill-name/SKILL.md (replace your-skill-name with the name of your skill).

9. Add your instructions to SKILL.md and save the file.

10. Select Provision in the left pane to make the declarative agent available in your environment.

Limits

In the Agents Toolkit, you add a skill as a directory (you can't use .zip), and the complete app package is limited to 10 MB. You can add up to eight skills per agent, with a maximum directory depth of three and up to 350 files across the skill directory. For the full support matrix, see Skills in declarative agents.

Related content

• Skills in declarative agents
• Add skills to your declarative agent in Agent Builder