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

📅 2026-03-19 👤 Elaine 👁️ 16 次阅读 ⏱️ 9 分钟阅读 ❤️ 0 赞

AI Agent 嵌入式

🤖 AI Coding Agent Skills 编写指南

    <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

    <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

调试流程

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

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

    <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 名称

使用方法

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

    <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

JLinkGDBServer -device STM32F407VG -if SWD -speed 4000

连接 GDB

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

    <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

环境检查

# 检查 J-Link
JLinkExe -version

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

调试流程

连接硬件
启动 GDB Server
GDB 连接
加载程序
开始调试

脚本

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

    <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

    </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

    <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 配置
}

    <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. 环境检查

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

# 或者检查版本
JLinkExe -version

2. 启动 GDB Server

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

3. GDB 调试

# 在终端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
```
<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 "$@"

    <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"

    <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"

echo "烧录完成！"

    <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"
    }
]

}

    <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"

}

    <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：使用自动化脚本

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

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

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

方式2：手动调试

启动 J-Link GDB Server：

JLinkGDBServer -device STM32F407VG -if SWD -speed 4000

GDB 连接：

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

故障排除

连接失败：检查硬件连接、J-Link 驱动
无法烧录：检查芯片是否被读保护

断点无效：确认 elf 文件包含调试信息 (-g)

<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>

🤖 AI Coding Agent Skills 编写指南

Embedded Debug Skill

快速开始

调试流程

Skill 名称

使用方法

Embedded Debug Skill

环境要求

调试命令

启动 J-Link GDB Server

连接 GDB

GDB 常用命令

自动调试流程

创建 SKILL.md

cat > .skills/embedded-debug/SKILL.md << 'EOF'

Embedded Debug Skill

环境检查

调试流程

脚本

参数说明

-device: 芯片型号

-if: 接口类型 (SWD/JTAG)

-speed: 调试速度 kHz

默认端口 2331

复位和停止

加载程序

断点

执行

寄存器

内存

查看变量

线程

目录结构

Embedded Debug Skill

环境要求

调试流程

1. 环境检查

2. 启动 GDB Server

3. GDB 调试

自动化脚本

参考文档

embedded-debug/scripts/debug.sh

自动化嵌入式调试脚本

配置

颜色输出

检查工具

检查环境

启动 GDB Server

调试函数

清理函数

主流程

embedded-debug/scripts/regs.sh

读取 ARM 寄存器和内存

GDB 命令文件

embedded-debug/scripts/flash.sh

Flash 烧录脚本

J-Link Commander 烧录命令

Embedded ARM Debug Skill

快速开始

方式1：使用自动化脚本

方式2：手动调试

GDB 常用命令

环境变量

Cortex-Debug 配置

故障排除

📚 相关文章