К основному содержанию
скилл CX Codex

flashduck-dev — скилл для Claude Code: разработка и установка

Скилл flashduck-dev для Claude Code помогает собирать и менять прошивки робота Flashduck. Запускается при работе с голосовой прошивкой, DuckClaw или общим шестисервоприводным оборудованием.

MIT ★ 187 обновлён 2026-11-03

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add FlashCat-Jordan/Flashduck --skill flashduck-dev -a claude-code
Открыть на GitHub

Что делает flashduck-dev

Скилл проверяет среду разработки и помогает собрать, прошить и менять прошивки Flashduck. Он охватывает голосовую прошивку в firmware/voice и DuckClaw в firmware/duckclaw: настройки глаз, действий и походки, веб-настройку, MCP-инструменты, инструменты и промпты DuckClaw. Это два независимых проекта ESP-IDF; одновременно прошивки работать не могут, а прошивка одной заменяет другую.

Перед сборкой запускается bash skills/flashduck-dev/scripts/check-env.sh. Проверка охватывает Python 3, Git, CMake, Ninja, ESP-IDF версии 6.0.1 или выше и esptool; если чего-то не хватает, скилл предлагает объяснить причину и запросить разрешение перед установкой. Путь репозитория на macOS должен состоять из ASCII-символов: при не-ASCII пути ESP-IDF может завершить сборку ошибкой. Перед изменением пинов и действий нужны инструкции по безопасности оборудования; успешная сборка сама по себе не подтверждает работу на роботе.

Какие задачи решает

  • проверить среду перед сборкой прошивки
  • собрать и прошить голосовую прошивку или DuckClaw
  • найти файлы для изменения глаз, действий и походки
  • настроить инструменты и промпты DuckClaw
  • разобраться с безопасными первыми изменениями робота

Примеры запросов агенту

  • Проверь среду и помоги собрать прошивку в firmware/voice.
  • Добавь действие DuckClaw и собери прошивку из firmware/duckclaw.
  • Помоги изменить цвет глаз Flashduck и проверь нужные файлы.

Как установить flashduck-dev

1Через Skills CLI (Vercel)

npx skills add FlashCat-Jordan/Flashduck --skill flashduck-dev -a claude-code

2Вручную: положить файлы

~/.claude/skills/flashduck-dev/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/flashduck-dev/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о flashduck-dev

Как установить flashduck-dev в Claude Code?

Выполни npx skills add FlashCat-Jordan/Flashduck --skill flashduck-dev -a claude-code. Файл скилла появится по пути ~/.claude/skills/flashduck-dev/SKILL.md.

Что делает flashduck-dev?

Скилл помогает проверять среду, собирать и прошивать проекты Flashduck, а также менять прошивки, действия робота и настройки DuckClaw.

Что нужно для работы flashduck-dev?

Для проверки среды и сборки нужны Python 3, Git, CMake, Ninja, ESP-IDF версии 6.0.1 или выше и esptool. Для проверки последовательных портов устройство должно быть подключено.

Исходный текст

SKILL.md · MIT
---
name: flashduck-dev
description: Use when helping someone build, flash, modify, or extend a Flashduck robot — the voice firmware in firmware/voice, the DuckClaw on-device agent in firmware/duckclaw, or the shared six-servo hardware. Covers environment checks/install, compile/flash, eyes, actions, gait, web tuning, MCP tools, DuckClaw tools/prompts, and beginner-friendly secondary development.
---

# Flashduck Development Skill

Use this skill when the user wants to **build, flash, modify, debug, or teach someone about Flashduck**.

The repository has three layers. Do not mix them:

| Layer | Path | What it owns |
|---|---|---|
| Product | `README.md` | What Flashduck is, how to play, how to choose a system |
| Firmware | `firmware/voice/`, `firmware/duckclaw/` | Two independent ESP-IDF projects |
| Secondary development | `skills/flashduck-dev/` | This skill: environment, recipes, checks |

Read `docs/architecture.md` for the full project/code map and `docs/coding-agent.md` for the agent workflow.

---

## 0. Always check the environment first

Run:

```bash
bash skills/flashduck-dev/scripts/check-env.sh
```

It checks:

- macOS/Linux, Python 3, Git, CMake, Ninja;
- ESP-IDF presence and version (need **6.0.1+**);
- `esptool`;
- whether the repository path is ASCII (required by this project on macOS);
- serial ports, if present.

Then:

- If everything is **OK**, continue.
- If something is **MISSING**, read `references/environment.md`, explain what is missing, and ask before installing. After approval run:

```bash
bash skills/flashduck-dev/scripts/setup-env.sh --yes
```

- If ESP-IDF is installed but not active, source it:

```bash
source "$IDF_PATH/export.sh"
# or the path printed by setup-env.sh
```

Do not install ESP-IDF inside the repository. Do not claim the environment is ready until `check-env.sh` passes.

### Non-ASCII paths

This repository may live under a path containing Chinese characters. ESP-IDF 6.0.1 can fail with:

```text
cannot read spec file '.../picolibc.specs'
```

If `check-env.sh` reports a non-ASCII path, build from an ASCII path, for example:

```bash
cp -R /path/to/Flashduck/firmware/voice ~/flashduck-voice-build
cd ~/flashduck-voice-build
```

For DuckClaw, copy `firmware/duckclaw` to an ASCII path. Do not rename the user's repository without asking.

`build-voice.sh` and `build-duckclaw.sh` do this automatically with `prepare-ascii-build.sh`; their output paths are printed.

---

## 1. Decide which firmware the user needs

Ask one short question if it is not clear:

| User wants | Firmware | Start here |
|---|---|---|
| Voice chat, wake word, eye expressions, gait tuning, MCP tools | `firmware/voice` | `references/voice-firmware.md` |
| DingTalk, local memory, emotions, relationship growth, AI poses | `firmware/duckclaw` | `references/duckclaw.md` |
| Both | Explain they are mutually exclusive | `docs/architecture.md` |
| Only hardware / shell / wiring | No firmware change | `references/hardware.md` |

**They cannot run at the same time.** Flashing one replaces the other.

---

## 2. Hardware safety rules

Read `references/hardware.md` before changing pins or actions.

- Mouth servo: **45–60° only**. Never command more than 60°.
- Neck servo: **45–180°**, 135° is forward.
- Legs/feet: 90° neutral; keep normal poses near 75–105°.
- Do not change GPIOs unless the user confirms their board revision.
- Power off before unplugging servos. Do not back-drive a powered servo.
- A successful build is not hardware validation. State what still needs a real robot.

---

## 3. Work at the smallest correct layer

### Voice firmware

Repository root for commands: `firmware/voice`.

| Task | Owning files |
|---|---|
| Eye color/shape/state | `main/boards/flashduck/flashduck_display.cc/.h` |
| Predefined actions | `main/boards/flashduck/flashduck_controller.cc/.h` |
| Motion primitives | `main/boards/flashduck/flashduck_movements.cc/.h` |
| Web gait page | `main/boards/flashduck/flashduck_web_server.cc` |
| Camera/MCP tools | `main/mcp_server.cc`, board `GetCamera()` |
| Board pins | `main/boards/flashduck/config.h` |
| Build entry | `scripts/build.py` |

Build:

```bash
cd firmware/voice
python3 scripts/build.py flashduck --name flashduck --language zh-CN \
  --wake-word wn9_xiaoyaxiaoya_tts2
```

Full image: `build/merged-binary.bin` at `0x0`.

### DuckClaw

Repository root for commands: `firmware/duckclaw`.

| Task | Owning files |
|---|---|
| Predefined duck actions | `main/tools/tool_otto.c` |
| Motion/pose primitives | `main/otto/otto_movements.c/.h` |
| Board pins | `main/board/board_config.h` |
| Agent prompt/tools | `spiffs_data/config/AGENTS.md`, `TOOLS.md`, `SOUL.md` |
| DingTalk/on-device agent | `main/dingtalk/`, `main/agent/` |
| LCD UI | `main/lcd/lcd_display.c` |

Build:

```bash
cd firmware/duckclaw
idf.py set-target esp32s3
idf.py build
idf.py merge-bin
```

Full image: `build/merged-binary.bin` at `0x0`.

DuckClaw is **CC BY-NC-SA 4.0**; do not copy it into the MIT voice firmware without checking the license.

---

## 4. Beginner mode

When the user says they are new:

1. Explain the two firmware choices in one short paragraph.
2. Check the environment before asking them to install anything.
3. Give one command at a time, with the expected result.
4. After flashing, explain:
   - how to find the serial port;
   - what success looks like in the log;
   - how to open the config page / web gait page.
5. For a first change, prefer a safe, visible recipe:
   - change an eye color;
   - add a new duck action;
   - change a gait default;
   - change a DuckClaw prompt response.
6. Never start with pin changes, servo trimming, or partition changes.

Use `references/recipes.md` for step-by-step recipes.

---

## 5. Verification and reporting

Before saying “done”:

- run the relevant build;
- run host tests when the voice project changes:

```bash
cd firmware/voice
python3 -m unittest discover -s scripts/tests -v
```

- check the generated image exists;
- report:
  - what changed;
  - what was built/tested;
  - what still needs real hardware;
  - any license or partition caveat.

Do not say “works on hardware” from a successful compile.

---

## References

- `references/environment.md` — install/check ESP-IDF, Python, CMake, Ninja, esptool, serial ports, non-ASCII path.
- `references/hardware.md` — pins, servos, display, camera, audio, power, limits.
- `references/voice-firmware.md` — voice code map, eye/action/gait/MCP/camera recipes.
- `references/duckclaw.md` — DuckClaw code map, actions, prompts, config, license.
- `references/recipes.md` — task-oriented beginner recipes.
- `docs/architecture.md` — project and code logic.
- `docs/coding-agent.md` — decision tree, guardrails, hand-off format.

© FlashCat-Jordan · MIT · FlashCat-Jordan/Flashduck

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
esp32-firmware-engineer adamlipecz Скилл esp32-firmware-engineer помогает писать, проверять и отлаживать прошивки ESP32 на ESP-IDF. При работе с железом сначала выясняет плату, вариант чипа и подключённые устройства. CX Codex +1 1 500установок esp32p4-jc-m3-dev alexex1993 Скилл esp32p4-jc-m3-dev для Claude Code помогает разрабатывать прошивки для платы Guition JC-ESP32P4-M3-DEV. Разбирает настройку проекта, периферию и причины ошибок при запуске. CX Codex +1 ★ 29звёзд репо esp32-wroom-30pin alexex1993 Скилл esp32-wroom-30pin для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode. Помогает писать прошивки для 30-пиновой платы ESP32-WROOM-32: разбирает распиновку, подводные камни пинов и конфиги PlatformIO. CX Codex +1 ★ 29звёзд репо ota-deployment-guardian wedsamuel1230 Скилл ota-deployment-guardian защищает удалённые платы ESP32 и Arduino Uno R4 WiFi от окирпичивания при OTA-обновлениях. Помогает настроить откат прошивки и разобрать сбои сетевых портов. CX Codex +1 115установок ESP32 Simulator stramanu MCP-сервер ESP32 Simulator для Claude Code запускает прошивки ESP32 в локальном эмуляторе без реальной платы. Инструмент перехватывает вывод UART, эмулирует ввод и проверяет логи на паники. CX Codex +1 ★ 8звёзд репо esp32-ai-agent-skill ezrover Плагин esp32-ai-agent-skill для Claude, который подбирает чип ESP32, проверяет назначение GPIO и генерирует код под Arduino и ESP-IDF. ★ 59звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой