flipper-ble-mcp: Skill for Claude Code

Flipper Zero — KB-aware operating skill

The Flipper knowledge base in this repo is your memory; the flipper / flipper-control / flipper-ble MCP servers are your hands. This skill is the loop that ties them together so the system gets faster every session: read the KB before acting, drive the device safely, then pour what you learned back into the KB. Don't re-derive what a doc already records — and don't let a hard-won learning evaporate when the session ends.

Read CLAUDE.md (house style) once per session if you'll write to the KB. The deep "how to drive the device" knowledge already lives in resources/flipper-control-playbook.md and resources/flipper-ble-control.md — this skill routes to those rather than repeating them.

The operating loop — run EVERY Flipper task this way

1 · ORIENT (read before you touch the device)

Cheap reads first — they save device round-trips and prevent dead ends.

• Map the task to docs. Start at llms.txt (token-lean doc map). Then narrow:
  • By use case: most requests map to a UC — resolve it in uc-index.json (UC-ID → docs) or scan use-cases-model.md.
  • By topic: grep -rl "^domain: wifi" . (or nfc, bluetooth, …), then follow each doc's related: graph.
  • Read the matching guide/reference's TL;DR + body. The common ones are in references/routine-index.md — open it for the task→doc→tools map. For any add-on task (Marauder / NRF24 / CC1101 / GPS), also open its hardware/ board doc — physical gotchas (power, mounting, dual-SD, band limits) live there, not in the capability doc.
• Pre-flight the device & pick a transport. USB read: mcp__flipper__status. BLE: mcp__flipper-ble__ping (and scan only if it's not answering). Orientation manual: mcp__flipper-ble__playbook. Check app_lock_status / desktop_is_locked before launching anything. One BLE central at a time — if the user's phone holds the Flipper, BLE says "not found"; they free the phone's app.
• Choose the path with the data-first ladder (from the playbook): pure data read (storage_read/list/device_info) → direct app-entry (app_launch name=<full .fap path>) → semantic action → batched blind nav (press_sequence + one trailing screenshot) → screenshot loop (only for dynamic UI). Prefer reading an SD artifact over reading pixels.
• The constraint that re-routes everything: apps that seize the USB serial (WiFi Marauder, other ESP32/UART apps) kill the USB MCP servers while running → drive them over BLE, and read results from the SD log, not the 128×64 screen. The worked exemplar is wifi/marauder-mcp-scan.md.