> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/skills/skills-management.md).

# Skill Management

Learn how to create, edit, and manage skills, including manual creation, package uploads, additional tools, and export

{% hint style="info" %}
If you are not yet familiar with skills, read [Skills](/maiagent-user-guide/en/build/skills.md) first.
{% endhint %}

## Create a skill <a href="#create-skill" id="create-skill"></a>

Click <mark style="color:blue;">Skills</mark> in the left menu to open the skill management page, then click <mark style="color:blue;">Add skill</mark> in the upper-right corner.

The system provides two ways to create skills:

### Method 1: Create manually <a href="#method-manual-create" id="method-manual-create"></a>

Use this method to write skill instructions from scratch.

1. In the Add skill dialog, click <mark style="color:blue;">Create a new skill manually</mark> at the bottom to switch to manual mode
2. Fill in the <mark style="color:blue;">Basic settings</mark> tab:
   * **Skill name** (required): Give the skill a recognizable name
   * **Description** (required): Briefly describe the skill's purpose
3. Switch to the <mark style="color:blue;">Instructions</mark> tab and write instructions in Markdown. You can also click <mark style="color:blue;">Apply template</mark> to use the system's default template as a starting point
4. (Optional) Switch to the <mark style="color:blue;">Additional tools</mark> tab and select the tools the skill needs
5. Switch to the <mark style="color:blue;">Permission settings</mark> tab. Under <mark style="color:blue;">Quickly select permission scope</mark>, confirm which roles can use this skill: <mark style="color:blue;">All roles</mark>, <mark style="color:blue;">Exclude default role</mark> (selected by default), or <mark style="color:blue;">Select custom roles</mark>. “Will be assigned to after creation” below lists the roles that will actually receive access
6. Click <mark style="color:blue;">Save</mark> to create the skill

If you click <mark style="color:blue;">Save</mark> before opening the <mark style="color:blue;">Permission settings</mark> tab, the skill is not created yet. The screen automatically switches to <mark style="color:blue;">Permission settings</mark> and displays “Please review permission settings and confirm the assigned roles before submitting.” After confirming the roles, click <mark style="color:blue;">Save</mark> again to create the skill with the roles shown on the tab.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-bd1ed983993c823d22400b5a9a9da575af506530%2Fskills-create-permission-reminder.png?alt=media" alt="The Add skill dialog switches to the Permission settings tab and prompts you to review permissions and confirm the assigned roles before submitting. The quick permission scope options are All roles, Exclude default role (selected), and Select custom roles, with the roles to be assigned listed below"><figcaption><p>Saving before reviewing permissions switches to Permission settings and prompts you to confirm the roles</p></figcaption></figure>

{% hint style="info" %}
This confirmation only appears for new skills created manually. It does not appear when creating a skill with <mark style="color:blue;">Upload skill package</mark> or editing an existing skill. To change which roles can use a skill after creation, see [Control skill visibility and permissions by role](#skill-role-visibility).
{% endhint %}

### Method 2: Upload a skill package <a href="#method-upload-skill-package" id="method-upload-skill-package"></a>

Use this method to import an existing `.skill` or `.zip` package.

1. In the Add skill dialog (which defaults to upload mode), drag a `.skill` or `.zip` file to the upload area, or click the area to select a file
2. After upload, the system automatically parses `SKILL.md` in the package to extract the skill name, description, and instructions
3. Once the skill is created, you are automatically redirected to the edit page to adjust its settings

{% hint style="info" %}
The skill package must contain a `SKILL.md` file in the following format:

```markdown
---
name: Skill name
description: Skill description
---

Instructions for the AI assistant go here...
```

{% endhint %}

***

## Edit and configure a skill <a href="#edit-and-configure-skill" id="edit-and-configure-skill"></a>

In the skill list, click the skill's <mark style="color:blue;">Edit</mark> icon to open its settings page.

### Basic settings <a href="#basic-settings" id="basic-settings"></a>

Edit the skill's name and description.

### Instructions <a href="#instruction-content" id="instruction-content"></a>

Edit the skill's Markdown instructions. The Agent uses these instructions when it expands the skill.

Click <mark style="color:blue;">Apply template</mark> to load the default instruction template.

{% hint style="warning" %}
Applying a template overwrites the current instructions. Confirm before proceeding.
{% endhint %}

### Files <a href="#skill-package" id="skill-package"></a>

The <mark style="color:blue;">Files</mark> tab manages the skill's resource files and is available for both manually created and uploaded skills. Select a file in the tree on the left to preview its contents on the right. Uploading, adding folders, deleting, and re-uploading on this tab take effect immediately without a separate save.

* <mark style="color:blue;">Upload files</mark>: Upload reference documents, templates, or scripts as skill resources (up to 100 MB)
* <mark style="color:blue;">Add folder</mark>: Create a folder in the current directory to organize resource files
* <mark style="color:blue;">Download skill package</mark>: Package the instructions and resource files into a `.skill` download. See [Export a skill](#export-skill)
* <mark style="color:blue;">Re-upload skill package</mark>: Upload a new `.skill`/`.zip` version to replace the skill's name, description, instructions, and all resource files. Available only for skills created by upload
* When previewing a file, you can <mark style="color:blue;">Download</mark> or delete it individually

{% hint style="info" %}
Resource files are used only when the Agent has [Code Interpreter](/maiagent-user-guide/en/build/agent/code-interpreter.md) enabled. After the Agent expands the skill, the system places the files in the code execution environment for the Agent to read. Agents without Code Interpreter enabled use only the skill's instructions.
{% endhint %}

### Additional tools <a href="#additional-tools" id="additional-tools"></a>

Attach the required tools to the skill so the Agent can call them while executing it.

1. Click <mark style="color:blue;">Select tools</mark> to open the tool selection dialog
2. Select the tools to attach (multiple selections are supported), then confirm
3. Selected tools appear in a list with their names, types (API / MCP), and descriptions
4. To remove a tool, click the delete icon on its card

When finished, click <mark style="color:blue;">Save changes</mark> in the lower-right corner of the page.

***

## Export a skill <a href="#export-skill" id="export-skill"></a>

On the skill edit page, open the <mark style="color:blue;">Files</mark> tab and click <mark style="color:blue;">Download skill package</mark> to export the skill as a `.skill` file.

{% hint style="info" %}
Manually created skills can also be exported. The system automatically packages the instructions and resources into a `.skill` file. You can share the exported package with other organizations for import.
{% endhint %}

***

## Bind a skill to an Agent <a href="#bind-skill-to-ai-agent" id="bind-skill-to-ai-agent"></a>

A skill must be bound to an Agent before it can take effect:

1. Go to the <mark style="color:blue;">AI Assistants</mark> page, select the target Agent, and open its settings
2. Find the <mark style="color:blue;">Skills</mark> setting in the model settings area
3. Select the skills to bind and confirm
4. Save the Agent settings

Once bound, the Agent automatically decides whether to expand a skill based on the user's question and performs the corresponding task according to the skill's instructions.

***

## Control skill visibility and permissions by role <a href="#skill-role-visibility" id="skill-role-visibility"></a>

To show members of specific roles only the skills relevant to their work, use role permission management to assign skills to each role.

For example, a system administrator wants sales staff to read the “Customer summary” skill without being able to edit or delete it. She can edit the sales role, assign the skill, and grant only read permission. Sales staff can then see “Customer summary” in the skill list without receiving edit or delete permissions.

### How it works <a href="#skill-role-visibility-rules" id="skill-role-visibility-rules"></a>

* **Unassigned skills are hidden**: Organization-created skills must be assigned to a role before its members can see them in the skill list. Unassigned skills are completely hidden from that role
* **Permission granularity**: Each role–skill assignment can have separate <mark style="color:blue;">Read</mark>, <mark style="color:blue;">Edit</mark>, and <mark style="color:blue;">Delete</mark> permissions, supporting read-only access such as “can read but cannot modify”
* **Creation permission**: Each role has an independent “Allow skill creation” switch controlling whether its members can create skills
* **Owners have unrestricted access**: Organization owners automatically have full access to all skills without assignments
* **Global skill exception**: Built-in global skills are visible to all members and cannot be restricted through role assignments

### Setup steps <a href="#skill-role-visibility-steps" id="skill-role-visibility-steps"></a>

{% stepper %}
{% step %}

### Open role settings <a href="#open-role-settings" id="open-role-settings"></a>

In the left menu, select “<mark style="color:blue;">Organization settings</mark>” → “<mark style="color:blue;">Organization overview</mark>”, then click “<mark style="color:blue;">Edit role permissions</mark>”. Select the role to configure and switch to the “<mark style="color:blue;">Assign skills</mark>” tab.
{% endstep %}

{% step %}

### Set skill creation permission <a href="#set-create-skill-permission" id="set-create-skill-permission"></a>

Select or clear “<mark style="color:blue;">Allow skill creation</mark>” as needed to determine whether members of this role can create skills. Changes are saved immediately, and a success message appears when the update succeeds.
{% endstep %}

{% step %}

### Assign skills <a href="#assign-skills-to-role" id="assign-skills-to-role"></a>

Click “<mark style="color:blue;">Assign skills</mark>”, select the skills to make available to this role, and confirm.
{% endstep %}

{% step %}

### Set skill permissions <a href="#set-skill-permissions" id="set-skill-permissions"></a>

In the assigned list, set Read/Edit/Delete permissions for each skill or remove its assignment. Selecting or clearing a permission saves it immediately, and a success message appears when the update succeeds. There is no separate “Save” button on this page.
{% endstep %}
{% endstepper %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-3339a4d762b54ab17bd2f31d015b1aae2f3e74b2%2Frole-permission-assign-skills.png?alt=media" alt="The Assign skills tab in role permission management, where you can configure skill creation and skill permissions"><figcaption><p>Manage creation permission and individual skill permissions on the Assign skills tab</p></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-9923a16cdc23ef49119db9d307c83b11ef4977e8%2Frole-permission-assign-skills-modal.png?alt=media" alt="The Assign skills dialog with available skills on the left and selected skills on the right"><figcaption><p>Select available skills to assign to the role</p></figcaption></figure>

{% hint style="info" %}
For instructions on creating roles and assigning members, see [Role permission management](/maiagent-user-guide/en/org/roles/role-permission.md).
{% endhint %}

***

## Delete a skill <a href="#delete-skill" id="delete-skill"></a>

In the skill list, click the skill's <mark style="color:blue;">Delete</mark> icon and confirm to delete it.

{% hint style="warning" %}
After a skill is deleted, Agents bound to it can no longer use it. This action cannot be undone.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/skills/skills-management.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.