专业化的 AI 辅助开发工具集，让 MQTT X 开发更快速、更可靠

MQTT X Skills 是一套为 Claude Code 设计的专业化技能模块，旨在帮助开发者快速、高效地使用 MQTT X Go 库构建生产级 MQTT 应用程序。每个 Skill 都包含完整的代码模板、最佳实践、常见问题解决方案和详细的参考文档。

• 快速启动：5分钟内创建可运行的 MQTT 客户端
• 最佳实践：每个 Skill 都包含经过验证的生产级配置和模式
• 完整模板：开箱即用的代码模板，减少样板代码编写
• 场景化：针对不同应用场景提供专门的解决方案
• 文档齐全：详细的使用说明、示例代码和故障排查指南
• 自然交互：通过自然语言与 Claude 对话即可生成代码

这是 MQTT X 库的综合性主 SKILL，作为所有子技能的统一入口点。使用渐进式披露原则，帮助您快速找到所需功能。

主要特性：

• 📊 智能导航：通过决策树快速定位所需技能
• 🗺️ 场景映射：25+ 真实场景到技能的精准映射
• 🎓 学习路径：4 条系统化学习路径（新手/安全/性能/完整）
• 🔍 快速诊断：环境验证和问题诊断工具
• 📚 完整参考：API 速查表、技能概览、组合模式

适用场景：

• ✅ 首次使用 MQTT X，不确定从哪里开始
• ✅ 需要根据具体需求选择合适的技能
• ✅ 想要系统化学习 MQTT X 的所有功能
• ✅ 遇到问题需要快速诊断和解决

核心资源：

• 决策树 - 5 条决策路径帮您选择正确的技能
• 场景映射 - 25+ 场景的详细技能推荐
• 技能概览 - 所有 10 个子技能的完整对比
• 学习路径 - 4 条系统化学习计划
• API 速查 - 常用操作的快速参考
• 环境验证 - 一键检查开发环境
• 问题诊断 - 自动诊断常见问题

使用方式：

"Use mqttx skill to help me get started"
"I need to choose the right MQTT X skill for my use case"
"Show me the learning path for MQTT X"

---

新用户？从这里开始：

1. 完全新手 → 使用 mqttx 主 SKILL 获得引导
2. 快速上手 → 直接使用 mqttx-quickstart
3. 特定场景 → 查看下方场景分类或使用主 SKILL 的场景映射

• mqttx-quickstart - 快速创建第一个 MQTT 客户端
  • 5分钟快速上手
  • 基础连接、订阅、发布
  • Builder 模式配置

• mqttx-mqtt5 - MQTT 5.0 协议特性

  • 用户属性、主题别名
  • 增强认证（JWT、OAuth 2.0）
  • 共享订阅、请求-响应模式

• mqttx-events - 事件系统和生命周期管理

  • 连接事件监听
  • 自定义事件处理
  • 事件驱动架构

• mqttx-multi-session - 多会话管理

  • 并发连接管理
  • 负载均衡
  • 会话协调

• mqttx-message-forwarder - 消息转发器

  • 会话间消息路由
  • 主题映射和转换
  • 消息过滤

• mqttx-tls-security - TLS/SSL 安全配置
  • 基础 TLS 加密
  • 双向 TLS 认证
  • 证书管理和轮换

• mqttx-persistence - 持久化存储

  • Redis 会话持久化
  • 文件存储
  • QoS 消息持久化

• mqttx-performance - 性能优化

  • 吞吐量优化
  • 延迟优化
  • 内存和资源优化

• mqttx-testing - 测试和调试
  • 单元测试
  • 集成测试
  • 性能基准测试
  • Mock 测试

• mqttx-production - 生产环境部署
  • 健康检查
  • 监控和告警
  • 优雅关闭
  • 部署清单

• mqttx-quickstart - 基础连接
• mqttx-multi-session - 多会话
• mqttx-tls-security - 安全连接
• mqttx-mqtt5 - MQTT 5.0 连接

• mqttx-message-forwarder - 消息转发
• mqttx-events - 事件路由
• mqttx-mqtt5 - 共享订阅

• mqttx-persistence - 会话持久化
• mqttx-production - 生产级存储

• mqttx-tls-security - TLS 加密
• mqttx-mqtt5 - 增强认证
• mqttx-production - 生产安全

• mqttx-performance - 性能调优
• mqttx-production - 监控指标
• mqttx-testing - 性能测试

• mqttx-testing - 测试框架
• mqttx-quickstart - 快速原型

快速入门 - MQTT 客户端开发基础

• 何时使用：创建第一个 MQTT 客户端、快速原型开发、学习基础用法
• 包含内容：
  • 3 个代码模板（基础客户端、Builder 模式、订阅发布示例）
  • API 快速参考
  • 常见问题解决方案
• 学习时长：5 分钟
• 文件数：5 个

查看详情

---

TLS/SSL 安全配置 - 加密和证书认证

• 何时使用：生产环境部署、敏感数据传输、双向认证需求
• 包含内容：
  • 2 个代码模板（基础 TLS、双向 TLS）
  • 证书配置模板
  • 证书到期检查脚本
  • TLS 最佳实践指南
• 关键特性：服务器认证、客户端认证、证书轮换、安全清单
• 文件数：7 个

查看详情

---

消息转发器 - 会话间消息路由

• 何时使用：多会话消息转发、协议桥接、消息路由
• 包含内容：
  • 2 个代码模板（基础转发器、高级转发器）
  • 转发模式参考文档
• 关键特性：主题映射、消息过滤、双向转发、广播模式
• 文件数：4 个

查看详情

---

持久化存储 - Redis 和文件存储

• 何时使用：会话状态持久化、QoS 消息保证、会话恢复
• 包含内容：
  • 2 个代码模板（Redis 存储、文件存储）
  • 会话恢复示例
  • 存储配置模板
  • 存储对比指南
  • 持久化测试脚本
• 关键特性：Redis 集群、文件存储、自动恢复、存储选择
• 文件数：8 个

查看详情 | README

---

测试和调试 - 单元测试、集成测试、基准测试

• 何时使用：编写测试、性能测试、并发测试、调试
• 包含内容：
  • 3 个测试模板（单元测试、集成测试、基准测试）
  • 测试最佳实践文档
  • 测试运行脚本
  • 测试示例
• 关键特性：表驱动测试、Mock 对象、并发测试、性能基准
• 文件数：10 个

查看详情 | README | 示例

---

MQTT 5.0 特性 - 用户属性、增强认证、共享订阅

• 何时使用：需要 MQTT 5.0 特性、增强认证、共享订阅、主题别名
• 包含内容：
  • 3 个代码模板（基础 MQTT 5、高级特性、认证）
  • MQTT 5.0 特性详解
  • MQTT 3.1.1 vs 5.0 对比
  • 快速参考
  • MQTT 5 支持检查脚本
• 关键特性：用户属性、JWT/OAuth 2.0 认证、共享订阅、主题别名
• 文件数：9 个

查看详情 | README

---

事件系统 - 连接事件和生命周期管理

• 何时使用：监听连接事件、自定义事件处理、事件驱动架构
• 包含内容：
  • 3 个代码模板（事件驱动、事件处理、单事件）
  • 事件类型参考
  • 快速参考
• 关键特性：连接事件、消息事件、自定义事件、事件过滤
• 文件数：7 个

查看详情 | README

---

多会话管理 - 并发连接和负载均衡

• 何时使用：管理多个 MQTT 连接、负载均衡、高可用部署
• 包含内容：
  • 2 个代码模板（基础多会话、高级多会话）
  • 会话模式参考
• 关键特性：并发会话、负载均衡、会话协调、故障转移
• 文件数：4 个

查看详情

---

性能优化 - 吞吐量、延迟、内存优化

• 何时使用：性能调优、高吞吐量需求、低延迟需求、资源优化
• 包含内容：
  • 1 个性能调优模板
  • 性能指南
  • 基准测试脚本
• 关键特性：缓冲区配置、连接参数、QoS 选择、并发优化
• 文件数：5 个

查看详情 | README

---

生产环境部署 - 监控、健康检查、优雅关闭

• 何时使用：生产部署、监控告警、健康检查、运维
• 包含内容：
  • 1 个生产配置模板
  • 部署清单
  • 生产最佳实践
• 关键特性：健康检查、Prometheus 指标、优雅关闭、部署清单
• 文件数：3 个

查看详情

直接用自然语言描述你的需求，Claude 会自动选择合适的 Skill：

"我想创建一个基础的 MQTT 客户端，连接到 broker.emqx.io"
→ 自动使用 mqttx-quickstart Skill

"帮我配置 TLS 加密连接"
→ 自动使用 mqttx-tls-security Skill

"我需要实现多个 MQTT 会话的负载均衡"
→ 自动使用 mqttx-multi-session Skill

"配置 Redis 持久化存储"
→ 自动使用 mqttx-persistence Skill

"帮我优化 MQTT 应用的性能"
→ 自动使用 mqttx-performance Skill

"写单元测试覆盖订阅和发布功能"
→ 自动使用 mqttx-testing Skill

如果你知道需要哪个模板，可以直接引用：

"使用 mqttx-quickstart/assets/builder-pattern.go.tmpl
创建一个连接到 localhost:1883 的客户端"

"基于 mqttx-tls-security/assets/tls-mutual-auth.go.tmpl
配置双向 TLS 认证"

"参考 mqttx-testing/assets/benchmark-test.go.tmpl
编写性能基准测试"

复杂场景可以组合多个 Skills：

"创建一个安全的 MQTT 客户端，使用 TLS 加密，
支持 Redis 持久化，并包含完整的单元测试"

→ 结合使用：
  - mqttx-quickstart（基础结构）
  - mqttx-tls-security（TLS 配置）
  - mqttx-persistence（Redis 存储）
  - mqttx-testing（测试代码）

让 Claude 引导你完成整个流程：

"我是 MQTT X 新手，帮我从零开始创建一个生产级应用"

→ Claude 会按顺序引导你：
  1. quickstart - 创建基础客户端
  2. events - 添加事件处理
  3. tls-security - 配置安全连接
  4. persistence - 添加持久化
  5. testing - 编写测试
  6. production - 生产部署

从零开始学习 MQTT X：

1. mqttx-quickstart (5 分钟)

   • 创建第一个 MQTT 客户端
   • 理解基本概念：Session、Manager、Builder

2. mqttx-events (15 分钟)

   • 监听连接事件
   • 处理消息事件
   • 实现事件驱动逻辑

3. mqttx-multi-session (20 分钟)

   • 管理多个会话
   • 理解会话协调
   • 实现简单负载均衡

4. mqttx-testing (20 分钟)

   • 编写第一个单元测试
   • 理解测试模式
   • 运行基准测试

预期成果：能够创建、测试和运行基本的 MQTT 应用

---

构建安全的 MQTT 应用：

1. mqttx-quickstart (5 分钟)

   • 基础客户端

2. mqttx-tls-security (30 分钟)

   • 配置基础 TLS
   • 实现双向认证
   • 管理证书

3. mqttx-mqtt5 (30 分钟)

   • 配置增强认证
   • JWT/OAuth 2.0 集成
   • 用户属性安全

4. mqttx-production (60 分钟)

   • 生产安全配置
   • 安全监控
   • 安全审计

预期成果：能够部署符合企业安全标准的 MQTT 应用

---

构建高性能 MQTT 应用：

1. mqttx-quickstart (5 分钟)

   • 基础客户端

2. mqttx-performance (45 分钟)

   • 性能配置优化
   • 吞吐量优化
   • 延迟优化
   • 资源优化

3. mqttx-multi-session (30 分钟)

   • 多会话负载均衡
   • 并发优化

4. mqttx-testing (20 分钟)

   • 性能基准测试
   • 压力测试

5. mqttx-production (20 分钟)

   • 生产性能监控
   • 性能调优

预期成果：能够构建和优化高性能 MQTT 应用

---

从入门到生产部署的完整学习路径：

1. 基础阶段 (30 分钟)

   • mqttx-quickstart - 快速入门
   • mqttx-events - 事件处理

2. 进阶阶段 (90 分钟)

   • mqttx-multi-session - 多会话管理
   • mqttx-message-forwarder - 消息转发
   • mqttx-mqtt5 - MQTT 5.0 特性

3. 安全和持久化 (60 分钟)

   • mqttx-tls-security - TLS 配置
   • mqttx-persistence - 持久化存储

4. 优化阶段 (60 分钟)

   • mqttx-performance - 性能优化
   • mqttx-testing - 测试和调试

5. 生产阶段 (90 分钟)

   • mqttx-production - 生产部署

预期成果：能够独立设计、开发、测试和部署生产级 MQTT 应用

下表展示每个 Skill 覆盖的功能点：

Skill	基础连接	安全	持久化	性能	测试	监控	MQTT 5.0	多会话	事件
quickstart	✅	-	-	-	-	-	-	-	-
tls-security	✅	✅	-	-	-	-	-	-	-
message-forwarder	✅	-	-	✅	-	-	-	✅	-
persistence	✅	-	✅	-	-	-	-	-	-
testing	-	-	-	✅	✅	✅	-	-	-
mqtt5	✅	✅	-	-	-	-	✅	-	-
events	✅	-	-	-	-	✅	-	-	✅
multi-session	✅	-	-	✅	-	-	-	✅	-
performance	✅	-	-	✅	✅	✅	-	✅	-
production	✅	✅	✅	✅	-	✅	-	✅	✅

图例：

• ✅ 核心功能
• • 不涉及

根据不同应用场景，推荐使用的 Skills 组合：

需求：大量设备定期上报数据

推荐 Skills：

1. mqttx-quickstart - 基础连接
2. mqttx-multi-session - 多设备管理
3. mqttx-persistence - 数据持久化
4. mqttx-performance - 高吞吐优化

---

需求：低延迟、高可靠、安全

推荐 Skills：

1. mqttx-quickstart - 基础连接
2. mqttx-tls-security - 双向 TLS
3. mqttx-performance - 低延迟优化
4. mqttx-production - 生产监控

---

需求：多设备、消息路由、本地处理

推荐 Skills：

1. mqttx-multi-session - 多设备连接
2. mqttx-message-forwarder - 消息路由
3. mqttx-events - 事件处理
4. mqttx-persistence - 本地存储

---

需求：高可用、大规模、监控

推荐 Skills：

1. mqttx-multi-session - 负载均衡
2. mqttx-mqtt5 - 共享订阅
3. mqttx-persistence - Redis 集群
4. mqttx-production - 监控告警

---

需求：移动网络、断线重连、QoS 保证

推荐 Skills：

1. mqttx-quickstart - 基础连接
2. mqttx-persistence - QoS 持久化
3. mqttx-events - 连接事件
4. mqttx-tls-security - 安全通信

---

需求：安全、可靠、审计

推荐 Skills：

1. mqttx-tls-security - 加密认证
2. mqttx-mqtt5 - 增强认证
3. mqttx-persistence - 消息持久化
4. mqttx-production - 审计日志

---

需求：资源受限、本地处理、云边协同

推荐 Skills：

1. mqttx-quickstart - 基础连接
2. mqttx-performance - 资源优化
3. mqttx-message-forwarder - 云边消息
4. mqttx-events - 本地事件处理

---

需求：快速迭代、完整测试、调试

推荐 Skills：

1. mqttx-quickstart - 快速原型
2. mqttx-testing - 单元测试
3. mqttx-events - 调试事件
4. mqttx-performance - 性能测试

如果你想贡献新的 Skill，请遵循以下步骤：

docs/skills/mqttx-your-skill/
├── SKILL.md              # 主 Skill 文档（必需）
├── README.md             # 详细说明（可选）
├── assets/               # 代码模板目录
│   ├── template1.go.tmpl
│   ├── template2.go.tmpl
│   └── config.yaml.tmpl
├── references/           # 参考文档目录
│   ├── guide.md
│   └── best-practices.md
└── scripts/              # 辅助脚本目录
    └── helper.sh

SKILL.md 是核心文档，必须包含以下部分：

---
name: mqttx-your-skill
description: 简短描述。Use when user needs... (触发条件)
---

# MQTT X Your Skill

一句话简介

## When to Use This Skill

列出具体使用场景：
- 场景 1
- 场景 2
- 场景 3

## Prerequisites

列出依赖和前置条件

## Instructions

### Step 1: 标题
详细步骤说明

### Step 2: 标题
详细步骤说明

## Examples

### Example 1: 标题
完整代码示例

### Example 2: 标题
完整代码示例

## Common Issues

常见问题和解决方案

## Related Skills

相关 Skills 链接

## References

参考文档和资源

在 assets/ 目录创建 .go.tmpl 模板文件：

// assets/example.go.tmpl
package main

import (
    "log"
    "github.com/darkit/mqttx"
)

func main() {
    // {{.Description}}

    manager := mqttx.NewSessionManager()
    defer manager.Close()

    // Configuration
    opts := mqttx.DefaultOptions()
    opts.Name = "{{.SessionName}}"
    opts.Brokers = []string{"{{.BrokerAddr}}"}

    // Your skill specific code here

    if err := manager.AddSession(opts); err != nil {
        log.Fatal(err)
    }

    select {}
}

在 references/ 目录创建详细的参考文档：

• 最佳实践指南
• 配置参数说明
• 架构设计文档
• 故障排查指南

在 scripts/ 目录创建辅助脚本：

#!/bin/bash
# scripts/helper.sh

# 帮助用户快速完成某些操作的脚本

在 docs/skills/README.md (本文档) 中添加新 Skill 的信息。

• Skill 目录名：mqttx-{skill-name} (小写，连字符分隔)
• Skill name 字段：mqttx-{skill-name} (与目录名一致)
• 模板文件：{purpose}.go.tmpl (小写，连字符分隔)

• 清晰的触发条件：在 description 字段明确说明何时使用
• 完整的示例：每个示例都应该是可运行的完整代码
• 常见问题：包含至少 3-5 个常见问题及解决方案
• 相关链接：链接到相关 Skills 和参考文档

• 注释充分：每个重要部分都有注释说明
• 可配置：使用模板变量（如 {{.BrokerAddr}}）
• 最佳实践：代码体现最佳实践
• 完整性：包含错误处理、资源清理等

• 可验证：示例代码必须经过测试验证
• 依赖明确：清楚说明外部依赖（如 Redis、MQTT Broker）
• 环境说明：说明运行环境要求

1. Fork 项目：Fork MQTT X 仓库到你的账号
2. 创建分支：git checkout -b skill/your-skill-name
3. 开发 Skill：按照上述规范创建 Skill
4. 测试验证：确保所有示例代码可运行
5. 提交代码：

   git add docs/skills/mqttx-your-skill/
   git commit -m "docs(skills): add mqttx-your-skill"
   git push origin skill/your-skill-name
   

6. 创建 PR：在 GitHub 创建 Pull Request

PR 将根据以下标准进行审查：

• ✅ 目录结构符合规范
• ✅ SKILL.md 包含所有必需部分
• ✅ 代码模板可运行且符合最佳实践
• ✅ 文档清晰、准确、完整
• ✅ 示例代码经过测试
• ✅ 链接正确无误
• ✅ 中英文文档一致（如适用）

• MQTT X 项目主页：GitHub
• 完整使用文档：/workspace/docs/使用指南.md
• API 文档：/workspace/docs/API文档.md
• 高级特性文档：/workspace/docs/高级特性.md
• 性能调优指南：/workspace/docs/性能调优指南.md

• 基础示例：/workspace/examples/basic_client/
• 高级示例：/workspace/examples/advanced_client/
• TLS 示例：/workspace/examples/enhanced_tls/
• MQTT 5 示例：/workspace/examples/mqtt5_auth/

• MQTT 协议规范：

  • MQTT 3.1.1 规范
  • MQTT 5.0 规范

• MQTT Broker：

  • EMQX - 企业级 MQTT Broker
  • Mosquitto - 轻量级 MQTT Broker
  • HiveMQ - 企业级 MQTT 平台

• 测试工具：

  • MQTT X - MQTT 客户端测试工具
  • MQTT.fx - MQTT 客户端
  • mosquitto_pub/sub - 命令行工具

• 监控工具：

  • Prometheus - 监控和告警
  • Grafana - 可视化面板
  • Jaeger - 分布式追踪

• Claude Code 官方文档：了解如何使用 Claude Code
• Skills 开发指南：学习如何创建自定义 Skills

发布日期：2025-11

包含 Skills：

• mqttx - 综合性主 SKILL（统一入口）
• mqttx-quickstart
• mqttx-tls-security
• mqttx-message-forwarder
• mqttx-persistence
• mqttx-testing
• mqttx-mqtt5
• mqttx-events
• mqttx-multi-session
• mqttx-performance
• mqttx-production

总计：1 个主 SKILL + 10 个子 Skills，72 个文件

主 SKILL 包含：

• 1 个主配置文件（SKILL.md）
• 2 个决策支持工具（决策树、场景映射）
• 3 个参考文档（技能概览、API 速查、学习路径）
• 2 个可执行脚本（环境验证、问题诊断）

如果你在使用 Skills 过程中遇到问题：

1. 检查文档：首先查看相关 Skill 的文档和 Common Issues 部分
2. 搜索问题：在 GitHub Issues 中搜索是否已有类似问题
3. 提交 Issue：如果是新问题，在 GitHub 提交 Issue，包含：
   • 使用的 Skill 名称
   • 问题描述
   • 复现步骤
   • 错误信息
   • 环境信息（Go 版本、MQTT Broker 等）

如果你有新的 Skill 想法或功能建议：

1. 提交 Feature Request：在 GitHub Issues 提交功能请求
2. 描述使用场景：说明这个功能解决什么问题
3. 参与讨论：与社区讨论实现方案

欢迎贡献：

• 新的 Skills
• 代码模板改进
• 文档完善
• 问题修复
• 示例代码

本 Skills 体系遵循 MQTT X 项目的开源许可证。

---

最后更新：2025-11-29 维护者：MQTT X Team 文档版本：1.0.0