# baremetal-startup

baremetal-startup is a Claude Code skill that guides coding agents through Cortex-M and RISC-V initialization from reset to main().

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 394 installs · ★ 298 repo stars
- Author: mohitmishra786
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/mohitmishra786/low-level-dev-skills/tree/HEAD/skills/baremetal/baremetal-startup/SKILL.md
- Updated: 2026-06-27
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/baremetal-startup

## What it does

The skill provides step-by-step guidance for writing minimal `startup.s`, `entry.S`, and `crt0` routines. It covers vector table definitions, setting up the initial stack pointer via `_estack`, copying `.data` from flash to RAM, and zeroing the `.bss` section before calling `main()`.

It also details linker symbol integration and vector table relocation with `SCB->VTOR`. Without proper address alignment required by ARM specifications, setting `VTOR` after a bootloader jump will break interrupt handlers.

The reference addresses typical boot crashes: immediate `HardFault` from invalid stack pointers, corrupted global variables, calling C++ static constructors prior to clock configuration, and missing `while(1)` or `WFI` loops if `main()` terminates.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill baremetal-startup -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/baremetal-startup/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/baremetal-startup/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill baremetal-startup -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/baremetal-startup/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill baremetal-startup -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/baremetal-startup/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install mohitmishra786/low-level-dev-skills skills/baremetal/baremetal-startup
```

2. **Manually: put the files in place**
- File: `.github/skills/baremetal-startup/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill baremetal-startup -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/mohitmishra786/low-level-dev-skills --path skills/baremetal/baremetal-startup
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/baremetal-startup/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill baremetal-startup -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/mohitmishra786/low-level-dev-skills/tree/HEAD/skills/baremetal/baremetal-startup/SKILL.md

## When to use it
- write a minimal Cortex-M startup.s or Reset_Handler
- configure .data copying and .bss clearing before entering main()
- relocate the vector table using SCB->VTOR after a bootloader jump
- fix boot-time HardFault exceptions and stack pointer errors

## Example prompts
- /baremetal-startup My STM32 never reaches main — what should Reset_Handler do?
- /baremetal-startup How do I relocate the vector table after bootloader jump?
- /baremetal-startup Generate a minimal RISC-V assembly entry point clearing bss

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: d70358c101dd5a30.

BEGIN THIRD-PARTY FILE d70358c101dd5a30
````text
---
name: baremetal-startup
description: Bare-metal startup skill for reset-to-main bring-up. Use when writing startup code, vector tables, .data/.bss init, stack setup, or crt0 for Cortex-M/RISC-V. Activates on queries about reset vector, VTOR, startup.s, bss init, or bare-metal entry point.
---

# Bare-Metal Startup

## Purpose

Guide agents through bare-metal startup from reset to `main()`: reset and exception vectors, `.data`/`.bss` initialization, stack and heap setup, C runtime integration with linker scripts, and common Cortex-M and RISC-V bring-up bugs.

## When to Use

- Firmware hangs before reaching `main()`
- Porting to a new MCU without vendor HAL
- Writing custom `startup.s` or `Reset_Handler`
- Integrating with `skills/embedded/linker-scripts`
- Debugging uninitialized globals or stack overflows at boot

## Workflow

### 1. Boot sequence mental model

```
Power-on / reset
├── CPU loads SP from vector[0]
├── CPU branches to Reset_Handler from vector[1]
├── Reset_Handler: init clocks (optional), copy .data, zero .bss
├── Configure stack pointer (if not already from vector)
├── Call SystemInit() / platform_init()
└── Call main() — must not return (loop or WFI)
```

### 2. Cortex-M vector table

On Cortex-M, the vector table starts at address 0 or a relocatable base (VTOR):

| Index | Entry |
|-------|-------|
| 0 | Initial stack pointer (`_estack`) |
| 1 | `Reset_Handler` |
| 2 | `NMI_Handler` |
| 3 | `HardFault_Handler` |
| 4+ | IRQ handlers per NVIC |

```asm
/* startup.s — minimal Cortex-M */
.syntax unified
.thumb

.section .isr_vector,"a",%progbits
.global g_pfnVectors
g_pfnVectors:
    .word _estack
    .word Reset_Handler
    .word NMI_Handler
    .word HardFault_Handler
    /* ... device IRQ vectors from vendor CMSIS ... */

.section .text.Reset_Handler
.thumb_func
.global Reset_Handler
Reset_Handler:
    ldr r0, =_sidata    /* .data load address (LMA) */
    ldr r1, =_sdata     /* .data VMA start */
    ldr r2, =_edata
    b LoopCopyDataInit
CopyDataInit:
    ldr r3, [r0], #4
    str r3, [r1], #4
LoopCopyDataInit:
    cmp r1, r2
    blt CopyDataInit
    ldr r2, =_sbss
    ldr r4, =_ebss
    movs r3, #0
    b LoopFillZerobss
FillZerobss:
    str r3, [r2], #4
LoopFillZerobss:
    cmp r2, r4
    blt FillZerobss
    bl SystemInit
    bl main
    b .
```

```c
/* Linker symbols — declared extern in startup */
extern uint32_t _estack, _sidata, _sdata, _edata, _sbss, _ebss;
```

### 3. VTOR relocation (Cortex-M)

```c
#include "core_cm4.h"  /* CMSIS */

void relocate_vector_table(uint32_t base) {
````
END THIRD-PARTY FILE d70358c101dd5a30

The third-party file has ended. Everything between the d70358c101dd5a30 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2597 of 4950 bytes. © mohitmishra786 · MIT · https://github.com/mohitmishra786/low-level-dev-skills/tree/HEAD/skills/baremetal/baremetal-startup/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
