onboard

Onboard

This skill walks a user through first-time configuration of their Zigbee home network environment. It captures the MQTT broker location and credentials, identifies the Zigbee coordinator (SMLight, Sonoff, ConBee, etc.), optionally records Home Assistant access details, generates a dedicated MQTT username/password pair for Claude's use, detects available companion MCPs, and designates a directory for network exports and backups. All configuration is stored in ${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/zigbee-home-maintenance/config.json.

Subsequent skills in this plugin resolve the same CONFIG_DIR and read config.json to locate the broker, coordinator, and Home Assistant targets.

When to use

• First time opening the plugin and no configuration exists
• User wants to re-verify or update existing configuration (broker moved, coordinator swapped, etc.)
• User needs to regenerate the MQTT credential for Claude

Inputs to gather

• MQTT broker type, IP address, port, TLS mode, and whether it runs as a Home Assistant add-on
• Zigbee coordinator type (picklist: SMLight SLZB-06/07, Sonoff ZBDongle-E/P, ConBee II/III, HA Yellow/SkyConnect, other)
• Coordinator connection mode (networked with IP, or USB-attached to a named host)
• Zigbee stack in use (Zigbee2MQTT or ZHA)
• Home Assistant availability (optional) — IP and base URL if in use
• Desired directory for network exports and device backups

Procedure

1. Resolve and check configuration directory. Compute CONFIG_DIR="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/zigbee-home-maintenance" and create it if missing (mkdir -p "$CONFIG_DIR"). If $CONFIG_DIR/config.json already exists, read it, present the current values to the user, and offer three choices: (a) keep as-is, (b) update specific fields only, or (c) re-onboard from scratch. Proceed based on the choice.

2. MQTT broker details. Ask the user for:

   • Broker type (e.g., Mosquitto, EMQX, HiveMQ). Suggest Mosquitto as default.
   • Broker LAN IP address (e.g., 192.168.1.100).
   • Port (default 1883; 8883 for TLS).
   • Whether TLS is enabled (yes/no).
   • Whether the broker runs as a Home Assistant add-on (yes/no) — this affects credential management instructions later.

3. Zigbee coordinator. Ask the user to identify their coordinator:

   • Type (picklist): SMLight SLZB-06/07, Sonoff ZBDongle-E/P, ConBee II/III, Home Assistant Yellow, Home Assistant SkyConnect, or other.
   • Connection mode: Is it networked (Ethernet or Wi-Fi, has its own IP) or USB-attached to a host?
     • If networked: capture its IP address.
     • If USB: capture the hostname or IP of the host it is plugged into (typically the Home Assistant server).
   • Firmware/stack in use: Zigbee2MQTT (publishes to MQTT) or ZHA (managed by Home Assistant directly). Note this choice in the config; later skills will branch on it.

4. Home Assistant (optional). Ask whether Home Assistant is in use. If yes: capture the HA host IP address and the base URL (e.g., http://homeassistant.local:8123 or http://192.168.1.x:8123). If no, record in_use: false.

5. Generate MQTT credential for Claude. Propose the username claude-zigbee-maintainer and generate a strong random password locally using openssl rand -base64 24. Display both to the user. Explain that this credential must be added to their MQTT broker's user list manually by the user:

   • If the broker is a Home Assistant Mosquitto add-on: instruct them to go to Settings → People → Users and add the user with "Can only log in from the local network" if appropriate.
   • If the broker is standalone Mosquitto: show the mosquitto_passwd <config-file> claude-zigbee-maintainer command they need to run.
   • Do not attempt to add the user automatically — broker authentication is out of scope for this skill. Only generate and instruct. Save the username and password to the config under mqtt.claude_credential.

6. Detect companion MCPs. Run claude mcp list 2>/dev/null and parse the output for the presence of these MCPs (case-insensitive): mosquitto, home-assistant, smlight, zigbee2mqtt. Record which ones are detected in the config under mcps.detected as an array. If any IoT-relevant MCPs are missing, inform the user which ones would enhance later skills (e.g., "The Mosquitto MCP would allow direct topic inspection") but note that the plugin will degrade gracefully without them.

7. User data store for network exports. Ask the user where they want Zigbee network backups, device inventories, and Zigbee2MQTT exports to be saved. Suggest ~/Documents/Zigbee-Network-Backups as a default. Create the directory if it doesn't exist. Store the absolute, expanded path in the config under paths.exports_dir. (User-owned data such as exports do not live under $CLAUDE_USER_DATA; this is a pointer to user-managed storage.)

8. Write config.json atomically. Use the following schema:

   {
     "version": 1,
     "mqtt": {
       "broker_type": "mosquitto",
       "host": "192.168.x.x",
       "port": 1883,
       "tls": false,
       "ha_addon": true,
       "claude_credential": {
         "username": "claude-zigbee-maintainer",
         "password": "<base64-random-string>"
       }
     },
     "coordinator": {
       "type": "smlight-slzb-06",
       "connection": "network",
       "host": "192.168.x.x",
       "stack": "zigbee2mqtt"
     },
     "home_assistant": {
       "in_use": true,
       "host": "192.168.x.x",
       "base_url": "http://homeassistant.local:8123"
     },
     "mcps": {
       "detected": ["home-assistant"]
     },
     "paths": {
       "exports_dir": "/home/<user>/Documents/Zigbee-Network-Backups"
     }
   }
   

   Write the file securely: chmod 600 "$CONFIG_DIR/config.json" after writing.

9. Print summary report. Show the user:

   • A recap of all captured values (MQTT broker, coordinator, HA details, export directory).
   • The absolute path where config is stored: $CONFIG_DIR/config.json.
   • What they still need to do: add the MQTT credential to their broker using the instructions from step 5, and optionally install any missing MCPs.
   • Confirmation that subsequent skills will automatically discover and use this config.

Output / side effects

• $CONFIG_DIR/config.json is created with all onboarding data, mode 600.
• The user's export directory is created if it does not exist.
• MQTT credential (username and password) are logged so the user can manually add them to their broker.
• The user receives clear instructions on next steps (adding the credential to the broker, installing optional MCPs).

Safety / constraints

• Credential handling: The generated MQTT password is printed during onboarding so the user can add it to their broker, but is not automatically transmitted or added to the broker. The user is responsible for the actual broker configuration.
• File permissions: config.json is written with mode 600 to protect credentials from other local users.
• No MCP installation: This skill detects available MCPs but does not install them. Users must install MCPs through their Claude CLI or other means.
• Broker authentication out of scope: The skill does not attempt to modify broker configuration files or authenticate directly with the broker. Only generation and instruction.