embedded-framework

name	embedded-framework
description	Universal Embedded Knowledge Framework for Ankh Agent - recognizes embedded frameworks, maps domains, and applies native-first patterns
trigger	**/*.c, **/*.h, **/*.cpp, **/*.ino, **/*.py, **/*.md
version	1.0.0

Universal Embedded Knowledge Framework

Purpose

This skill enables Ankh to analyze, understand, and contribute to embedded projects by:

• Recognizing running domains
• Applying native framework patterns
• Respecting communication boundaries

When to Load

Load this skill when:

• Working on embedded projects (microcontrollers, RTOS, Linux embedded)
• Project contains: CMakeLists.txt, Kconfig, Makefile, FreeRTOS, NuttX, Zephyr, ESP-IDF, PX4, ROS/ROS2
• User asks about: embedded development, driver development, motor control, robotics, IoT, firmware

Three Core Principles

1. Domain-First Recognition

Before any code generation, you MUST:

1. Scan the project — Identify build files, source structure
2. Detect framework — Check for PX4, FreeRTOS, NuttX, RT-Thread, Zephyr, ESP-IDF
3. Map running domains — List all domains (Linux, RTOS, bare metal, etc.)

Output a domain map before writing any code:

## Running Domains Identified

1. **[Domain Name]**
   - Location: path/
   - Stack: technology
   - Responsibility: what it does

2. **[Another Domain]**
   - Location: path/
   - Stack: technology

2. Native-First Pattern Application

Native Framework API > Framework Adapter > Custom Abstraction

Framework	Use	Don't Use
PX4	uORB, module, parameter	FreeRTOS APIs
openvela	openvela framework, NuttX/POSIX	FreeRTOS xTaskCreate
FreeRTOS	xTaskCreate, xQueueSend	pthread, POSIX
Zephyr	device tree, Kconfig, device model	hardcoded GPIO
ESP-IDF	ESP-IDF components, FreeRTOS	vanilla FreeRTOS
RT-Thread	rt_device, rt_thread	FreeRTOS patterns
NuttX	POSIX, VFS, nxsem	FreeRTOS patterns
Bare metal	ISR, state machine, HAL	RTOS APIs

3. Clear Communication Boundaries

Cross-domain communication MUST use explicit protocols:

Transport	Protocol Format
UART	[HEADER, LEN, CMD, DATA, CRC]
CAN	[ID, DLC, DATA, CRC]
Ethernet	TCP/UDP with length prefix or protobuf

Framework Recognition

Detection Commands

# Detect project type
ls CMakeLists.txt Kconfig Makefile west.yml sdkconfig 2>/dev/null

# Check for specific frameworks
grep -r "xTaskCreate\|FreeRTOSConfig.h" . --include="*.c"     # FreeRTOS
grep -r "uORB\|px4_add_module" . --include="*.cpp"             # PX4
grep -r "rt_thread\|rt_mq_" . --include="*.c"                 # RT-Thread
grep -r "k_thread_\|DT_\|#include <zephyr" . --include="*.c"  # Zephyr
grep -r "esp_\|sdkconfig" . --include="*.c" --include="*.h"   # ESP-IDF

Framework Detection Table

Indicator	Framework
uORB/, msg/, px4_add_module	PX4
apps/, frameworks/, Kconfig	openvela / NuttX
xTaskCreate, FreeRTOSConfig.h	FreeRTOS
rt_device, SConscript	RT-Thread
dts/, west.yml, Kconfig	Zephyr
sdkconfig, main/	ESP-IDF

Framework Recognition and Routing

Based on detected framework, route to appropriate knowledge:

Framework	Primary Skill	Secondary Skill
PX4	domains/px4/README.md	vendor_sdks/px4.md
Motor control	domains/motor_control/README.md	—
Robotics	domains/robotics/README.md	—
STM32	vendor_sdks/stm32cube.md	—
ESP32	vendor_sdks/esp_idf.md	—
Zephyr	domains/zephyr/README.md	vendor_sdks/zephyr.md
NuttX/openvela	domains/nuttx/README.md	—

Code Generation Checklist

Before outputting code, verify:

• Uses detected framework's native API
• Does NOT mix with other framework patterns
• Respects domain boundaries
• Follows existing code conventions
• Includes proper error handling
• ISR code is non-blocking
• No hardcoded credentials or keys

Critical Constraints

1. Never mix domain APIs — Linux uses POSIX, FreeRTOS uses task/queue
2. Never bypass framework conventions — PX4 uses uORB, Zephyr uses device tree
3. Never put business logic in drivers — Drivers handle hardware only
4. Never block in ISR — ISRs are short and fast
5. Always define communication protocols — Between domains, use explicit framing
6. Never generate code without first understanding project structure
7. Always use framework's native build system — west/make/cmake/scons

Project Analysis Output Format

When scanning a project, output:

# Project Analysis Report

## Project Type
[Multi-domain embedded / Single-domain / Linux-based / etc.]

## Framework Detected
[Primary framework with version if identifiable]

## Build System
[west / make / cmake / scons / etc.]

## Running Domains
### Domain 1: [Name]
- **Location:** path/
- **Stack:** technology stack
- **Responsibility:** what this domain does

### Domain 2: [Name]
- **Location:** path/
- **Stack:** technology stack
- **Responsibility:** what this domain does

## Communication Boundaries
| Boundary | Type | Protocol |
|----------|------|----------|
| Linux ↔ MCU | UART | Custom binary protocol |

## Code Generation Recommendations
1. [Recommendation 1]
2. [Recommendation 2]

Environment Variables

EMBEDDED_SKILLPACK_DIR=/home/ubuntu/embedded-agent-skillpack

Activation Context

Load this skill when:

• Working on MCU/embedded projects (*.c, *.h, *.cpp, *.ino)
• Analyzing project structure for framework identification
• Writing embedded firmware or drivers
• Debugging embedded systems issues
• User asks about embedded development topics