bluetooth-debug

name	bluetooth-debug
description	This skill should be used when the user asks to "debug bluetooth", "bluetooth not working", "check bluetooth", "airpods not connecting", "bluetooth devices", or mentions pairing issues. Collects Bluetooth state on macOS and writes a JSON result to ~/.mac-guardian/data/.

bluetooth-debug

Reports on the Bluetooth subsystem: controller power state, paired devices, connected devices, battery levels where available, and recent log events.

When to invoke

Trigger on phrases like: "debug bluetooth", "bluetooth not working", "check bluetooth", "airpods not connecting", "bluetooth devices".

Primary source

system_profiler SPBluetoothDataType -json 2>/dev/null.

Parse the resulting JSON with jq when available, otherwise with grep/awk. Key fields of interest:

• controller_properties.controller_state (On / Off)
• controller_properties.controller_address
• device_connected (array of currently connected devices)
• device_not_connected (array of paired but disconnected devices)

For each device, extract:

• device_name (or first key if unnamed)
• device_address
• device_batteryLevelMain / device_batteryLevelLeft / device_batteryLevelRight / device_batteryLevelCase
• device_firmwareVersion
• device_productID / device_vendorID

Severity

• Controller off: warn with summary "Bluetooth is off."
• Controller on, any connected device battery < 20%: warn per device.
• Controller on, otherwise: ok.

Recent events

log show --style compact --last 2h --predicate 'subsystem CONTAINS "bluetooth"' 2>/dev/null | tail -40.

Truncate and include in raw.log_tail. Skip gracefully on no output.

Output contract

Standard envelope. Write to ~/.mac-guardian/data/bluetooth-debug-<ISOdate>.json.

Summary example: "Controller on, 3 paired (2 connected). AirPods Pro 14% battery."

Handoff

• On direct invocation: bash ${CLAUDE_PLUGIN_ROOT}/scripts/render-single.sh bluetooth-debug.
• When invoked by daily-health-report, return JSON path only.

Safety

• Read-only. Never unpair devices, never toggle Bluetooth.
• Do not request sudo.
• If system_profiler is not installed (very unusual), emit an info finding explaining the missing tool and exit cleanly.