Bluetooth debug

Skill dennisonbertram/claude-mac-guardian/skills/bluetooth-debug

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/.From its SKILL.md

Install

npx -y skills add dennisonbertram/claude-mac-guardian --skill bluetooth-debug

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.2 KB, as published. Nobody here has run it

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.