card-onboard
Onboard a user setting up AI Desk Card for the first time, or after moving to a new machine, plugging the device into a new network, or after a firmware update. Detects daemon state, USB / BLE / Wi-Fi connection, firmware version, and mDNS visibility — then walks the user through whatever's missing (install firmware, plug USB, pair BLE, provision Wi-Fi). Use whenever the user says "first-time setup" / "刚拿到设备" / "卡片没反应" / "刷固件" / "怎么连卡片" / "ai-desk-card 连不上".
Profile →npx skills add op7418/ai-desk-card --skill card-onboard --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# card-onboard — AI Desk Card 首次接入流程 把用户从"刚拿到设备/啥都没装"带到"四个 widget 在屏上、Wi-Fi 在线、推帧 0.2 秒到位"。 ## 一次性原则 - **永远先跑 probe**，不要凭空问"你 daemon 启动了吗"。`scripts/probe.sh` 一 次拿全所有状态。 - **每一步告诉用户当前进度**："我看到 daemon 跑着了，但还没设备连接， 现在去查串口..."。不要静默操作。 - **失败别循环重试**。卡住就停，把诊断结果给用户、让他决定。 - **优先推 Wi-Fi**，不要默认走 USB-serial 或 BLE。Wi-Fi 单帧 0.2 秒，USB 1-32 秒，BLE 命令通但 frame 不通（已知问题）。 ## 探针入口 ```bash bash $CLAUDE_PLUGIN_ROOT/skills/card-onboard/scripts/probe.sh ``` 输出结构（JSON）： ```jsonc { "daemon": { "running": bool, "pid": int|null }, "transport": { "connected": bool, "type": "SerialTransport|BLETransport|WiFiTransport|null" }, "firmware": { "our": bool, "note": str, "banner": str|null }, "serial_ports": [ "/dev/cu.usbserial-..." ], "mdns_peer": { "ip": "192.168.x.y", "port": 9880, "txt": { "fw": "0.8.0", "proto": "1" } } | null } ``` `firmware.our=true` = 设备上跑的是我们的固件（daemon 发了 `cmd:owner` 2.5 秒内收到 `ack:owner`）。 `mdns_peer != null` = **设备已经在 LAN 上播 Wi-Fi**，这是最理想的状态。 ## 决策树（按顺序处理；命中分支就先修，再回到 probe 验证） ### G — `mdns_peer != null` 且 `transport.type != "WiFiTransport"` 最理想状态被错过了。设备已在 Wi-Fi，但 daemon 没用 Wi-Fi。告诉用户： > 设备在 Wi-Fi `<ip>` 已上线。你 daemon 没用它，估计是之前没重启过 daemon。 跑： ```bash /card-stop && /card-start ``` 回到 probe，应该
- 一次性原则
- 探针入口
- 决策树（按顺序处理；命中分支就先修，再回到 probe 验证）
- G — mdnspeer != null 且 transport.type != "WiFiTransport"
- A — daemon.running == false
- B — daemon.running == true && serialports == [] && mdnspeer == null
- C — transport.connected == false 但 serialports != []
- D — transport.connected == true && firmware.our == false
- E — transport.connected == true && firmware.our == true 但 mdnspeer == null
- F — 全绿，要不要推默认 widget
- Z — 用户明确要用 BLE only（不推荐）
- 安抚话术
- 不要做的事
- 排错信息收集
bash $CLAUDE_PLUGIN_ROOT/skills/card-onboard/scripts/probe.sh
tail -30 "${TMPDIR:-/tmp}/ai_desk_card_daemon.log"
ioreg -p IOUSB | grep -i 'usb\|m5\|silab\|ftdi' | head -10What does the card-onboard skill do?
Onboard a user setting up AI Desk Card for the first time, or after moving to a new machine, plugging the device into a new network, or after a firmware update. Detects daemon state, USB / BLE / Wi-Fi connection, firmware version, and mDNS visibility — then walks the user through whatever's missing (install firmware, plug USB, pair BLE, provision Wi-Fi). Use whenever the user says "first-time setup" / "刚拿到设备" / "卡片没反应" / "刷固件" / "怎么连卡片" / "ai-desk-card 连不上".
How do I install it?
Run `npx skills add op7418/ai-desk-card --skill card-onboard --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From op7418/ai-desk-card, a repository with 136 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.