opencode/skill/mqtts-developer/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