Do I need to manually confirm connections?

Yes. The workflow requires explicit user confirmation before connecting to unknown devices to prevent unintended access.

Where are device profiles stored and how are they organized?

Profiles are stored under ~/bluetooth/profiles, with one file per device. Interaction history is in history.md and new devices awaiting profiling go to pending.md.

Which tools and platforms are supported for cross-platform operation?

Linux uses bluetoothctl (with fallbacks like hcitool or gatttool), macOS uses blueutil (with system_profiler/CoreBluetooth), Windows uses WinRT/PowerShell, and cross-platform options include Bleak (Python) and Noble (Node.js).

Bluetooth

Scanned

@ivangdavila

npx machina-cli add skill @ivangdavila/bluetooth --openclaw

Files (1)

SKILL.md

2.0 KB

Core Workflow

Scan — Discover nearby devices
Identify — Match against known profiles or learn new device
Connect — Establish link with appropriate protocol
Execute — Send commands, read data, manage state
Learn — Update device profile based on interaction success/failure

Quick Reference

Need	Load
CLI commands by platform	`tools.md`
Device profile management	`profiles.md`
Security rules and warnings	`security.md`
Patterns by use case	`use-cases.md`

Workspace

Store device profiles and interaction history:

~/bluetooth/
├── profiles/         # Known device configs (one file per device)
├── history.md        # Interaction log with success/failure
└── pending.md        # Devices discovered but not profiled

Critical Rules

Never auto-connect to unknown devices — require explicit user confirmation
Whitelist first — only interact with pre-authorized devices
Log everything — every connection attempt, command, result
Fail gracefully — if device unreachable, retry with backoff, then report
Profile learning — when something works, save it; when it fails, note why

Platform Detection

OS	Primary Tool	Fallback
Linux	`bluetoothctl`	`hcitool`, `gatttool`
macOS	`blueutil`	`system_profiler`, CoreBluetooth
Windows	WinRT/PowerShell	`pnputil` for enumeration
Cross-platform	Bleak (Python)	Noble (Node.js)

Device Interaction Pattern

1. Check ~/bluetooth/profiles/ for device
2. If known → load profile, use saved commands
3. If unknown → scan characteristics, discover capabilities
4. Execute requested action
5. Verify result (read state, check acknowledgment)
6. Update profile: what worked, what failed, timing

Source

git clone https://clawhub.ai/ivangdavila/bluetoothView on GitHub

Overview

This skill enables discovering, connecting, and controlling Bluetooth devices while automatically learning and updating device profiles. It follows a core five-step workflow (Scan, Identify, Connect, Execute, Learn) and uses cross-platform tools to manage devices from a central workspace.

How This Skill Works

It scans for nearby devices, identifies them against known profiles or learns new ones, establishes a connection using the appropriate protocol, executes requested actions, and then updates the device profile based on success or failure. Profiles and history are stored under ~/bluetooth/profiles with dedicated history.md and pending.md files, while all activity is logged to support auditing and troubleshooting.

When to Use It

When adding a new Bluetooth device that isn't yet profiled and you want to generate a reusable profile.
When working across Linux, macOS, and Windows using platform-specific tools or cross-platform libraries.
When requiring explicit user confirmation before connecting to unknown devices.
When issuing commands to a device and needing to verify results and refine its profile.
When auditing device interactions and maintaining a history of connections and actions.

Quick Start

Step 1: Scan for nearby devices and identify whether they have existing profiles or are new.
Step 2: If known, load the profile; if unknown, perform characteristic discovery to learn capabilities.
Step 3: Connect, execute the requested action, verify the result, and let the Learn step update the profile accordingly.

Best Practices

Never auto-connect to unknown devices; require explicit user confirmation.
Whitelist pre-authorized devices first and restrict interactions accordingly.
Log every connection attempt, command, and result for traceability.
Fail gracefully with backoff on unreachable devices and report outcomes clearly.
Use the Learn phase to update profiles after successful interactions and note reasons for failures.

Example Use Cases

Pair and control a Bluetooth speaker by loading its known profile and issuing playback commands.
Discover and learn a BLE heart-rate monitor, then adapt commands based on characteristics.
Debug a BLE environmental sensor by exploring characteristics and updating the profile with capabilities.
Manage multiple headsets across Linux, macOS, and Windows with consistent profiles.
Audit device interactions by reviewing history.md and pending.md when profiling new devices.

Frequently Asked Questions

Add this skill to your agents