> 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, skill package uploads, additional tools, and export features

{% 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 the <mark style="color:blue;">Add Skill</mark> button in the upper right.

The system provides two creation methods:

### 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. Complete the <mark style="color:blue;">Basic Settings</mark> tab:
   * **Skill name** (required): Give the skill an easily 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. Click <mark style="color:blue;">Save</mark> to finish creating the skill

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

Use this method to import a packaged `.skill` or `.zip` file.

1. In the Add Skill dialog (upload mode by default), drag a `.skill` or `.zip` file into the upload area, or click the area to select a file
2. Once the upload is complete, the system automatically parses `SKILL.md` in the file to extract the skill name, description, and instructions
3. After creation succeeds, you are automatically taken to the editing page, where you can adjust the settings further

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

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

Execution 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 instructions in Markdown. 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. The file tree is on the left; select a file to preview its content on the right. Uploading, adding folders, deleting, and reuploading in 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;">Reupload 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 a 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 click Confirm
3. Selected tools appear in the list with their names, types (API / MCP), and descriptions
4. To remove a tool, click the delete icon on its card

When you finish configuring the skill, click <mark style="color:blue;">Save Changes</mark> in the lower right of the page.

***

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

In the <mark style="color:blue;">Files</mark> tab of the skill editing page, 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 skill package with other organizations for import.
{% endhint %}

***

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

A created skill must be assigned to an Agent before it takes 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 assign and click Confirm
4. Save the Agent settings

Once assigned, the Agent automatically determines whether to expand a skill based on the user's question during a conversation, then follows the skill's instructions to perform the task.

***

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

To let members with specific roles see only skills relevant to their work, use role permission management to assign skills to roles individually.

For example, a company's 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 this skill, and retain only read permission. After configuration, sales staff can 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 invisible**: 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**: For each “role × skill” assignment, you can configure <mark style="color:blue;">Read</mark>, <mark style="color:blue;">Edit</mark>, and <mark style="color:blue;">Delete</mark> permissions separately to support read-only access, such as allowing reading without modification
* **Creation permission**: Each role has an independent “Allow Skill Creation” toggle that controls whether its members can create skills
* **Owners are unrestricted**: Organization owners automatically have full access to all skills without assignment
* **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, click “<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 %}

### Configure 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 with this role can create skills. Changes are saved immediately; a success message appears after the update.
{% 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 %}

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

In the assigned list, configure read/edit/delete permissions for each skill individually, or remove the assignment. Selecting or clearing a permission saves it immediately; a success message appears after the update. 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 skill creation and skill permissions can be configured"><figcaption><p>Manage creation permission and individual skill permissions in 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 the skills to assign to the role from the available skills</p></figcaption></figure>

{% hint style="info" %}
For details 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 assigned 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.