agentsclimarketplace

Embedded fault debug

Skill easyzoom/aix-skills/skills/embedded-fault-debug

Use when embedded firmware crashes, traps, faults, resets unexpectedly, jumps to default handlers, corrupts stack, or executes invalid instructionsFrom its SKILL.md

Install
npx -y skills add easyzoom/aix-skills --skill embedded-fault-debug

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

4.2 KB, 936 tokens by cl100k_base, as published. Nobody here has run it

Embedded Fault Debug

Overview

Use this skill to preserve crash evidence and find the first failing instruction. The agent should read architecture-specific fault state before reset, map addresses to symbols, and separate root cause from secondary symptoms.

When To Use

Use this skill when:

  • Firmware hits HardFault, BusFault, UsageFault, trap, illegal instruction, default handler, watchdog reset, assert, or panic.
  • The board resets unexpectedly or hangs after a repeatable action.
  • The user has a register dump, fault log, crash PC, stack dump, watchdog event, or GDB backtrace.

Do not use this skill when the target cannot yet connect or flash; use mcu-flashing-debug first.

First Questions

Ask for:

  • Architecture/chip family and toolchain.
  • Exact symptom and whether it is reproducible.
  • Register dump, backtrace, fault/trap registers, assert log, or reset reason.
  • ELF/MAP file that matches the running image.
  • Whether the target has been reset since the fault.

Workflow

  1. Preserve state. Do not reset or reflash until fault registers, PC, LR/RA, SP, and stack frame are captured.

  2. Confirm image-symbol match. Ensure the ELF/MAP file matches the firmware currently running on target.

  3. Identify the faulting address. Map PC, exception return address, mepc, stacked PC, or return address to a symbol and source line.

  4. Classify the cause. Separate invalid memory access, illegal instruction, stack overflow, alignment, bus/peripheral access, watchdog, assert, and default handler cases.

  5. Walk backward to the first bad state. Inspect caller, input pointers, stack bounds, interrupt context, DMA/cache interactions, and recent initialization.

  6. Add a focused verification. Use a watchpoint, assertion, guard pattern, stack watermark, or minimal repro to prove the suspected cause.

Architecture Notes

Cortex-M

Read SCB fault registers before reset:

CFSR  = 0xE000ED28
HFSR  = 0xE000ED2C
MMFAR = 0xE000ED34
BFAR  = 0xE000ED38

Decode stacked r0-r3, r12, lr, pc, and xpsr from MSP or PSP.

RISC-V

Read:

mcause, mepc, mtval, mtvec, mstatus, sp

Check whether mcause is interrupt or exception, and map mepc to source/disassembly.

8051

Use available evidence:

  • Reset reason register if the derivative provides one.
  • Stack pointer and internal RAM pressure.
  • ISR vector selection and default handler loops.
  • Watchdog configuration.
  • GPIO heartbeat or serial breadcrumbs around suspected code.

Common Root Causes

  • Stack overflow or ISR stack pressure.
  • Null/corrupt function pointer.
  • Wrong vector table, trap vector, or interrupt number.
  • Accessing peripheral before clock/reset release.
  • DMA writing outside buffers.
  • Cache coherency issue on cache-enabled MCUs.
  • Compiler target flags not matching core features.
  • Watchdog not serviced during long init.
  • Bootloader/app offset mismatch.

Verification

Before claiming a fault is understood:

  • State the matched ELF/MAP and running firmware identity if known.
  • Report faulting PC/address and mapped symbol/source.
  • Report architecture-specific fault registers or explain why unavailable.
  • State the suspected root cause and the evidence linking it to the fault.
  • State the next minimal verification step, such as watchpoint, stack watermark, or assertion.

Common Failures

  • Resetting immediately and losing the only useful fault state.
  • Trusting a backtrace when the ELF does not match flashed firmware.
  • Fixing the line where the fault occurred instead of the earlier corruption.
  • Ignoring interrupt context, stack selection, or DMA/cache side effects.
  • Treating watchdog reset as a generic crash without reading reset reason.

Example

User:

程序跑一会儿就进 HardFault。

Agent:

  1. Asks for chip, ELF, register dump, CFSR/HFSR, stacked PC, and whether reset happened.
  2. Maps stacked PC to source.
  3. Checks stack bounds, caller, interrupt context, and invalid memory access evidence.
  4. Suggests a focused watchpoint or stack watermark before changing code.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 0 of the 12 instructions most debug triage skills give in 936 tokens

Counted across 1,020 of the 1,639 authors here whose files we hold, read 2026-09-06

  • Find root cause before attempting any fixin 134 of 1020, across 118 files
  • Create a failing test case before implementing a fixin 109 of 1020, across 95 files
  • Read error messages and stack traces completelyin 102 of 1020, across 88 files
  • Reproduce the issue consistently before investigatingin 90 of 1020, across 77 files
  • Make the smallest possible change to test a hypothesisin 90 of 1020, across 76 files
  • Trace data flow backward to find the sourcein 84 of 1020, across 70 files
  • Form a single hypothesis before testingin 78 of 1020, across 64 files
  • Implement only one fix at a timein 76 of 1020, across 63 files
  • Question the architecture if three fixes failin 73 of 1020, across 59 files
  • Add diagnostic instrumentation at component boundariesin 68 of 1020, across 56 files
  • Compare broken code against working examplesin 68 of 1020, across 57 files
  • Write a regression test before applying the fixin 62 of 1020, across 55 files

Said here and by no other author read

  • Capture fault registers before resetting the target
  • Verify ELF file matches the running firmware
  • Map faulting address to source code line
  • Classify fault cause based on register state
  • Inspect stack bounds and interrupt context
  • Trace backward to identify initial corruption

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 613,757. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.