Skills¶

A skill is a reusable set of instructions that an agent loads when a task matches. It is a folder with one required file, SKILL.md. The file starts with front matter, a block of settings at the top, that holds a name and a description. A skill is immutable or mutable. See Immutable and Mutable Skills Differ.

A Skill Needs a Name and a Description¶

---
name: triage-alerts
description: Sort new security alerts by severity. Use when the user asks to triage alerts.
---

# Triage alerts

1. List the new alerts.
2. Rank them by severity.

name is required. Use lowercase letters, digits and single hyphens, up to 63 characters.
description is required. It holds 1 to 1,024 characters. The agent reads it to decide when to use the skill.
Front matter starts with --- on line 1 and ends with a second --- line.

A skill can also hold scripts/, references/ and assets/ folders.

Import a Skill as One Markdown File or ZIP¶

Open Skills in the organization sidebar or in Workspace settings.

Select Import skills. The Import skills dialog opens.
Drop or choose one .md file or one .zip archive, then select Preview. The dialog lists each skill with Create or Conflict.
In a workspace, set Type to Immutable, because the dialog starts on Mutable when the workspace has agents.
For a Conflict, choose Overwrite or Rename. For Rename, type a new name.
Select Import. The skill appears in the table. In a workspace, set the type selector above the table to Immutable to see it.

The upload limit is 10 MiB. Each SKILL.md holds up to 64 KiB. A ZIP archive cannot contain links, nested skill folders or duplicate paths. The dialog offers a valid example to download.

Immutable and Mutable Skills Differ¶

Immutable skills are the ones you upload. They have versions, live at organization or workspace scope, and attach to a sandbox or an agent.
Mutable skills live in one agent's home directory. The agent can edit them, and agents often write them. To list them, set the type selector to Mutable and pick an agent. The agent must be Idle.

Change Version Applies to Every Agent¶

Overwriting an immutable skill creates the next version. A skill has one active version at a time. You cannot pin a version to one agent.

Open the menu on the skill row and select Edit. The Change version for dialog opens.
Pick a version, such as v1 or v2, in Version.
Select Update. The toast reads Skill version updated.

Every agent and sandbox that uses the skill now loads that version.

Export Moves a Skill Between Scopes¶

A skill has a scope, either the organization or one workspace. The table shows the scope as a badge. A workspace sees an organization skill only if you selected it as inherited.

To move a skill, select it, open the menu at the top of the table and select Export. You get a ZIP file. Import that file at the other scope.

The Agent Chooses Its Own Skills¶

AgentZ has no slash command for skills. The agent reads the description of each skill and loads the ones that fit. Write each description to say when the skill applies.

To attach an immutable skill, use the Skills step of the sandbox wizard. You can also use the Immutable skills field when you create an agent.

Next Step¶

Custom tools