agentsclimarketplace

Ha bluetooth augment

Skill nolte/claude-home-assistant/skills/ha-bluetooth-augment

Augments an existing Home Assistant Custom Integration with Bluetooth support, conforming to spec/ha/bluetooth. Sets the manifest bluetooth matcher list plus the bluetooth_adapters dependency, subscribes to advertisements via bluetooth.async_register_callback with an explicit scanning mode bound through entry.async_on_unload, picks the right Bluetooth coordinator family (passive/active processor or DataUpdate variants), and wires device/service-info lookups over the shared scanner. Keeps passive (connectable=False) as the default. Part of the Gold discovery family, sibling of ha-discovery-augment. Activate on "add bluetooth discovery/support", "listen for BLE advertisements", or equivalent German requests. Do not activate for DHCP/SSDP/USB/HomeKit/Zeroconf discovery (ha-discovery-augment), the config-flow discovery step (ha-config-flow-augment), the generic polling coordinator (ha/coordinator-patterns), greenfield scaffolding (ha-integration-scaffold), or deploying to a live HA instance.From its SKILL.md

Install
npx -y skills add nolte/claude-home-assistant --skill ha-bluetooth-augment

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

10.0 KB, as published. Nobody here has run it

HA Bluetooth Augment

Spec: spec/claude/ha-bluetooth-augment/en.md (EN canonical) / spec/claude/ha-bluetooth-augment/de.md (DE translation).

Why this is a skill, not an agent

  • Human-visible augmentation surface — the user describes how the device advertises and reads back the manifest matcher, the callback registration, the coordinator family, and the conformance report; a skill keeps this on the visible command surface, like the sibling augment skills (ha-discovery-augment, ha-config-flow-augment, ha-coordinator-add).
  • Mid-flow interactivity — the passive-vs-connectable decision, the coordinator-family choice, and the network-discovery redirect are per-run dialogues the user approves before generation.
  • Bounded, inline generation — the manifest matcher plus the callback registration and the coordinator wiring fit inline; no isolated agent context is needed.
  • Counter-dimension considered: the draft→validate loop could be an agent, but the connectable decision and the trade-off advice belong in the user's working context; skill wins.

When this skill activates

Use this skill to add Bluetooth support — central BLE discovery plus advertisement-driven data fetching — to an existing integration, typically for a device that delivers its data over BLE advertisements (the passive default) or needs an occasional active connection.

When NOT to activate

  • DHCP/SSDP/USB/HomeKit/Zeroconf network or bus discovery → ha-discovery-augment / ha/discovery-mechanisms
  • the config-flow Bluetooth discovery step / generic config-flow auth steps → ha-config-flow-augment / ha/config-flow-patterns
  • the generic polling-based DataUpdateCoordinator for REST/cloud APIs → ha/coordinator-patterns
  • greenfield integration scaffolding → ha-integration-scaffold
  • deploying/importing into a running HA instance → out of scope

Hard rules

  1. Read spec/ha/bluetooth/en.md first. Do not generate HA internals from memory.
  2. Right mechanism, with delimitation. DHCP/SSDP/USB/HomeKit/Zeroconf → ha-discovery-augment; the full config-flow discovery step → ha-config-flow-augment. Redirect rather than augmenting the wrong one.
  3. Manifest matcher + dependency. The bluetooth key is a list of matcher dicts from the documented fields (service_uuid, local_name, manufacturer_id, service_data_uuid, connectable); add bluetooth_adapters to dependencies when the integration uses an adapter.
  4. Passive is the default. Operate connectable=False whenever the device delivers data through advertisements only — that opts in to non-connectable controllers. Use connectable=True (the field default) only where an outgoing connection is actually needed; set the flag per device for mixed devices.
  5. Advertisement callbacks. Subscribe via bluetooth.async_register_callback(hass, callback, matcher, mode) with a BluetoothCallbackMatcher and an explicit bluetooth.BluetoothScanningMode (ACTIVE/PASSIVE). The callback is @callback, synchronous, signature (service_info: BluetoothServiceInfoBleak, change: BluetoothChange) -> None. Bind the returned cancel callback via entry.async_on_unload(...).
  6. Lookups, never an own scanner. Get a BLEDevice via bluetooth.async_ble_device_from_address(hass, address, connectable) and handle the None case (no adapter in range); read latest info via bluetooth.async_last_service_info; check bluetooth.async_scanner_count(hass, connectable=True) at setup when connecting. Never instantiate an own BleakScanner.
  7. Right coordinator family. PassiveBluetoothProcessorCoordinator for sensors/binary sensors/events from advertisements; ActiveBluetoothProcessorCoordinator on connection need; the DataUpdate variants for non-sensor entities; the generic DataUpdateCoordinator only on pure connection communication with no advertisements. Processor coordinators format PassiveBluetoothDataUpdate (indexed by PassiveBluetoothEntityKey) and bind coordinator.async_start() to entry.async_on_unload(...) only after async_forward_entry_setups. Active variants check CoreState.running and a reachable connectable BLEDevice in needs_poll_method.
  8. Connection handling. For active connections use bluetooth.async_get_scanner(hass), a fresh BleakClient per connection, a timeout ≥ 10 s, and bleak-retry-connector; never hold a permanent connection when the data is in advertisements.
  9. Name per spec/ha/naming-conventions/en.md and verify HA internals against the official docs (see spec/ha/upstream-docs-verification/en.md).

Inputs

FieldRequiredDefaultNotes
target_diryes—repo root; custom_components/<domain>/manifest.json must exist
device_behaviouryes—how the device advertises, and whether data is advertisement-only or needs an active connection
matcher fieldsnoasked when neededservice_uuid / service_data_uuid / manufacturer_id / local_name / connectable
modenoderived (PASSIVE default)BluetoothScanningMode PASSIVE / ACTIVE
coordinator familynoinferred + confirmedpassive/active processor vs. DataUpdate variant

If the user is silent on an optional field, use the default but state it explicitly.

Pre-flight (in order — abort on first failure)

  1. target_dir/custom_components/<domain>/manifest.json exists; read domain.
  2. Delimit the mechanism: on a DHCP/SSDP/USB/HomeKit/Zeroconf situation redirect to ha-discovery-augment and stop; point a full config-flow discovery step at ha-config-flow-augment.
  3. Read ha/bluetooth.
  4. No bluetooth matcher / callback / coordinator registration is already declared. If it is, abort.

Workflow

1) Resolve and confirm

State domain, the matcher fields, the resolved connectable (default False for advertisement-only) and BluetoothScanningMode, the chosen coordinator family, and every assumed default in one paragraph. Wait for confirmation.

2) Generate

ConcernArtifactKey contract
discoverymanifest.json bluetooth list (+ bluetooth_adapters in dependencies on adapter use)matcher dicts from the documented fields; connectable per device
advertisementsasync_register_callback + @callbackBluetoothCallbackMatcher, explicit BluetoothScanningMode, bound via entry.async_on_unload
coordinatorpassive/active processor or DataUpdate variantPassiveBluetoothDataUpdate; async_start() after async_forward_entry_setups
connection (active only)async_get_scanner + bleak-retry-connectorfresh BleakClient, timeout ≥ 10 s

Use lookups (async_ble_device_from_address with None handling, async_last_service_info, async_scanner_count) instead of starting an own scanner.

3) Validate and report

Validate offline (manifest matcher, plus bluetooth_adapters in dependencies on adapter use; async_register_callback with @callback signature, bound via entry.async_on_unload; async_ble_device_from_address with None handling; passive default; use-case-correct coordinator family formatting PassiveBluetoothDataUpdate and starting after async_forward_entry_setups; connections via async_get_scanner, fresh BleakClient, timeout ≥ 10 s, bleak-retry-connector). Emit a CONFORMANT / NEEDS-WORK report keyed to ha/bluetooth acceptance criteria, plus the changed file paths and the quality-scale marker (Gold: discovery).

4) No deploy

The skill never deploys to a live HA instance. Surface the report and stop.

Boundaries

  • DHCP/SSDP/USB/HomeKit/Zeroconf network discovery → ha-discovery-augment
  • Config-flow Bluetooth discovery step / generic config-flow steps → ha-config-flow-augment
  • Generic polling DataUpdateCoordinator → ha/coordinator-patterns
  • Greenfield scaffold → ha-integration-scaffold
  • Deploy to live HA → out of scope

Keep looking

Skills are one crate of 608,666. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.