# Introducing the MQTTX AI Agent Skill

> MQTTX CLI now ships with an Agent Skill that teaches AI coding agents to run MQTT checks, benchmarks, and simulations correctly.

> Language: en · Published: 2026-09-20 · Category: Product · Canonical: https://mqttx.app/blog/introducing-mqttx-ai-agent-skill · Translation: [中文](https://mqttx.app/zh/blog/introducing-mqttx-ai-agent-skill.md)

Coding agents are good at writing MQTT code. Running the MQTTX CLI correctly is a different problem: flags differ between commands, TLS and authentication options are easy to misconfigure, and benchmarks or simulations need bounded, repeatable parameters. An agent that guesses its way through `mqttx` can waste time, leave processes running, or produce results you cannot trust.

The MQTTX AI Agent Skill closes that gap. It lives in the MQTTX repository and teaches an AI coding agent how to operate the `mqttx` command correctly and safely, using the same documentation the MQTTX team maintains.

## What the skill covers

The skill is organized around the tasks agents actually perform. Its `SKILL.md` routes the agent to a dedicated reference document for each task, so the agent only reads what it needs instead of loading the entire CLI manual into context.

- **Basic workflows**: `conn`, `pub`, and `sub`, plus bounded checks and publish/subscribe round trips.
- **Connections and authentication**: transport selection, TLS and mutual TLS, WebSocket headers, credentials, and SCRAM authentication.
- **MQTT features**: MQTT 3 and MQTT 5 behavior, QoS, retained messages, sessions, wills, request/response, and subscription properties.
- **Payloads and files**: text and binary input, interactive line mode, reading from files, codecs, Protobuf and Avro schemas, and random payloads.
- **Benchmarks and simulation**: `bench conn`, `bench pub`, `bench sub`, `simulate`, `ls --scenarios`, and custom generators.
- **Configuration and utilities**: `init`, `check`, help and version output, INI defaults, and JSON or YAML options.
- **Capability map**: exact flag availability by command and version-specific caveats.
- **Troubleshooting**: guidance for failures and diagnosis.

## Install MQTTX CLI with an agent

The MQTTX repository includes an installation guide written specifically for agents. It covers environment detection, package selection, and version verification. Give your agent this prompt:

> Read https://raw.githubusercontent.com/emqx/MQTTX/main/INSTALL.md and follow its instructions to install or update MQTTX CLI for this environment. Verify the executable path and version.

## Install the skill

Install the skill with the Skills CLI:

```shell
npx skills add emqx/MQTTX --skill mqttx-cli
```

If you work from a local checkout, run `npx skills add . --skill mqttx-cli` from the repository root. You can also copy the entire `skills/mqttx-cli` directory, including its `references`, into your agent's supported skills directory, or ask the agent to read the skill's `SKILL.md` directly.

## Try it

Once the CLI and the skill are installed, give your agent a task such as:

> Use the mqttx-cli skill to verify a publish/subscribe round trip against my local broker at 127.0.0.1:1883. Use a unique topic under mqttx-test/, finish within 15 seconds, and report the result.

The agent can then choose the right commands and flags, run the check, and report what happened.

## Learn more

- [MQTTX AI Agent Skill documentation](https://mqttx.app/docs/cli/agent-skill)
- [Skill source on GitHub](https://github.com/emqx/MQTTX/tree/main/skills/mqttx-cli)