Create a Skill

What you'll build

A custom skill that adds domain knowledge and task playbooks to your agent. Skills are modular capabilities your agent uses automatically when relevant — such as troubleshooting a specific service or running a diagnostic procedure. Learn more → Skills. Time: ~10 minutes.

Skills + Knowledge

Skills and knowledge uploads work together. A skill teaches your agent how to do something (procedures, playbooks, step-by-step instructions). A knowledge document teaches your agent what it needs to know (reference data, architecture docs, runbooks). You can also attach reference documents directly to a skill as supporting files (Step 5 below). See Upload Knowledge Documents for the knowledge upload flow.

Prerequisites

• An agent created in the Azure SRE Agent portal
• A clear understanding of the procedure or domain knowledge you want to encode

---

Create a skill

1. Open the Agent Canvas

Navigate to your agent → Builder → Agent Canvas.

2. Click Create → Skill

Click the Create dropdown in the toolbar and select Skill.

The skill creation dialog opens with a two-column layout: form fields on the left and a code editor on the right showing SKILL.md.

3. Enter name and description

Field	Example value
Name	high-cpu-troubleshooting
Description	"Troubleshooting procedure for high CPU alerts on container apps. Checks upstream dependencies, connection pool, and recent deployments."

The name must be unique across your skills. The description appears in the Skills list and helps the agent decide when to use this skill.

Editing the description

Click Edit next to the description text to switch to edit mode. Click Save when done.

4. Write skill instructions

The center editor shows SKILL.md — this is where you write the skill's instructions. The file starts with a default template:

---
name:
description:
---

<!-- Add your skill instructions here -->

The YAML frontmatter (name, description, tools) stays in sync with the form fields on the left. Write your instructions below the frontmatter in Markdown:

---
name: high-cpu-troubleshooting
description: Troubleshooting procedure for high CPU alerts on container apps
tools:
  - kusto_query
---

## When to use this skill
Use this skill when you receive a high CPU alert on any container app.

## Steps
1. Check upstream dependencies for cascading failures
2. Query connection pool metrics for the last hour
3. Review deployments in the last 24 hours
4. If a recent deployment correlates with CPU spike, identify the commit
5. Recommend rollback or fix based on findings

## Expected output
Structured report with: affected resource, root cause, recommended action, and evidence.

5. Add supporting files (optional)

The Files section on the left shows a file browser. Beyond the default SKILL.md, you can:

• Click the new file icon to add files (e.g., reference data, templates, example queries)
• Click the new folder icon to organize files into directories
• Drag and drop a folder into the drop zone, or click the Upload folder link to upload an entire folder structure

Click any file in the browser to edit it in the code editor. The editor supports syntax highlighting for Markdown, JSON, YAML, KQL, Python, and shell scripts.

6. Select tools (optional)

1. Click Choose tools in the Tools section.
2. Browse or search for tools — filter by type (Custom Tool, MCP Tool) or search by name.
3. Check the tools this skill needs (e.g., kusto_query, azure_resource_health).
4. Close the panel.

To create custom tools first, see Create a Kusto Tool or Create a Python Tool. Learn more → Tools concept.

Selected tools appear as removable pills. These tools are dynamically available when this skill is activated.

note

Tools added to a skill are dynamically available when the skill is activated. For more consistent behavior, configure tools directly on the custom agent instead.

7. Click Create

Checkpoint: Your skill appears in the Skills tab on the Agent Canvas. The agent can now use it automatically when it encounters a relevant situation.

---

Test it

Skills are available to the main agent by default, so you can test them directly in chat without creating a custom agent first.

Option 1: Test in a new chat

1. Click New chat thread in the sidebar.
2. Type a prompt that should trigger your skill — e.g., "We're seeing high CPU on our container app, can you investigate?"
3. Verify the agent activates the skill and follows the procedures you defined.

Option 2: Test via a custom agent in the playground

1. Create a custom agent and assign this skill to it.
2. On the Agent Canvas toolbar, select the Test playground view toggle.
3. Select the custom agent, type a test prompt, and verify it uses the skill correctly.

For full details, see Agent Playground.

---

Edit a skill

1. Select the skill

In the Skills tab, click the skill name or select it and click Edit.

2. Modify fields

The edit dialog opens with all current values pre-populated — form fields, files, and editor content.

What to change	Where to update
When the agent uses it	Description and SKILL.md instructions
What procedures to follow	SKILL.md content in the editor
Which tools are available	Tools → Choose tools
Reference data	Files → add, edit, or remove files

3. Click Save

---

Tips for writing effective skills

• Be specific about when to use it — the agent reads the description and instructions to decide relevance
• Include step-by-step procedures — numbered steps give the agent a clear playbook
• Specify expected output — tell the agent what format the results should take
• Add reference data — upload query templates, configuration baselines, or known-good values as supporting files
• Assign relevant tools — if the skill needs specific tools (like Kusto queries or Azure actions), add them

---

What you learned

• Skills are modular capabilities with instructions, supporting files, and optional tools
• The agent activates skills automatically when it encounters a relevant situation based on the name and description
• SKILL.md contains your instructions in Markdown with YAML frontmatter that syncs with the form fields
• Supporting files (reference data, templates, queries) give the skill additional context
• Knowledge documents complement skills — skills define procedures, knowledge provides reference data
• Tools assigned to a skill are dynamically available when activated — for consistent behavior, configure tools on the custom agent instead
• Test skills in the Test playground to verify the agent picks them up correctly

Related

Resource	What you'll learn
Skills →	How skills work and when the agent activates them
Upload Knowledge Documents →	Add reference documents that complement your skills
Custom Agents →	How custom agents use skills to specialize
Agent Playground →	Test and iterate on your agent configuration
Tools →	How tools give agents access to external services
Create a Custom Agent →	Build a custom agent that can use your skills
Create a Kusto Tool →	Create a custom Kusto query tool
Create a Python Tool →	Create a custom Python tool
Create a Scheduled Task →	Automate recurring tasks
Test Tool in Playground →	Debug individual tools before assigning them