AI Coding Agent Skills 编写指南：嵌入式调试实战

OpenClaw / Kilo Code / Open Code 技能开发 + 嵌入式调试实战 | 2026-03-19

📋 目录

Skills 基础概念
Skills 目录结构
OpenClaw Skills 编写
Kilo Code / Open Code Skills
嵌入式调试工具链
嵌入式调试 Skill 实战
调试自动化脚本
总结

🤔 Skills 是什么？

Skills 是扩展 AI Coding Agent 能力的模块化包，为 AI 提供特定领域的专业知识、工作流程和工具集成。

可以把 Skills 理解为 AI 的「专业培训课程」——让通用 AI 变成特定领域的专家。

Skills 能做什么？

专业工作流：特定领域的多步骤操作流程
工具集成：与特定文件格式、API、硬件的交互
领域知识：公司规范、数据结构、业务逻辑
脚本资源：复杂重复任务的自动化脚本

📁 Skills 目录结构

一个 Skill 通常包含以下结构：

skill-name/
├── SKILL.md (必需)           # 技能说明文档
├── scripts/                 # 可执行脚本
│   ├── debug.sh
│   └── flash.py
├── references/              # 参考文档
│   ├── jlink.md
│   └── cortex-debug.md
└── assets/                 # 资源文件
    ├── launch.json
    └── template.cfg

SKILL.md 结构

---
name: embedded-debug
description: 嵌入式调试技能，当需要调试 ARM Cortex-M 微控制器、使用 J-Link、OpenOCD、设置断点、读取寄存器时触发。
---

# Embedded Debug Skill

## 快速开始

使用前确保已安装：
- J-Link Software
- ARM GCC Toolchain
- OpenOCD 或 J-Link GDB Server

## 调试流程

1. 连接硬件
2. 启动 GDB Server
3. 配置 launch.json
4. 开始调试

...详细步骤见 references/jlink.md

🔧 OpenClaw Skills 编写

OpenClaw Skill 结构

OpenClaw 的 Skills 使用类似 Markdown + YAML frontmatter 的格式：

---
name: skill-name
description: 技能描述，触发条件
---

# Skill 名称

## 使用方法

这里写详细的技能说明...

OpenClaw 工具调用

OpenClaw Skills 可以使用内置工具：

exec：执行 shell 命令
process：管理后台进程
read/write：读写文件
subagents：启动子任务

示例：OpenClaw Skill

---
name: embedded-debug
description: 嵌入式 ARM Cortex-M 调试技能。使用场景：(1) 使用 J-Link 调试 (2) 使用 OpenOCD (3) 读取寄存器 (4) 设置断点 (5) 单步执行
---

# Embedded Debug Skill

## 环境要求

- J-Link Software 安装
- ARM GCC Toolchain (arm-none-eabi-gdb)
- 硬件连接（J-Link + 目标板）

## 调试命令

### 启动 J-Link GDB Server

```bash
JLinkGDBServer -device STM32F407VG -if SWD -speed 4000
```

### 连接 GDB

```bash
arm-none-eabi-gdb build/app.elf
```

### GDB 常用命令

| 命令 | 说明 |
|------|------|
| `target remote localhost:2331` | 连接调试器 |
| `monitor reset` | 复位目标 |
| `monitor halt` | 停止 |
| `load` | 加载程序 |
| `break main` | 设置断点 |
| `continue` | 继续运行 |
| `next` | 单步 |
| `info registers` | 查看寄存器 |
| `x/32x 0x08000000` | 查看内存 |

## 自动调试流程

见 scripts/auto-debug.sh

⚡ Kilo Code / Open Code Skills

Kilo Code 和 Open Code 都支持类似的 Skill 扩展机制。Skill 文件放在项目的 .skills/ 目录下。

创建 Skill

# 创建 skill 目录
mkdir -p .skills/embedded-debug

# 创建 SKILL.md
cat > .skills/embedded-debug/SKILL.md << 'EOF'
---
name: embedded-debug
description: 嵌入式 ARM 调试专家。触发条件：调试 ARM Cortex-M、使用 J-Link/OpenOCD、设置断点、读取寄存器、Flash 编程
---

# Embedded Debug Skill

## 环境检查

```bash
# 检查 J-Link
JLinkExe -version

# 检查 ARM GCC
arm-none-eabi-gdb --version
```

## 调试流程

1. 连接硬件
2. 启动 GDB Server
3. GDB 连接
4. 加载程序
5. 开始调试

## 脚本

使用 scripts/ 目录下的自动化脚本。
EOF

🔍 嵌入式调试工具链

工具链组成

工具	用途	说明
J-Link	调试器硬件	SEGER 出品的 ARM 调试器
OpenOCD	开源调试服务器	支持多种调试器
Cortex-Debug	VSCode 调试扩展	提供图形化调试界面
EIDE	嵌入式开发环境	VSCode 扩展，集成编译调试
arm-none-eabi-gdb	GDB 调试客户端	命令行调试工具

J-Link GDB Server

# 启动 J-Link GDB Server
JLinkGDBServer -device STM32F407VG -if SWD -speed 4000

# 参数说明
# -device: 芯片型号
# -if: 接口类型 (SWD/JTAG)
# -speed: 调试速度 kHz

# 默认端口 2331

GDB 调试命令

# 基本连接
target remote localhost:2331

# 复位和停止
monitor reset
monitor halt

# 加载程序
load

# 断点
break main          # 在 main 设置断点
break *0x08000000   # 在地址设置断点
delete 1            # 删除断点 1

# 执行
continue            # 继续运行
next                # 单步（不进入函数）
step                # 单步（进入函数）
finish              # 运行到函数返回

# 寄存器
info registers      # 查看所有寄存器
print $r0          # 查看 r0 寄存器
set $r0 = 0x1234   # 修改寄存器

# 内存
x/16x 0x20000000   # 查看内存 (16个32位数)
x/32b 0x08000000   # 查看32字节
set {int}0x20000000 = 0  # 写入内存

# 查看变量
print variable_name
info locals        # 查看局部变量
info args          # 查看函数参数

# 线程
info threads       # 查看线程
thread 2           # 切换到线程 2

💻 嵌入式调试 Skill 实战

创建 Skill 目录结构

# 创建 skill
mkdir -p .skills/embedded-debug/scripts
mkdir -p .skills/embedded-debug/references

# 目录结构
.skill/
├── SKILL.md
├── scripts/
│   ├── debug.sh          # 自动调试脚本
│   ├── flash.sh          # Flash 烧录脚本
│   └── regs.sh           # 读取寄存器脚本
└── references/
    ├── jlink-commands.md # J-Link 常用命令
    └── cortex-debug.md    # Cortex-Debug 配置
}

SKILL.md 主文件

---
name: embedded-debug
description: 嵌入式 ARM Cortex-M 调试专家。触发条件：调试 ARM 微控制器、使用 J-Link 或 OpenOCD、设置断点、读取寄存器、Flash 烧录、单步调试、查看内存、反汇编
---

# Embedded Debug Skill

当需要调试嵌入式 ARM Cortex-M 微控制器时使用此技能。

## 环境要求

- J-Link Software (JLinkExe, JLinkGDBServer)
- ARM GCC Toolchain (arm-none-eabi-gdb, arm-none-eabi-readelf)
- 硬件：J-Link + 目标板连接

## 调试流程

### 1. 环境检查

```bash
# 检查 J-Link 连接
JLinkExe -device STM32F407VG -if SWD -speed 4000 -CommanderScript connect.cjs

# 或者检查版本
JLinkExe -version
```

### 2. 启动 GDB Server

```bash
# 在终端1启动
JLinkGDBServer -device STM32F407VG -if SWD -speed 4000
```

### 3. GDB 调试

```bash
# 在终端2连接
arm-none-eabi-gdb build/app.elf

# GDB 中执行
(gdb) target remote localhost:2331
(gdb) monitor reset
(gdb) load
(gdb) break main
(gdb) continue
```

## 自动化脚本

使用 scripts/auto-debug.sh 进行一键调试。

## 参考文档

- J-Link 命令：references/jlink-commands.md
- Cortex-Debug 配置：references/cortex-debug.md

自动调试脚本 debug.sh

#!/bin/bash
# embedded-debug/scripts/debug.sh
# 自动化嵌入式调试脚本

set -e

# 配置
DEVICE="${DEVICE:-STM32F407VG}"
INTERFACE="${INTERFACE:-SWD}"
SPEED="${SPEED:-4000}"
ELF_FILE="${ELF_FILE:-build/app.elf}"
GDB_PORT="${GDB_PORT:-2331}"

# 颜色输出
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

echo_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
echo_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
echo_error() { echo -e "${RED}[ERROR]${NC} $1"; }

# 检查工具
check_tool() {
    if ! command -v $1 &> /dev/null; then
        echo_error "$1 未安装"
        exit 1
    fi
}

# 检查环境
check_env() {
    echo_info "检查环境..."
    check_tool JLinkGDBServer
    check_tool arm-none-eabi-gdb
    
    if [ ! -f "$ELF_FILE" ]; then
        echo_error "ELF 文件不存在: $ELF_FILE"
        exit 1
    fi
    
    echo_info "环境检查通过"
}

# 启动 GDB Server
start_gdb_server() {
    echo_info "启动 J-Link GDB Server..."
    echo_info "设备: $DEVICE"
    echo_info "接口: $INTERFACE"
    echo_info "速度: ${SPEED}kHz"
    
    JLinkGDBServer \
        -device "$DEVICE" \
        -if "$INTERFACE" \
        -speed "$SPEED" \
        -port "$GDB_PORT" \
        -singlerun \
        -silent \
        -timeout 0 &
    
    GDB_SERVER_PID=$!
    echo_info "GDB Server PID: $GDB_SERVER_PID"
    sleep 2
}

# 调试函数
debug_gdb() {
    echo_info "启动 GDB 调试..."
    
    arm-none-eabi-gdb -iex "target remote localhost:$GDB_PORT" \
                      -iex "monitor reset" \
                      -iex "load" \
                      "$ELF_FILE"
}

# 清理函数
cleanup() {
    echo_info "清理..."
    if [ ! -z "$GDB_SERVER_PID" ]; then
        kill $GDB_SERVER_PID 2>/dev/null || true
    fi
}

trap cleanup EXIT

# 主流程
main() {
    check_env
    start_gdb_server
    debug_gdb
}

main "$@"

寄存器读取脚本 regs.sh

#!/bin/bash
# embedded-debug/scripts/regs.sh
# 读取 ARM 寄存器和内存

GDB_PORT="${GDB_PORT:-2331}"
ELF_FILE="${ELF_FILE:-build/app.elf}"

echo "=========================================="
echo "ARM Cortex-M 寄存器读取"
echo "=========================================="

# GDB 命令文件
cat > /tmp/regs.gdb << 'EOF'
target remote localhost:2331
monitor halt

echo \n========== 寄存器 ==========\n
info registers

echo \n========== 特殊寄存器 ==========\n
echo PC (Program Counter):\n
print/x $pc

echo SP (Stack Pointer):\n
print/x $sp

echo LR (Link Register):\n
print/x $lr

echo \n========== xPSR ==========\n
print/x $xpsr

monitor reg

echo \n========== 内存 (栈) ==========\n
x/16x $sp

detach
quit
EOF

arm-none-eabi-gdb -batch -x /tmp/regs.gdb "$ELF_FILE"

Flash 烧录脚本 flash.sh

#!/bin/bash
# embedded-debug/scripts/flash.sh
# Flash 烧录脚本

set -e

DEVICE="${DEVICE:-STM32F407VG}"
INTERFACE="${INTERFACE:-SWD}"
SPEED="${SPEED:-4000}"
BIN_FILE="${BIN_FILE:-build/app.bin}"
ADDR="${ADDR:-0x08000000}"

echo "=========================================="
echo "Flash 烧录"
echo "=========================================="
echo "设备: $DEVICE"
echo "文件: $BIN_FILE"
echo "地址: $ADDR"

# J-Link Commander 烧录命令
JLinkExe -device "$DEVICE" \
         -if "$INTERFACE" \
         -speed "$SPEED" \
         -CommanderScript <(cat << 'EOF'
connect
loadfile $BIN_FILE $ADDR
r
qc
EOF
)

echo "烧录完成！"

🔧 Cortex-Debug + EIDE 配置

Cortex-Debug launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Cortex Debug (J-Link)",
            "cwd": "${workspaceFolder}",
            "executable": "build/app.elf",
            "request": "launch",
            "type": "cortex-debug",
            "runToEntryPoint": "main",
            "servertype": "jlink",
            "device": "STM32F407VG",
            "interface": "swd",
            "serialNumber": "",
            "jlinkscript": "",
            "svdFile": "STM32F407.svd",
            "searchDir": [],
            "configuration": {
                "displayFormat": "hex",
                "showFull SyrbolTable": true,
                "showStatic Variables": true
            },
            "searchDir": ["/opt/SEGGER/JLink"],
            "serverpath": "JLinkGDBServer"
        },
        {
            "name": "Cortex Debug (OpenOCD)",
            "executable": "build/app.elf",
            "request": "launch",
            "type": "cortex-debug",
            "runToEntryPoint": "main",
            "servertype": "openocd",
            "configFiles": [
                "interface/jlink.cfg",
                "target/stm32f4x.cfg"
            ],
            "searchDir": ["/usr/share/openocd/scripts"],
            "openocdCommands": [
                "adapter speed 4000"
            ],
            "device": "STM32F407VG"
        }
    ]
}

EIDE 配置

// .vscode/settings.json for EIDE
{
    // EIDE 配置
    "eide.build.targetDir": "build",
    "eide.build.elfName": "app.elf",
    
    // 调试器配置
    "cortex-debug.JLinkGDBServerPath": "/opt/SEGGER/JLink/JLinkGDBServer",
    "cortex-debug.openOCDPath": "/usr/bin/openocd",
    
    // ARM GCC 路径
    "cortex-debug.armToolchainPath": "/usr/bin"
}

完整的调试 Skill (Kilo Code / Open Code)

---
name: embedded-arm-debug
description: 嵌入式 ARM Cortex-M 调试专家。触发：调试 ARM、单步执行、设置断点、读取寄存器、查看内存、Flash 烧录、反汇编、J-Link、OpenOCD、EIDE、Cortex-Debug
---

# Embedded ARM Debug Skill

## 快速开始

### 方式1：使用自动化脚本

```bash
# 一键调试
./.skills/embedded-debug/scripts/debug.sh

# 读取寄存器
./.skills/embedded-debug/scripts/regs.sh

# 烧录 Flash
./.skills/embedded-debug/scripts/flash.sh
```

### 方式2：手动调试

1. 启动 J-Link GDB Server：
```bash
JLinkGDBServer -device STM32F407VG -if SWD -speed 4000
```

2. GDB 连接：
```bash
arm-none-eabi-gdb build/app.elf
(gdb) target remote localhost:2331
(gdb) load
(gdb) break main
(gdb) continue
```

## GDB 常用命令

| 命令 | 说明 |
|------|------|
| `target remote :2331` | 连接调试器 |
| `monitor reset halt` | 复位 |
| `load` | 加载程序 |
| `break func` | 断点 |
| `next` / `step` | 单步 |
| `info registers` | 寄存器 |
| `x/16x addr` | 内存 |

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| DEVICE | STM32F407VG | 芯片型号 |
| INTERFACE | SWD | 接口 |
| SPEED | 4000 | 速度 kHz |
| ELF_FILE | build/app.elf | ELF 路径 |
| GDB_PORT | 2331 | GDB 端口 |

## Cortex-Debug 配置

使用 VSCode + Cortex-Debug 扩展时，配置见 .vscode/launch.json

## 故障排除

1. **连接失败**：检查硬件连接、J-Link 驱动
2. **无法烧录**：检查芯片是否被读保护
3. **断点无效**：确认 elf 文件包含调试信息 (-g)

📝 总结

✅ Skills 编写要点

结构清晰：SKILL.md + scripts/ + references/
描述准确：description 要包含触发条件
脚本自动化：复杂操作写成脚本，AI 直接调用
参考文档：详细用法放在 references/

⚠️ 嵌入式调试注意事项

确保 J-Link 固件是最新的
检查芯片是否被读保护
SWD 接口只需要 4 根线：VCC、GND、SWDIO、SWDCLK
调试前先确认芯片型号和连接