Skip to content
Skills Library
Documents & office · Writing

embedded-documentation

/embedded-documentation

Use when creating or reviewing embedded firmware projects (STM32, FreeRTOS, drone, robotics) to ensure complete, consistent, and maintainable documentation. Automatically generates and validates project documentation: README, architecture docs, module design docs, interface specs, RTOS task design, ISR documentation, state machines, hardware pin mapping, and data flow diagrams. Triggers on new projects, new modules, new RTOS tasks/ISRs, state machine detection, or any undocumented component.

Licence
MIT
Last repository change
24.05.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.05.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when creating or reviewing embedded firmware projects (STM32, FreeRTOS, drone, robotics) to ensure complete, consistent, and maintainable documentation. Automatically generates and validates project documentation: README, architecture docs, module design docs, interface specs, RTOS task design, ISR documentation, state machines, hardware pin mapping, and data flow diagrams. Triggers on new projects, new modules, new RTOS tasks/ISRs, state machine detection, or any undocumented component.

Original author description

Use when creating or reviewing embedded firmware projects (STM32, FreeRTOS, drone, robotics) to ensure complete, consistent, and maintainable documentation. Automatically generates and validates project documentation: README, architecture docs, module design docs, interface specs, RTOS task design, ISR documentation, state machines, hardware pin mapping, and data flow diagrams. Triggers on new projects, new modules, new RTOS tasks/ISRs, state machine detection, or any undocumented component.

How it works

  1. Purpose
  2. Documentation Level Overview
  3. Project-Level Documentation (L1)
  4. Module-Level Documentation (L2)
  5. Interface Documentation (L3)
  6. RTOS Task Documentation (L4)
  7. ISR Documentation (L4)
  8. State Machine Documentation (L5)
  9. Diagram Generation Rules
  10. Documentation Validation Checklist
Original SKILL.md headings · 341 lines, 1,171 words
SKILL.md preview
---
name: embedded-documentation
description: >
  Use when creating or reviewing embedded firmware projects (STM32, FreeRTOS, drone, robotics) to
  ensure complete, consistent, and maintainable documentation. Automatically generates and validates
  project documentation: README, architecture docs, module design docs, interface specs, RTOS task
  design, ISR documentation, state machines, hardware pin mapping, and data flow diagrams.
  Triggers on new projects, new modules, new RTOS tasks/ISRs, state machine detection, or any
  undocumented component.
---

# Embedded Documentation

## Purpose

This skill defines documentation standards for embedded firmware projects. The goal is to ensure
every generated project is accompanied by documentation sufficient for another engineer to
understand, build, modify, and maintain the system.

Goals:

- maintainability
- traceability
- onboarding efficiency
- architecture visibility
- design consistency

The most valuable embedded documentation is not Doxygen API comments — it is architecture overviews,
RTOS task design, and hardware resource mapping that let a new engineer understand the whole
system in minutes.

Documentation must evolve together with code. Never leave public modules undocumented.

## Documentation Level Overview

| Level | Content | When Generated |
|-------|---------|----------------|
| L1 — Project | README, Architecture, Build, Hardware, Directory Structure | New project |
| L2 — Module | Per-module design docs | New module created |
| L3 — Interface | Interface contract docs | New interface created |
| L4 — RTOS/ISR | TaskDesign, ISRDesign, EventFlow | `osThreadNew` or `IRQHandler` detected |
| L5 — Control | ControlLoop, StateMachine, Estimator | State machine enum or control structures detected |

## Project-Level Documentation (L1)

When creating a new embedded project, generate:

```text
README.md

docs/
├── Architecture.md
├── Build.md
├── Hardware.md
└── DirectoryStructure.md
```

### README Requirements

Every project README must contain:

```markdown
# Project Overview

What this firmware does and which hardware it targets.

# Features

Key capabilities and supported peripherals.

# Hardware Platform

MCU family, board revision, key pin assignments.

# Build Instructions

Toolchain, build commands, optional features.

# Flash Instructions

Debugger, probe, or bootloader method.

# Project Structure

Overview of the directory layout.

# Software Architecture

Layer diagram and dependency direction.

# Dependencies

Middleware, SDKs, toolchains required.

# License
```

### Architecture Documentation

Must describe the layer model — a ASCII dependency diagram:

```text
app/
 ↓
module/
 ↓
interface/
 ↓
bsp/
 ↓
platform/
```

Explain the role of each layer and the dependency direction constraint.

### Directory Structure Documentation

Auto-generate from the actual project tree:

```text
project/
├── app/              — Application entry, tasks, state machines
├── module/           — Business logic modules
├── interface/        — Hardware abstraction contracts
├── bsp/              — Board-specific driver implementations
├── platform/         — Vendor SDK, HAL, CMSIS, linker scripts
├── middleware/       — Third-party (FreeRTOS, lwIP, FatFS)
├── docs/             — Documentation
├── tools/            — Build and debug scripts
└── tests/            — Unit and integration tests
```

### Hardware Documentation

When the project references GPIO, UART, SPI, I2C, CAN, PWM, or ADC, generate `docs/Hardware.md`
with a resource table:

```markdown
| Peripheral | Interface | Target       | Purpose          |
|------------|-----------|--------------|------------------|
| USART1     | uart_if   | Telemetry    | 115200 baud      |
| SPI1       | spi_if    | ICM-42688    | IMU data @ 1MHz  |
| TIM3       | pwm_if    | Motor driver | 50Hz PWM         |
| ADC1       |           | Battery      | Voltage monitor  |
| PB0        | gpio_if   | LED          | Status indicator |
```

## Module-Level Documentation (L2)

When a new module is created (e.g., `module/motor/`), generate `docs/modules/motor.md`:

```markdown
# Motor Module

## Purpose

Control motor output — converts speed commands into PWM signals and monitors fault status.

## Responsibilities

- speed control loop execution
- PWM generation via pwm_if
- fault detection and safe stop
- current limiting

## Public API

error_t motor_init(void)
error_t motor_set_speed(int32_t rpm)
void    motor_stop(void)
bool    motor_is_faulted(void)

## Dependencies

- pwm_if
- timer_if
- gpio_if

## Data Flow

control_module → motor_module → pwm_if → platform_pwm

## State Machine

STOPPED → STARTING → RUNNING → FAULT → STOPPED
```

## Interface Documentation (L3)

Every interface in `interface/` must document:

```markdown
# UART Interface

## Purpose

Provide hardware-independent UART access for modules.

## Public API

int32_t uart_init(uart_config_t *cfg)
int32_t uart_write(const uint8_t *data, uint32_t len)
int32_t uart_read(uint8_t *data, uint32_t len)

## Ownership

Implemented by BSP layer. Consumed by module/ layer.

## Thread Safety

Not thread-safe. Caller must protect with mutex or critical section.
```

## RTOS Task Documentation (L4)

When the code contains `osThreadNew()` or `xTaskCreate()`, generate `docs/TaskDesign.md`:

```markdown
# Task Design

| Task            | Period | Priority | Stack  | Responsibility          |
|-----------------|--------|----------|--------|-------------------------|
| imu_task        | 1 ms   | High     | 512    | Sensor acquisition      |
| control_task    | 1 ms   | High     | 1024   | PID control loop        |
| telemetry_task  | 20 ms  | Low      | 256    | UART telemetry output   |
| usb_cdc_task    | event  | Medium   | 512    | USB serial handling     |
```

Also document synchronization primitives:

```markdown
### Synchronization

| Resource         | Type         | Purpose                  |
|------------------|--------------|--------------------------|
| imu_data_queue   | MessageQueue | IMU → Control            |
| control_mutex    | Mutex        | Shared setpoint access   |
| telemetry_event  | EventFlags   | Telemetry trigger        |
```

## ISR Documentation (L4)

When the code contains `IRQHandler` functions, generate `docs/ISRDesign.md`:

```markdown
# ISR Design

| Interrupt      | Source   | Priority | Execution Time | Shared Variables        |
|----------------|----------|----------|----------------|-------------------------|
| USART1_IRQn    | RX       | 5        | < 5 µs         | rx_buffer, rx_index     |
| TIM3_IRQn      | Update   | 4        | < 2 µs         | pwm_duty                |

### Deferred Processing

| ISR            | Deferred Mechanism     | Consumer      |
|----------------|------------------------|---------------|
| USART1_IRQn    | osMessageQueuePut      | usb_cdc_task  |
| TIM3_IRQn      | Direct (in-isr update) | —             |
```

## State Machine Documentation (L5)

When the code contains a state enum or `switch(state)`, generate `docs/StateMachine.md`:

```text
INIT
 ↓
IDLE
 ↓
RUNNING
 ↓
FAULT → IDLE
```

Include transition conditions:

```markdown
| Transition | From     | To       | Condition               |
|------------|----------|----------|-------------------------|
| start      | IDLE     | RUNNING  | system_ready == true    |
| fault      | RUNNING  | FAULT    | motor_fault_detected    |
| reset      | FAULT    | IDLE     | fault_ack received      |
| error      | INIT     | IDLE     | init complete           |
```

## Diagram Generation Rules

When producing documentation, prefer ASCII diagrams for architecture and data flow so they
render inline in any Markdown viewer without external tools.

### Architecture Diagram

```text
app/
 ↕
module/
 ↕
interface/
 ↕
bsp/
 ↕
platform/
```

### Data Flow Diagram

```text
imu_sensor
    ↓ (SPI)
imu_module
    ↓ (queue)
estimator
    ↓ (shared data)
controller
    ↓ (pwm_if)
motor_driver
```

### Task Interaction Diagram

```text
imu_task ──queue──→ control_task ──queue──→ telemetry_task
```

## Documentation Validation Checklist

After generating code, verify:

- [ ] README exists and covers all required sections
- [ ] Architecture document describes layer model
- [ ] Build instructions are documented
- [ ] Hardware resources are documented with peripheral table
- [ ] New modules each have a design doc
- [ ] All interfaces document purpose, API, ownership, and thread safety
- [ ] RTOS tasks documented with period/priority/stack/responsibility
- [ ] ISRs documented with source, latency, shared variables, deferred processing
- [ ] State machines documented with transitions and conditions
- [ ] Dependency graph and data flow documented
- [ ] Directory structure documented

## Auto Fix Strategy

When documentation is missing:

1. **Detect** the undocumented component (module, interface, task, ISR, hardware)
2. **Generate** the required document following the templates above
3. **Link** the new document from the README table of contents
4. **Update** architecture references to maintain document graph coherence

Documentation should evolve together with code. Never leave public modules undocumented.

Versions

The database has no other skills named embedded-documentation.

Database snapshot: 13.11.2026 · package version bf5fb4d28cbf (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100embedded-firmware-dev
    Use when writing or reviewing embedded C firmware, FreeRTOS tasks, ISR handlers, NVM/flash storage, or sensor driver state machines. NOT for documentation-only RTOS references, conceptual RTOS discussions, or bare-metal projects without an RTOS or sensor subsystem.
  • 100embedded-rtos-design
    Use when designing, generating, or reviewing RTOS-based embedded firmware (FreeRTOS, CMSIS-RTOS2, RT-Thread, Zephyr, ThreadX) for STM32, GD32, ESP32, drone flight controllers, and robotics projects. Enforces real-time system architecture — task decomposition, scheduling,…
  • 100embedded-isr-design
    Use when generating or reviewing interrupt service routines (ISRs) for embedded firmware (STM32, GD32, ESP32, FreeRTOS, bare-metal, drone flight controllers, robotics). Enforces the "Fast In, Fast Out" principle — ISRs capture events and defer processing to task context.…
  • 90rtos-task-design
    Decompose firmware into RTOS tasks with deadline-derived priorities, queue-based communication, and priority-inversion defenses. Use when structuring FreeRTOS/Zephyr-class applications or debugging missed deadlines.
  • 85write-the-docs
    Write or edit project documentation. Use when writing a README, design doc, or module doc.
  • 100volt-firmware
    Produce a complete firmware architecture spec for a described device — layer diagram, module responsibilities, HAL interface definitions, key state machines, RTOS decision. Use when asked to "design firmware architecture", "plan embedded firmware", "architect an IoT device",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.