手把手教你给 Claude Code 添加 Keil 自动编译 Skill

前言

本教程记录如何在 Claude Code 中创建一个 Keil MDK 自动编译 Skill，实现：保存代码后自动编译、编译失败自动报错、项目启动自动检测 Keil 路径。

适合：用过 Keil 写单片机、想让 AI 帮你自动编译的小白。

最终效果

1
2


你：帮我把这行代码改一下
Claude：改好了 → 自动编译 → 0 Error, 0 Warning → 回复你结果

不需要你手动点开 Keil 点 Build，Claude 保存代码后自动帮你编译。

需要准备什么

东西	说明
Keil MDK	已经安装好，能正常编译你的工程
Claude Code	已经配置好，能打开你的项目文件夹
你的 Keil 工程	有 `.uvprojx` 工程文件

确认 Keil 命令行能用：

打开 CMD，输入你的 Keil 路径，例如：

1

D:\Keil_v5\UV4\UV4.exe -?

如果有反应（弹出 Keil 或显示帮助），说明路径是对的。

一步一步来做

第 1 步：创建项目内的 Skill 文件夹

在你的项目根目录下创建这个文件夹结构：

1
2
3


你的项目/
  └── .claude/
      └── skills/          ← 放这里

.claude 是 Claude Code 的配置文件夹，放在项目根目录下，Claude 会自动识别。

第 2 步：创建 Skill 文件

在 .claude/skills/ 下新建文件 keil-build.md，内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


---
name: keil-build
description: Keil MDK 项目编译自动化。项目启动时检测 Keil UV4 路径；代码修改后通过 PostToolUse hook 自动编译。
---

## 启动协议（必须执行）

每次本 Skill 被加载时，**必须**：

1. **检查 Keil 配置**：尝试读取 `.claude/keil_config.json`
   - 如果存在且路径有效：直接使用
   - 如果不存在：**询问用户** Keil UV4 的安装路径

2. **保存配置**：将路径写入 `.claude/keil_config.json`

## 自动编译机制

本项目已配置 `PostToolUse` hook：
- 每次 **Edit** 或 **Write** 修改代码后，自动触发编译
- bat 脚本读取 `.claude/keil_config.json` 中的路径执行增量编译
- **30 秒节流**：连续编辑不会重复编译

### 编译结果确认

每次修改代码后，**必须在回复用户前**：

1. **读取 `build_log.txt`** 确认结果
2. **解析输出**：
   - `0 Error(s), 0 Warning(s)` → 通过
   - `N Error(s)` → **停止**，报告错误
   - `0 Error(s), N Warning(s)` → 通过，但列出 Warning

## 手动编译命令

```bash
# 读取配置并编译
UV4=$(powershell -Command "(Get-Content .claude\keil_config.json | ConvertFrom-Json).uv4_path")
PRJ=$(powershell -Command "(Get-Content .claude\keil_config.json | ConvertFrom-Json).project_file")
cmd //c "$UV4 -b $PRJ -j0 -o build_log.txt"

配置格式

.claude/keil_config.json：

1
2
3
4
5


{
  "uv4_path": "D:\\Keil_v5\\UV4\\UV4.exe",
  "project_file": "MDK-ARM\\Project.uvprojx",
  "target_name": "PY32F002Ax5_Project"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18



**这个文件是干什么的？**
- 告诉 Claude："我这个项目要用 Keil 编译"
- Claude 每次启动项目时会先看这个 skill
- Skill 里规定了：改代码后要编译、启动时要问 Keil 装在哪

---

#### 第 3 步：创建 Keil 路径配置文件

在 `.claude/` 下新建 `keil_config.json`：

```json
{
  "uv4_path": "D:\\Keil_v5\\UV4\\UV4.exe",
  "project_file": "MDK-ARM\\Project.uvprojx",
  "target_name": "你的Target名称"
}

三个字段说明：

字段	填什么
`uv4_path`	Keil 安装目录下的 `UV4\UV4.exe` 完整路径
`project_file`	你的 `.uvprojx` 工程文件相对路径
`target_name`	Keil 工程里的 Target 名字（看 Keil 左上角下拉框）

如何找你的 Keil 路径？

右键 Keil 桌面快捷方式 → 属性 → 目标：

1

"D:\Keil_v5\UV4\UV4.exe"

把这个填到 uv4_path 里，注意 JSON 里要双反斜杠 \\。

第 4 步：创建自动编译脚本

在 .claude/ 下新建 auto_build.bat：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


@echo off
REM 30秒节流：避免连续多个Edit触发多次编译
if exist ".claude\.last_build" (
    for /f "usebackq delims=" %%a in (`powershell -Command "[math]::Floor(((Get-Date) - (Get-Item '.claude\.last_build').LastWriteTime).TotalSeconds)"`) do set "ELAPSED=%%a"
    if defined ELAPSED (
        if %%a LSS 30 exit /b 0
    )
)

REM 更新时间戳
powershell -Command "New-Item -ItemType File -Path '.claude\.last_build' -Force | Out-Null" >nul 2>&1

REM 读取配置
if not exist ".claude\keil_config.json" exit /b 0

for /f "usebackq delims=" %%i in (`powershell -Command "(Get-Content '.claude\keil_config.json' | ConvertFrom-Json).uv4_path"`) do set "UV4=%%i"
for /f "usebackq delims=" %%i in (`powershell -Command "(Get-Content '.claude\keil_config.json' | ConvertFrom-Json).project_file"`) do set "PRJ=%%i"

if "%UV4%"=="" exit /b 0
if "%PRJ%"=="" exit /b 0

REM 执行增量编译
cmd /c "%UV4%" -b "%PRJ%" -j0 -o build_log.txt

这个脚本是干什么的？

Claude 改完代码后，自动调用这个脚本
脚本去读 keil_config.json 里的路径
然后调用 Keil 命令行编译
30 秒内连续修改不会重复编译（省时间）

第 5 步：配置 settings.json（关键！）

在 .claude/ 下新建或编辑 settings.json：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cmd //c \".claude\\\\auto_build.bat\"",
            "statusMessage": "Keil auto-build..."
          }
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "cmd //c \".claude\\\\auto_build.bat\"",
            "statusMessage": "Keil auto-build..."
          }
        ]
      }
    ]
  }
}

这段配置是什么意思？

部分	含义
`PostToolUse`	每次 Claude 调用完工具后触发
`matcher: "Edit"`	只有 Edit（修改文件）后触发
`matcher: "Write"`	只有 Write（写入文件）后触发
`command`	触发后执行 `auto_build.bat`
`statusMessage`	编译时显示的状态提示

简单说：Claude 改完代码 → 自动跑 bat → 自动编译。

文件结构总览

完成后你的项目应该长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


你的项目/
  ├── .claude/
  │   ├── skills/
  │   │   └── keil-build.md      ← Skill 定义
  │   ├── auto_build.bat          ← 编译脚本
  │   ├── keil_config.json        ← Keil 路径配置
  │   └── settings.json           ← Hook 配置
  ├── MDK-ARM/
  │   └── Project.uvprojx         ← Keil 工程
  └── ... 其他代码文件

常见问题

Q1：编译报错 “找不到 UV4.exe”

检查 keil_config.json 里的 uv4_path 是否正确。路径里的反斜杠要双写：D:\\Keil_v5\\UV4\\UV4.exe。

Q2：Hook 没触发

确认 settings.json 放在 .claude/ 下，不是项目根目录。文件名必须是 settings.json（不是 setting.json）。

Q3：想暂停自动编译

在 Claude 对话里直接说"不用编译"或"跳过编译"，skill 规则里有例外处理。

Q4：多个项目都想用这个 skill

把整个 .claude/ 文件夹复制到其他项目，改一下 keil_config.json 里的工程路径即可。

Keil 命令行速查

命令	作用
`UV4.exe -b 工程.uvprojx -j0`	增量编译
`UV4.exe -r 工程.uvprojx -j0`	重新编译（全部重来）
`UV4.exe -f 工程.uvprojx -j0`	下载程序到单片机
`-j0`	不启动 Keil 界面，命令行直接跑
`-o log.txt`	把编译日志输出到文件

本教程随项目创建，记录于 2026-05-19。