# embedded-agent-skillpac

**Repository Path**: wang-zhulin/embedded-agent-skillpac

## Basic Information

- **Project Name**: embedded-agent-skillpac
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Embedded Agent SkillPack

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Project Type: Knowledge Framework](https://img.shields.io/badge/Type-Knowledge%20Framework-blue)](https://github.com/embedded-agent/skillpack)
[![Embedded Frameworks: 8+](https://img.shields.io/badge/Frameworks-8%2B-green)](https://github.com/embedded-agent/skillpack)
[![Domain Coverage: 10+](https://img.shields.io/badge/Domains-10%2B-orange)](https://github.com/embedded-agent/skillpack)

**Universal knowledge framework for embedded AI agents.** The SkillPack provides structured, domain-aware guidance that enables AI coding assistants (Claude Code, Codex, opencode) to correctly understand and contribute to embedded systems projects—spanning bare-metal microcontrollers, RTOS kernels, Linux-based embedded systems, and robotics middleware.

---

## Problem

AI agents fail in embedded development because they lack domain awareness. They mix FreeRTOS APIs with POSIX threads, write Linux GPIO code for bare-metal MCUs, or bypass critical framework conventions like PX4's uORB or Zephyr's device tree. The consequences range from build failures to safety-critical runtime bugs.

**The SkillPack solves this by teaching agents the rules of each embedded domain before they touch a line of code.**

---

## Three Core Principles

### 1. Domain-First

Every embedded system contains multiple **Running Domains** that must be identified before writing any code. Mixing domain APIs in the same code module is the primary cause of embedded project failures.

```
┌─────────────────────────────────────────────────────┐
│  Linux / ROS2 Domain                                 │
│  Sensor fusion, navigation, web dashboard           │
├─────────────────────────────────────────────────────┤
│  Communication Boundary (UART / CAN / Ethernet)     │
├─────────────────────────────────────────────────────┤
│  MCU / RTOS Domain                                  │
│  Motor control, encoder, current sampling          │
├─────────────────────────────────────────────────────┤
│  Bootloader Domain                                  │
│  Flash, secure boot, OTA                           │
└─────────────────────────────────────────────────────┘
```

### 2. Native-First

Use each framework's native APIs and idioms. Do not force a unified OSAL abstraction across different ecosystems.

| Framework | Use These APIs |
|-----------|----------------|
| **PX4** | `uORB`, module framework, `px4_add_module` |
| **FreeRTOS** | `xTaskCreate`, `xQueueSend`, `xSemaphoreTake` |
| **NuttX / openvela** | POSIX, VFS, `nxsem_*`, `task_create` |
| **Zephyr** | Device tree, Kconfig, `DEVICE_DEFINE`, `DT_PROP` |
| **ESP-IDF** | `esp_timer`, `esp_event_loop`, `esp_wifi_*` |
| **RT-Thread** | `rt_device`, `rt_thread`, `rt_mq_*` |
| **ROS2** | `rclcpp::Node`, `create_publisher<T>()`, `create_subscription<T>()` |
| **Bare Metal** | State machine, ISR, HAL, direct register access |

### 3. Clear Communication Boundaries

Define explicit protocols between domains. Do not make cross-domain API calls. Use serialization (protobuf, MAVLink, custom frames) at boundary crossings.

---

## Quick Start

### Claude Code

```
1. Load the skill adapter
   → Read adapters/claude-code/SKILL.md

2. Read core files in order:
   → core/01_domain_model.md
   → core/02_project_recognition.md
   → core/03_native_first_rules.md
   → core/05_code_generation_policy.md

3. Identify the project framework and domains

4. Generate a domain map before writing code

5. Apply framework-native patterns
```

### Codex / opencode

```
1. Load the agent adapter
   → Read adapters/codex/AGENTS.md
   → Read adapters/opencode/AGENTS.md

2. Follow the same Domain → Map → Apply workflow
```

### NPM Install (Recommended)

```bash
# Install globally — gives you the `easp` CLI
npm install -g embedded-agent-skillpack

# Verify
easp lint
easp export --target all
easp smoke
easp debug gdb script --profile stm32-hardfault

# Or run via npx (no install needed)
npx embedded-agent-skillpack lint
npx embedded-agent-skillpack export --target omx
```

For per-project install, alternative install methods, and development mode setup, see [`docs/install_npm.md`](docs/install_npm.md).

---

## Project Recognition Table

| File / Pattern | Framework Detected |
|----------------|-------------------|
| `uORB/`, `msg/`, `px4_add_module` | PX4 Flight Control |
| `apps/`, `frameworks/`, `Kconfig` | openvela / NuttX |
| `xTaskCreate`, `FreeRTOSConfig.h` | FreeRTOS |
| `rt_device`, `SConscript` | RT-Thread |
| `dts/`, `west.yml`, `#include <zephyr/` | Zephyr |
| `sdkconfig`, `main/` | ESP-IDF |
| `ros1/`, `ros2/`, `ament_` | ROS / ROS2 |
| `CMakeLists.txt`, `package.xml` | ROS2 |
| No OS, `while(1)`, ISR | Bare Metal |

---

## Supported Domains

| Domain | Stacks Covered |
|--------|----------------|
| **Flight Control** | PX4, uORB, MAVLink, mixer, sensor fusion |
| **Motor Control** | FOC, BLDC, PID, ADC, PWM, encoder |
| **Robotics** | ROS1, ROS2, topics, services, actions, lifecycle |
| **IoT** | MQTT, BLE, Wi-Fi, TLS, CoAP, LwM2M |
| **Consumer Electronics** | LVGL, touch input, audio, BLE |
| **Embedded Linux** | POSIX, pthread, socket, systemd, character devices |
| **RTOS** | FreeRTOS, NuttX, RT-Thread, Zephyr, openvela |
| **Bare Metal** | State machines, ISR, HAL, register access |
| **Bootloader** | Flash, secure boot, OTA, UART/CAN update |
| **Middleware** | lwIP, FatFS, USB stack, BLE stack, LVGL |

---

## Directory Structure

```
embedded-agent-skillpack/
├── core/                           # Must-read: framework rules
│   ├── 01_domain_model.md          # Running domains concept
│   ├── 02_project_recognition.md   # How to identify project type
│   ├── 03_native_first_rules.md    # Native API priority per framework
│   ├── 04_communication_boundary.md # Cross-domain protocol design
│   └── 05_code_generation_policy.md # Code generation checklist
│
├── domains/                        # Domain-specific knowledge
│   ├── px4/                        # PX4 flight control
│   ├── robotics/                   # ROS1, ROS2, telemetry
│   ├── motor_control/              # FOC, BLDC, PID
│   ├── rtos/                       # FreeRTOS, NuttX, RT-Thread, Zephyr
│   ├── linux/                      # Embedded Linux, POSIX
│   ├── iot/                        # MQTT, BLE, Wi-Fi
│   ├── consumer_electronics/       # Smartwatch, LVGL
│   ├── bootloader/                 # Flash, OTA, secure boot
│   ├── baremetal/                  # Patterns for no-OS projects
│   └── platform_framework/         # openvela
│
├── vendor_sdks/                    # Chip vendor SDKs
│   ├── stm32cube.md                # STM32 HAL/LL
│   ├── esp_idf.md                  # ESP-IDF components
│   ├── sifli_sdk.md                # SiFlight SDK
│   └── sifli_solutions.md          # SiFlight solutions
│
├── middleware/                     # Common middleware
│   ├── lvgl.md                     # LVGL UI framework
│   ├── lwip.md                     # lwIP TCP/IP stack
│   ├── fatfs.md                    # FatFS file system
│   ├── usb_stack.md                # USB device/host stack
│   └── ble_stack.md                # BLE middleware
│
├── communication/                  # Protocol definitions
│   ├── uart_protocol.md            # UART framing, state machine
│   ├── can_protocol.md             # CAN 2.0, CANopen
│   ├── mavlink.md                  # MAVLink v1/v2
│   ├── mqtt.md                     # MQTT pub/sub
│   ├── websocket.md                # WebSocket framing
│   ├── usb_cdc.md                  # USB CDC-ACM
│   └── rpmsg.md                    # RPMsg (A-core ↔ M-core)
│
├── patterns/                       # Architecture patterns
│   ├── state_machine.md            # FSM implementation
│   ├── publisher_subscriber.md     # Pub/sub patterns
│   ├── singleton.md                # Singleton in embedded C
│   ├── factory.md                  # Factory pattern
│   └── observer.md                # Observer/event driven
│
├── adapters/                       # AI tool configurations (11 runtimes)
│   ├── omo/                        # Oh My OpenAgent — multi-agent orchestration
│   ├── omx/                        # Oh My Codex — knowledge distillation
│   ├── omc/                        # Oh My Claude Code — SKILL.md format
│   ├── native-codex/               # Native Codex CLI — AGENTS.md
│   ├── native-opencode/            # Native OpenCode — AGENTS.md + agents/
│   ├── native-claude-code/         # Native Claude Code — SKILL.md
│   ├── cursor/                     # Cursor IDE — .cursorrules
│   ├── openclaw/                   # OpenClaw — AI coding agent
│   ├── hermes/                     # Hermes — agent runtime
│   ├── ankh/                       # Ankh — modern agent runtime
│   └── generic/                    # Generic — framework-agnostic
│
├── prompts/                        # Task prompt templates
├── examples/                       # Example implementations
│
├── CLAUDE.md                       # Entry point for Claude
└── README.md                       # This file
```

---

## Architecture Overview

The SkillPack operates on a **layered domain model**:

```
┌─────────────────────────────────────────────────────────┐
│                   AI Agent (Claude/Codex)                │
├─────────────────────────────────────────────────────────┤
│  Adapter Layer (claude-code/, codex/, opencode/)        │
│  → Tool-specific loading instructions                   │
├─────────────────────────────────────────────────────────┤
│  Core Rules (core/)                                     │
│  → Domain model, recognition, native-first, boundaries  │
├─────────────────────────────────────────────────────────┤
│  Domain Skills (domains/)                               │
│  → PX4, motor control, robotics, RTOS, Linux, IoT...    │
├─────────────────────────────────────────────────────────┤
│  Technical Skills (vendor_sdks/, middleware/, comms/)  │
│  → Chip SDKs, middleware, protocol specs                │
├─────────────────────────────────────────────────────────┤
│  Patterns (patterns/)                                   │
│  → State machine, pub/sub, factory, observer           │
└─────────────────────────────────────────────────────────┘
```

**Workflow for any embedded task:**

1. **Recognize** → Identify framework type via build files and include patterns
2. **Map** → Generate domain map (location, stack, responsibility per domain)
3. **Apply** → Use framework-native patterns from the appropriate domain folder

---

## Critical Rules

> **Never mix APIs from different domains in the same code file.**

| Rule | Why |
|------|-----|
| Don't use `pthread_create` in FreeRTOS code | Different threading models |
| Don't use `xQueueSend` in Linux code | FreeRTOS queues are not portable |
| Don't use `HAL_GPIO_WritePin` in Linux apps | Linux uses sysfs or character devices |
| Don't use `ros::NodeHandle` in ISR | ROS requires a running node graph |
| Don't put business logic in drivers | Drivers handle hardware, not policy |
| Don't block in ISR context | ISRs must be short and non-blocking |
| Don't bypass framework conventions | uORB, device tree, Kconfig exist for reasons |

---

## Case Studies

Real-world SkillPack validation through completed embedded projects.

### Case Study 1: STM32 UART DMA ReceiveToIdle
📄 [`case_studies/01_stm32_uart_dma_receive_to_idle.md`](case_studies/01_stm32_uart_dma_receive_to_idle.md) — 566 lines

**Task:** Verify whether the ingestion pipeline's STM32 UART DMA knowledge patch can actually guide code generation and review.

**Coverage:** `vendor_sdks/stm32cube.md`, `communication/uart_protocol.md`, `runtime/domain_route_table.yaml`, EVAL T26/T27

**Key outcome:** Dogfooding ingestion pipeline (v0.4c) — 9 claims extracted, patch generated, patch_lint 8/8 passed, merge gate PASSED. Demonstrates the full IMPORTED → EXTRACTED → CLASSIFIED → CLAIMS_EXTRACTED → PATCH_PROPOSED → PATCH_LINTED → HUMAN_REVIEW_REQUIRED → HUMAN_REVIEWED → MERGED → EVAL_UPDATED pipeline.

---

### Case Study 2: STM32 FreeRTOS Software Timer Library
📄 [`case_studies/02_stm32_freertos_software_timer.md`](case_studies/02_stm32_freertos_software_timer.md) — 835 lines

**Task:** Design a portable software timer library supporting multiple timers, parameterized callbacks, CubeMX adaptation, and optional C++ wrapper.

**Coverage:** `domains/rtos/freertos.md`, `vendor_sdks/stm32cube.md`, `patterns/driver_model.md`, `checklists/ai_agent_output_review.md`, `runtime/domain_route_table.yaml` (route: `stm32_freertos_driver`)

**Key outcome:** Demonstrates Domain-First (RTOS domain), Native-First (FreeRTOS timer APIs), and CubeMX regeneration survival pattern.

---

### Case Study 3: ROS2 + MCU Robot Communication Gateway
📄 [`case_studies/03_ros2_mcu_robot_gateway.md`](case_studies/03_ros2_mcu_robot_gateway.md) — 1022 lines

**Task:** Design a dual-domain communication scheme bridging Linux/ROS2 on Raspberry Pi 4 with STM32/FreeRTOS motor controller via UART, extended with WebSocket telemetry dashboard.

**Coverage:** `domains/robotics/ros2_rules.md`, `domains/robotics/linux_mcu_robot.md`, `communication/uart_protocol.md`, `communication/websocket.md`, `checklists/ai_agent_output_review.md`, `runtime/domain_route_table.yaml` (route: `ros2_mcu_robot`)

**Key outcome:** Proves all three core principles in one project — Domain-First (3 distinct domains identified), Native-First (ROS2 C++ / FreeRTOS C / Linux POSIX each using native APIs), Clear Communication Boundaries (explicit UART frame protocol with SOF/CRC).

---

## Case Study 4: CmBacktrace HardFault Debug
📄 [`case_studies/04_cmbacktrace_hardfault_debug.md`](case_studies/04_cmbacktrace_hardfault_debug.md) — Embedded debugging闭环

**Task:** Analyze a STM32F407 HardFault crash log using CmBacktrace, perform symbolication with addr2line, and determine root cause.

**Coverage:** `debug/cmbacktrace_workflow.md`, `domains/debugging/hardfault.md`, `domains/debugging/cmbacktrace.md`, `runtime/domain_route_table.yaml` (route: `cmbacktrace_hardfault_analysis`)

**Key outcome:** v0.7B debug layer — CFSR decoding, stack overflow root cause, 5-step CmBacktrace workflow validated.

---

## Contributing

Contributions are welcome. This project follows the **Domain-First** principle even for its own documentation:

- **New framework support** → Add to `vendor_sdks/` and update `core/03_native_first_rules.md`
- **New domain** → Create `domains/<domain_name>/` with a `README.md` and applicable skills
- **New protocol** → Add to `communication/` with frame format and state machine
- **New pattern** → Add to `patterns/` with embedded-specific examples
- **New adapter** → Create `adapters/<tool_name>/` following existing conventions

Please read `core/01_domain_model.md` before contributing domain-specific content to ensure you follow the running domains model correctly.

---

## License

MIT License. See [LICENSE](LICENSE) for full text.

---

**The SkillPack is not a library or a framework. It is a structured knowledge base that makes embedded AI agents domain-aware.**