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

> 作者: Elaine
> 日期: 2026-03-19
> 标签: AI Agent, 嵌入式

---

<h1>🤖 AI Coding Agent Skills 编写指南</h1>
        <p class="subtitle">OpenClaw / Kilo Code / Open Code 技能开发 + 嵌入式调试实战 | 2026-03-19</p>

        <div class="info">
            <div class="info-title">📋 目录</div>
            <ul>
                <li><a href="#skill基础" style="color:#60a5fa;">Skills 基础概念</a></li>
                <li><a href="#skill结构" style="color:#60a5fa;">Skills 目录结构</a></li>
                <li><a href="#openclaw-skill" style="color:#60a5fa;">OpenClaw Skills 编写</a></li>
                <li><a href="#kilo-skill" style="color:#60a5fa;">Kilo Code / Open Code Skills</a></li>
                <li><a href="#嵌入式调试" style="color:#60a5fa;">嵌入式调试工具链</a></li>
                <li><a href="#实战skill" style="color:#60a5fa;">嵌入式调试 Skill 实战</a></li>
                <li><a href="#调试脚本" style="color:#60a5fa;">调试自动化脚本</a></li>
                <li><a href="#总结" style="color:#60a5fa;">总结</a></li>
            </ul>
        </div>

        <h2 id="skill基础">🤔 Skills 是什么？</h2>

        <div class="section">
            <p><strong>Skills</strong> 是扩展 AI Coding Agent 能力的模块化包，为 AI 提供特定领域的专业知识、工作流程和工具集成。</p>
            <p>可以把 Skills 理解为 AI 的「专业培训课程」——让通用 AI 变成特定领域的专家。</p>
        </div>

        <div class="section">
            <h3>Skills 能做什么？</h3>
            <ul>
                <li><strong>专业工作流</strong>：特定领域的多步骤操作流程</li>
                <li><strong>工具集成</strong>：与特定文件格式、API、硬件的交互</li>
                <li><strong>领域知识</strong>：公司规范、数据结构、业务逻辑</li>
                <li><strong>脚本资源</strong>：复杂重复任务的自动化脚本</li>
            </ul>
        </div>

        <h2 id="skill结构">📁 Skills 目录结构</h2>

        <div class="section">
            <p>一个 Skill 通常包含以下结构：</p>
            <pre><code>skill-name/
├── SKILL.md (必需)           # 技能说明文档
├── scripts/                 # 可执行脚本
│   ├── debug.sh
│   └── flash.py
├── references/              # 参考文档
│   ├── jlink.md
│   └── cortex-debug.md
└── assets/                 # 资源文件
    ├── launch.json
    └── template.cfg</code></pre>
        </div>

        <div class="section">
            <h3>SKILL.md 结构</h3>
            <pre><code>---
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</code></pre>
        </div>

        <h2 id="openclaw-skill">🔧 OpenClaw Skills 编写</h2>

        <div class="section">
            <h3>OpenClaw Skill 结构</h3>
            <p>OpenClaw 的 Skills 使用类似 Markdown + YAML frontmatter 的格式：</p>
            <pre><code>---
name: skill-name
description: 技能描述，触发条件
---

# Skill 名称

## 使用方法

这里写详细的技能说明...
</code></pre>
        </div>

        <div class="section">
            <h3>OpenClaw 工具调用</h3>
            <p>OpenClaw Skills 可以使用内置工具：</p>
            <ul>
                <li><code>exec</code>：执行 shell 命令</li>
                <li><code>process</code>：管理后台进程</li>
                <li><code>read/write</code>：读写文件</li>
                <li><code>subagents</code>：启动子任务</li>
            </ul>
        </div>

        <div class="section">
            <h3>示例：OpenClaw Skill</h3>
            <pre><code>---
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
</code></pre>
        </div>

        <h2 id="kilo-skill">⚡ Kilo Code / Open Code Skills</h2>

        <div class="section">
            <p>Kilo Code 和 Open Code 都支持类似的 Skill 扩展机制。Skill 文件放在项目的 <code>.skills/</code> 目录下。</p>
        </div>

        <div class="section">
            <h3>创建 Skill</h3>
            <pre><code># 创建 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</code></pre>
        </div>

        <h2 id="嵌入式调试">🔍 嵌入式调试工具链</h2>

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

        <div class="section">
            <h3>J-Link GDB Server</h3>
            <pre><code># 启动 J-Link GDB Server
JLinkGDBServer -device STM32F407VG -if SWD -speed 4000

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

# 默认端口 2331</code></pre>
        </div>

        <div class="section">
            <h3>GDB 调试命令</h3>
            <pre><code># 基本连接
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</code></pre>
        </div>

        <h2 id="实战skill">💻 嵌入式调试 Skill 实战</h2>

        <div class="section">
            <h3>创建 Skill 目录结构</h3>
            <pre><code># 创建 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 配置
}</code></pre>
        </div>

        <div class="section">
            <h3>SKILL.md 主文件</h3>
            <pre><code>---
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
</code></pre>
        </div>

        <div class="section">
            <h3>自动调试脚本 debug.sh</h3>
            <pre><code>#!/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 "$@"</code></pre>
        </div>

        <div class="section">
            <h3>寄存器读取脚本 regs.sh</h3>
            <pre><code>#!/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"</code></pre>
        </div>

        <div class="section">
            <h3>Flash 烧录脚本 flash.sh</h3>
            <pre><code>#!/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 "烧录完成！"</code></pre>
        </div>

        <h2 id="调试脚本">🔧 Cortex-Debug + EIDE 配置</h2>

        <div class="section">
            <h3>Cortex-Debug launch.json</h3>
            <pre><code>{
    "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"
        }
    ]
}</code></pre>
        </div>

        <div class="section">
            <h3>EIDE 配置</h3>
            <pre><code>// .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"
}</code></pre>
        </div>

        <div class="section">
            <h3>完整的调试 Skill (Kilo Code / Open Code)</h3>
            <pre><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)
</code></pre>
        </div>

        <h2 id="总结">📝 总结</h2>

        <div class="success">
            <div class="success-title">✅ Skills 编写要点</div>
            <ul>
                <li><strong>结构清晰</strong>：SKILL.md + scripts/ + references/</li>
                <li><strong>描述准确</strong>：description 要包含触发条件</li>
                <li><strong>脚本自动化</strong>：复杂操作写成脚本，AI 直接调用</li>
                <li><strong>参考文档</strong>：详细用法放在 references/</li>
            </ul>
        </div>

        <div class="warning">
            <div class="warning-title">⚠️ 嵌入式调试注意事项</div>
            <ul>
                <li>确保 J-Link 固件是最新的</li>
                <li>检查芯片是否被读保护</li>
                <li>SWD 接口只需要 4 根线：VCC、GND、SWDIO、SWDCLK</li>
                <li>调试前先确认芯片型号和连接</li>
            </ul>
        </div>