# Manage EMQX Agents Skills

A deployment-level skill is a reusable Markdown guide for creating a type of agent. It describes the agent's goal, triggers, data sources, tool usage, and output requirements. Reference a skill in a chat to create a similar agent with different topics, configuration, or output requirements.

For example, a skill can describe how to create an agent that:

- Monitors device offline events and generates alert summaries.
- Queries telemetry data from EMQX Tables and generates daily reports.
- Listens to MQTT topics, detects anomalies, and performs standard actions.
- Produces root cause analysis reports in a team-defined format.

A skill guides the current conversation. Referencing a skill does not directly create or deploy an agent. You must review the generated agent definition and deploy it after validation. A skill does not add connectors, tools, or permissions, and it does not replace agent instructions.

Deployment-level skills are different from the skills bundled with a deployed agent. Referencing a skill does not automatically add the uploaded `SKILL.md` file to the deployed agent. You manage deployment-level skills from **Skills** in the left navigation menu. Bundled agent skills remain read-only on the agent detail page.

## Prerequisites

Before managing or using deployment-level skills:

- Create an EMQX Agents deployment and verify that it is **Running**.
- Make sure that you have permission to view the deployment's skills.

Skills use the same role permissions as deployment management:

| Member Role | Skills Permissions |
|---|---|
| **Administrator** | View, upload, delete, and replace skills. |
| **Project Administrator** and **Project User** | View, upload, delete, and replace skills in authorized projects. |
| Other member roles with access to the deployment | Read-only access. |

To update a skill in the Console, delete it and upload the revised `SKILL.md`. Read-only users can reference skills only in chats that they are allowed to use. For details about project access, see [Roles and Permissions](../feature/user.md#roles-and-permissions).

## Reuse an Agent Creation Workflow

You can reuse a skill generated during agent authoring or write your own skill to define how a type of agent should be created.

### Reuse a Generated Skill

1. Start a chat and describe the agent you want to create.
2. Review the generated agent definition and refine it through follow-up messages until it meets your requirements.
3. After validation, [deploy the agent](./chats.md#deploy-an-agent-from-a-chat).
4. On the agent detail page, open the [Skills tab](./agents.md#skills-tab), select the generated `SKILL.md` file, and download it.
5. [Upload the file](#upload-a-skill) to the deployment's **Skills** page.
6. When creating a similar agent, [reference the skill in a chat](#create-an-agent-with-a-skill) and describe the differences, such as the agent name, MQTT topic, threshold, or output requirements.

### Write Your Own Skill

If the generated agent does not meet your requirements, you can write a `SKILL.md` file that specifies the agent's goal, triggers, data sources, tools, behavior, and output format. Upload the file, then reference it in subsequent chats to reuse those creation requirements. For a complete `SKILL.md` example, see [Prepare a Skill File](#prepare-a-skill-file).

## Prepare a Skill File

Upload one UTF-8 encoded Markdown file named `SKILL.md`. The file must not exceed 64 KiB.

The following example describes how to create an agent that detects spikes in device offline events. It specifies the data and configuration to request before finalizing the agent. Save the contents as `SKILL.md` and adapt the guidance to your workflow.

```markdown
---
name: device-offline-monitor
description: Create an agent that detects spikes in device offline events and produces an MQTT operations alert.
---

# Device Offline Monitor Agent

## Goal

Create an agent that monitors device status messages, detects an unusual increase in offline events, and produces a concise operations alert.

## Trigger and Data

1. Use an MQTT event trigger for `factory/+/device/+/status`.
2. Treat a message with `status = offline` as an offline event.
3. Query the latest 15 minutes of device status history from EMQX Tables for historical comparison.

## Agent Behavior

1. Group offline events by factory and production line using the data mappings provided by the user.
2. Compare the number of offline events in the current five-minute window with the recent baseline.
3. Report only when the event count exceeds the configured threshold.
4. Include the affected devices, time range, likely cause, and recommended next action.

## Configuration to Request

- MQTT topic filter and required connectors.
- EMQX Tables table and data mappings for factory, production line, device, status, and timestamp.
- Offline-event count threshold.
- Comparison window and baseline window.
- Output language and alert destination.

## Output Format

Return a short alert with these sections: Summary, Evidence, Affected Devices, Likely Cause, and Recommended Action.

## Guardrails

Do not claim that a device is offline without an MQTT event or matching historical data. Ask for missing connectors, topic, data mappings, threshold, or alert-destination details before finalizing the agent.
```

The Console does not support uploading a ZIP file or directory. It rejects uploads with a skill name that already exists.

## View Deployment-Level Skills

Click **Skills** in the left navigation menu. The Skills page lists the **Name**, **Description**, **Size**, and **Updated At** information for each uploaded skill.

![Skills page for managing deployment-level skills](./_assets/agents_skills_page.png)

Click a skill name to open its details. From the details drawer, you can:

- Preview the rendered Markdown.
- View the Markdown source.
- Refresh the displayed content.
- Download the `SKILL.md` file.

![Skill details drawer showing the Markdown preview of SKILL.md](./_assets/agents_skill_details.png)

## Upload a Skill

1. On the **Skills** page, click **Upload Skill**.
2. Drag a `SKILL.md` file into the upload area, or click the upload area and select the file.
3. Verify that the selected file is named `SKILL.md`, uses UTF-8 encoding, and does not exceed 64 KiB.
4. Click **Confirm**.
5. Verify that the skill appears in the Skills table.

The uploaded skill is immediately available for selection in chats in the same deployment. The Console rejects uploads with a skill name that already exists. To update a skill, delete it and upload the revised `SKILL.md`.

![Upload Skill dialog with SKILL.md selected for upload](./_assets/agents_upload_skill.png)

## Delete a Skill

1. On the **Skills** page, find the skill and click its delete icon in the **Actions** column.
2. Confirm the deletion in the dialog.

After deletion, the skill no longer appears in the candidate list and cannot be loaded by new runs in the current deployment. Historical messages retain their original `/skill-name` text. Deleting a skill does not affect skills or chats in other EMQX Agents deployments.

## Create an Agent with a Skill

You can reference a deployment-level skill in the first chat on the **Overview** page, in a new message on the **Chats** page, or when you edit a historical user message and regenerate the response.

To reference a skill:

1. At the beginning of the message or after a space, enter `/` followed by part of the skill name, such as `/device`.
2. Select the skill from the candidate list. Each candidate displays the skill name and description.
3. Describe the requirements for this agent, including any differences from the skill's example, and send the message.

You can also use the keyboard to select a candidate:

- Press the Up Arrow or Down Arrow key to move through the list.
- Press Enter or Tab to select a skill.
- Press Escape to close the list.

![No matching skills state in the chat input](./_assets/agents_reference_skill_in_chat.png)

The selected reference remains in the message and is highlighted. For example, adapt the offline-monitoring skill to a cold-chain warehouse with a different status topic and English alerts:

![Chat input with the device-offline-monitor skill reference highlighted](./_assets/agents_selected_reference_skill.png)

A message can reference multiple skills. If the same skill is referenced more than once, EMQX Agents selects it once for the run and loads selected skills in the order of their first appearance.

Review the generated agent definition and provide any missing information requested in the chat. When the definition meets your requirements and passes validation, [deploy the agent](./chats.md#deploy-an-agent-from-a-chat).

## Understand When a Skill Applies

A skill reference applies only to the chat run created or regenerated from the current message. It guides agent creation or modification in that conversation and does not automatically change a deployed agent. To update a running agent, review the changes and [redeploy it from the chat](./chats.md#redeploy-from-a-chat).

Skill references follow these rules:

- EMQX Agents loads a skill only if it exists in the current deployment and is recognized when the message is sent.
- A selected skill is not automatically applied to the next message.
- If you manually enter `/skill-name` while the skill list is still loading, EMQX Agents sends it as plain message text. The input does not wait for the list to load or select the skill automatically.
- An unknown skill name or an ordinary path such as `/path` remains plain message text. A slash in the middle of a word does not start a skill reference.
- When editing a previous message, review and adjust its skill references before regenerating the response. The new run uses the skills selected for the edited message.
- When you regenerate a response, EMQX Agents uses the current content of the selected skills. If a skill has changed since the original message, the regenerated response may differ.

If no skill in the current deployment matches the text after `/`, the menu displays **No matching skills**.

## Resolve Skill Problems

| Condition | Behavior and Action |
|---|---|
| The file is not named `SKILL.md`. | The Console rejects the file before uploading. Rename the file and try again. |
| More than one file is selected. | The Console rejects the selection. Upload one `SKILL.md` file. |
| The file exceeds 64 KiB. | The Console rejects the file. Reduce the file size to 64 KiB or less. |
| The skill content is invalid. | The upload fails. Correct the file based on the displayed error message, then upload it again. |
| A skill with the same name already exists. | The Console rejects the upload. Delete the existing skill before uploading the revised `SKILL.md`. |
| Your role has read-only access to skills. | Ask an Administrator, Project Administrator, or Project User with access to the deployment to upload, delete, or replace the skill. |
| A skill operation fails because the service is unavailable. | Verify that the deployment is running, then try again. |
| Regeneration fails because a referenced skill has been deleted or is invalid. | Edit the message to remove the reference or select an available skill, then try again. |
| The combined size of the `SKILL.md` files selected for one message exceeds 256 KiB. | The run cannot start. Select fewer skills or reduce their content before trying again. |

## Deployment-Level Skill Limits

| Item | Limit |
|---|---|
| File | One UTF-8 encoded Markdown file named `SKILL.md` per upload. |
| File size | 64 KiB or less. |
| Combined size per message | The combined size of the `SKILL.md` files selected for one message must not exceed 256 KiB. |
| Archives and directories | ZIP files and directory uploads are not supported. |
| Duplicate names | The Console rejects uploads with a skill name that already exists. |
| Scope | A skill is available only in the EMQX Agents deployment where it was uploaded. Upload the skill separately in each deployment that needs it. |
| Permissions | Skills use deployment management permissions. See [Prerequisites](#prerequisites) for the roles that can manage skills. |

## Next Steps

- [Start and Manage Chats](./chats.md)
- [Manage Agents](./agents.md)
- [Manage Connectors](./connectors.md)