opencode/skill/emqx/SKILL.md

MQTTS Developer Skill

Overview

Complete MQTTS (MQTT over TLS) certificate management and client development skill set. This skill provides automated workflows for setting up secure MQTT brokers with auto-renewable certificates and comprehensive client configuration guides.

Skill Components

This skill consists of 5 integrated knowledge modules:

1. setup-mqtts-acme.md

Complete MQTTS Auto-Certificate Setup Workflow

• Automated certificate issuance using acme.sh with DNS validation
• Support for Alibaba Cloud DNS API (extensible to other providers)
• EMQX Docker container reconfiguration
• Auto-renewal setup with reload hooks
• Comprehensive validation and troubleshooting

Use when: Setting up MQTTS for the first time or migrating to new domain

2. mqtts-quick-reference.md

Quick Reference Guide

• Common commands for certificate and EMQX management
• One-line diagnostic scripts
• Testing commands
• Key concepts and troubleshooting

Use when: Need quick command lookup or emergency troubleshooting

3. mqtts-client-config.md

Multi-Language Client Configuration Guide

• Python, Node.js, Java, C#, Go, ESP32/Arduino examples
• System CA vs fullchain.pem decision guide
• Single-direction TLS authentication explained
• Security best practices

Use when: Developing MQTT clients or solving connection issues

4. README.md

Skill Usage Guide

• How to use these skills effectively
• Usage scenarios and examples
• Learning path recommendations
• Maintenance guidelines

5. USAGE_EXAMPLES.md

Practical Usage Examples

• Real conversation examples
• Token-saving techniques
• Common scenarios and solutions

Quick Start

Scenario 1: Setup MQTTS for New Domain

I need to configure MQTTS for domain mq.example.com using Alibaba Cloud DNS.
Please follow the setup-mqtts-acme skill.

Scenario 2: Diagnose MQTTS Issues

According to mqtts-quick-reference, help me diagnose 
the MQTTS status of mq.example.com.

Scenario 3: Develop Client

Based on mqtts-client-config, help me write a Python MQTT client
that connects using system CA.

Parameters

When invoking this skill, provide:

• domain: MQTT domain name (e.g., mq.example.com)
• dns_provider: DNS provider for ACME validation (default: dns_ali)
• ca: Certificate Authority (default: zerossl, options: letsencrypt)
• emqx_container: EMQX container name (default: emqx)
• client_language: For client examples (python, nodejs, java, etc.)

Key Features

✅ Automated Setup: 10-phase automated workflow from DNS verification to final validation ✅ Auto-Renewal: Configured with cron job and Docker container restart ✅ Multi-Language: Client examples for 7+ programming languages ✅ Token Efficient: Reusable knowledge base saves 60-80% tokens ✅ Production Ready: Security best practices and comprehensive error handling ✅ Well Documented: 1700+ lines of structured knowledge

Prerequisites

• EMQX 5.x running in Docker
• acme.sh installed
• DNS provider API credentials configured
• Docker with sufficient permissions

Success Criteria

After using this skill, you should have:

• ✅ Valid TLS certificate for MQTT domain
• ✅ MQTTS listener running on port 8883
• ✅ Auto-renewal configured (checks daily)
• ✅ Client connection examples for your language
• ✅ Complete documentation and backup package

Token Efficiency

Using this skill vs. explaining from scratch:

• First use: Saves 60-70% tokens
• Repeated use: Saves 80%+ tokens
• Example: Full setup guidance ~3000 tokens → ~600 tokens with skill

Support Matrix

Certificate Authorities

• ZeroSSL (default)
• Let's Encrypt
• BuyPass (via acme.sh)

DNS Providers

• Alibaba Cloud (dns_ali) - primary
• Other 80+ providers supported by acme.sh

MQTT Brokers

• EMQX 5.x (primary)
• Adaptable to other MQTT brokers

Client Platforms

• PC/Mac/Linux (System CA)
• Android/iOS (System CA)
• ESP32/Arduino (fullchain.pem)
• Embedded Linux (fullchain.pem)

Related Skills

This skill can be extended to:

• mqtts-nginx: MQTTS with Nginx reverse proxy
• mqtts-mtls: Mutual TLS authentication setup
• mqtts-monitoring: Certificate monitoring and alerting
• mqtts-ha-cluster: High availability cluster configuration

Troubleshooting

Each component includes comprehensive troubleshooting sections for:

• DNS resolution issues
• Certificate validation errors
• SSL handshake failures
• Client connection problems
• Container startup issues
• Memory constraints (embedded devices)

Maintenance

Skills are versioned and maintained:

• Version: 1.0
• Last Updated: 2026-01-07
• Compatibility: EMQX 5.8.8, acme.sh latest

Usage Tips

1. Specify the skill: Always mention the skill component name

   • Good: "According to setup-mqtts-acme skill..."
   • Bad: "Help me setup MQTTS" (might not use skill)

2. Provide context: Include domain, DNS provider, container name

   • Good: "Domain mq.example.com, Alibaba DNS, container emqx"
   • Bad: "Setup certificate" (missing details)

3. Use staged approach: For complex tasks, break into phases

   • First: Check prerequisites
   • Then: Issue certificate
   • Finally: Configure container

4. Reference troubleshooting: When encountering errors

   • "According to [skill] troubleshooting, how to fix [error]?"

File Structure

skill/mqtts-developer/
├── SKILL.md                    (This file - main entry point)
├── setup-mqtts-acme.md        (Setup workflow)
├── mqtts-quick-reference.md   (Quick reference)
├── mqtts-client-config.md     (Client guide)
├── README.md                  (Usage guide)
└── USAGE_EXAMPLES.md          (Examples)

Statistics

• Total Size: 52KB
• Total Lines: 1750+ lines
• Code Examples: 20+ complete examples
• Languages Covered: 7+ programming languages
• Commands Documented: 50+ common commands

Contributing

To extend or improve this skill:

1. Add new scenarios to USAGE_EXAMPLES.md
2. Add new language examples to mqtts-client-config.md
3. Add new DNS providers to setup-mqtts-acme.md
4. Report issues or improvements needed

License

Part of OpenCode Skills Library