Add custom skills to a declarative agent created with Microsoft 365 Agents Toolkit (preview)

Important

Custom skills in declarative agents are in preview for organizations that are part of the Microsoft Frontier Preview. For more information, see Explore AI Early Access in Microsoft 365.

A custom 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 custom 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 custom skills are, why to use them, and the full support matrix, supported file types, sandbox behavior, and governance, see Custom skills in declarative agents.

Important

This guide assumes you completed the Create declarative agents using Microsoft 365 Agents Toolkit tutorial. Adding a custom skill requires declarative agent manifest version 1.9. If your using an agent created with an older version of the Agents Toolkit, you might need to update the version of your agent manifest.

Prerequisites

• Microsoft 365 Agents Toolkit CLI or the Microsoft 365 Agents Tookit 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 and known issues

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 400 files across the skill directory. For the full support matrix and known issues, see Custom skills in declarative agents.

Related content

• Custom skills in declarative agents
• Add custom skills to your declarative agent in Agent Builder