# Claude Code 插件高效运用指南

> 更新日期: 2026-03-19（skill-creator 补充）
> 适用环境: macOS / Claude Code 2.1.37+ / ESP32 嵌入式开发

---

## 一、当前已安装资源总览

| 类别 | 数量 | 说明 |
|------|------|------|
| 官方插件 (claude-plugins-official) | 7 个 | Git 工作流、代码审查、功能开发、迭代循环、规则维护、Skill 创建 |
| 社区插件 (claude-code-settings) | 2 个 | 长时任务自主执行、规格驱动开发 |
| 自定义 Skills (~/.claude/skills/) | 10 个 | ESP32 专用 6 个 + RK3588/Linux 驱动 4 个 |
| 内置 Skills | 3 个 | simplify、loop、claude-api |

---

## 二、命令速查表

| 命令 | 来源 | 一句话说明 |
|------|------|-----------|
| `/commit` | commit-commands | 自动分析变更，生成提交信息并 commit |
| `/commit-push-pr` | commit-commands | 一键 commit → push → 创建 PR |
| `/clean_gone` | commit-commands | 清理远程已删除的本地分支 |
| `/code-review` | code-review | 4 个 Agent 并行审查，置信度过滤 |
| `/review-pr` | pr-review-toolkit | 6 个专业 Agent 综合 PR 审查 |
| `/feature-dev` | feature-dev | 7 阶段引导式功能开发 |
| `/ralph-loop` | ralph-loop | 迭代式自引用开发循环，持续直到任务完成 |
| `/cancel-ralph` | ralph-loop | 取消正在运行的 Ralph Loop |
| `/claude-md-improver` | claude-md-management | 审计 CLAUDE.md，检查与代码库一致性 |
| `/revise-claude-md` | claude-md-management | 从当前会话提取经验更新 CLAUDE.md |
| `/autonomous-skill` | autonomous-skill | 多会话长时任务自主执行 |
| `/spec-kit-skill` | spec-kit-skill | 7 阶段规格驱动开发工作流 |
| `/skill-creator` | skill-creator | **元技能**：交互式创建、测试、优化自定义 Skills |
| `/simplify` | 内置 | 审查代码复用性、质量和效率 |
| `/loop` | 内置 | 定时循环执行命令（如每 5 分钟检查一次） |

---


## 三、按场景分类的使用指南

### 场景 1：日常编码提交（每天用）

#### `/commit` — 智能提交

**何时用**：写完代码，需要提交时

**使用方式**：
```
你：/commit
```
Claude 会自动：
1. 运行 `git diff` 分析所有变更
2. 理解变更内容和意图
3. 生成符合项目风格的提交信息
4. 执行 `git commit`

**对比手动提交的优势**：
- 不用自己写 commit message
- 自动识别变更类型（feat/fix/refactor）
- 遵循项目已有的提交风格

---

#### `/commit-push-pr` — 一键发布

**何时用**：功能开发完成，需要提交 + 推送 + 创建 PR

**使用方式**：
```
你：/commit-push-pr
```
一步完成三件事，适合功能分支开发完成后快速发布。

---

#### `/clean_gone` — 清理分支

**何时用**：定期清理，或感觉本地分支太多时

**使用方式**：
```
你：/clean_gone
```
自动清理所有远程已删除但本地仍残留的分支（`git branch` 中标记为 `[gone]` 的）。

---

### 场景 2：代码审查（提交前 / PR 合并前）

#### `/code-review` — 快速审查

**何时用**：提交前快速检查是否有明显问题

**使用方式**：
```
你：/code-review
```

**工作原理**：启动 4 个并行 Agent
1. CLAUDE.md 合规检查 ×2（检查代码是否遵循项目规则）
2. Bug 扫描（检测潜在 Bug）
3. Git 历史上下文分析（结合 git log 理解变更背景）

置信度 < 80 的问题自动过滤，只报告高确信度问题。

**适合**：日常快速检查，耗时较短

---

#### `/review-pr` — 深度审查

**何时用**：重要功能合并前的全面审查

**使用方式**：
```
你：/review-pr
```

**工作原理**：启动 6 个专业 Agent
| Agent | 检查内容 |
|-------|---------|
| code-reviewer | 代码质量、Bug、安全漏洞 |
| comment-analyzer | 注释准确性和可维护性 |
| silent-failure-hunter | 静默失败和错误处理缺陷 |
| pr-test-analyzer | 测试覆盖质量 |
| type-design-analyzer | 类型设计质量（封装、不变量） |
| code-simplifier | 代码简化机会 |

**适合**：重要 PR、团队协作代码、关键功能上线前

**`/code-review` vs `/review-pr` 如何选择？**
| | `/code-review` | `/review-pr` |
|---|---|---|
| Agent 数量 | 4 个 | 6 个 |
| 耗时 | 较短 | 较长 |
| 深度 | 快速扫描 | 全面审查 |
| 使用频率 | 每次提交前 | 重要 PR 合并前 |

---

### 场景 3：功能开发（新功能 / 复杂任务）

#### `/feature-dev` — 引导式功能开发

**何时用**：开发新功能，需要系统性地理解代码库并设计方案

**使用方式**：
```
你：/feature-dev 添加 OTA 远程固件升级功能
```

**7 阶段工作流**：
```
阶段 1: 理解代码库 → code-explorer Agent 分析现有架构
阶段 2: 提问澄清   → 向你提出关键问题（如 OTA 源、回滚策略）
阶段 3: 需求确认   → 确认功能范围和约束
阶段 4: 架构设计   → code-architect Agent 设计方案
阶段 5: 实现       → 按设计方案编码
阶段 6: 审查       → code-reviewer Agent 检查实现质量
阶段 7: 总结       → 输出变更摘要
```

**ESP32 项目实际用例**：
```
你：/feature-dev 新增 BLE OTA 固件升级功能
你：/feature-dev 添加 MQTT 设备影子同步
你：/feature-dev 实现多语言 TTS 语音切换
```

**优势**：避免直接写代码导致的架构混乱，先理解再动手

---

#### `/autonomous-skill` — 长时任务自主执行

**何时用**：任务太大，一个会话搞不定（如大规模重构、全项目代码迁移）

**使用方式**：
```
你：/autonomous-skill 将项目从 ESP-IDF v5.1 迁移到 v5.4
```

**工作原理**：
1. **Initializer Agent**：分析任务，分解为子任务清单
2. 生成 `.autonomous/<task-name>/task_list.md` 和 `progress.md`
3. **Executor Agent**：逐个执行子任务，自动更新进度
4. 会话中断后，下次启动自动从 `progress.md` 继续

**适合**：
- 跨多文件的大规模重构
- 框架/SDK 版本迁移
- 全项目代码规范统一

---

### 场景 4：迭代式开发（调试 / 持续改进）

#### `/ralph-loop` — 持续迭代直到完成

**何时用**：任务需要多轮尝试才能完成（如调试、性能调优）

**使用方式**：
```
你：/ralph-loop 优化 GIF 动画播放性能，目标是音频不卡顿
```

**工作原理**：
- Claude 完成一轮后尝试退出 → Stop Hook 拦截 → 重新注入 prompt → 继续迭代
- 直到任务真正完成才停止

**取消方式**：
```
你：/cancel-ralph
```

**适合**：
- 性能调优（反复测量-修改-验证）
- 复杂 Bug 排查（需要多轮假设-验证）
- 代码质量持续改进

**注意**：会消耗较多 token，确保任务值得持续迭代

---

### 场景 5：知识管理（CLAUDE.md 维护）

#### `/claude-md-improver` — 审计规则文件

**何时用**：定期维护（建议每 1-2 周一次），或感觉 CLAUDE.md 与实际代码不一致时

**使用方式**：
```
你：/claude-md-improver
```

**输出**：
- 质量报告（一致性评分、过时内容、遗漏项）
- 自动更新建议
- 与当前代码库对比的差异分析

---

#### `/revise-claude-md` — 提取会话经验

**何时用**：解决了一个复杂问题后，在会话结束前执行

**使用方式**：
```
你：/revise-claude-md
```

**工作原理**：
- 回顾当前会话中的所有踩坑经验、解决方案、架构决策
- 自动提取有价值的内容更新到 CLAUDE.md
- 避免下次遇到同样问题

**最佳实践**：
```
解决完 Bug → 测试通过 → /revise-claude-md → /commit
```

---

### 场景 6：代码简化（内置）

#### `/simplify` — 代码简化审查

**何时用**：写完代码后，检查是否有可简化的地方

**使用方式**：
```
你：/simplify
```

**检查内容**：
- 代码复用机会
- 不必要的复杂度
- 可删除的冗余代码
- 保持功能不变的前提下简化实现

---

### 场景 7：自定义 Skill 创建与优化（元技能）

#### `/skill-creator` — 从零创建专业领域 Skills

**何时用**：需要为新的技术领域（如 Linux 驱动、Android HAL、新硬件平台）创建专属的 Claude Code Skill

**来源**：Anthropic 官方插件（claude-plugins-official），是一个"元技能"（Meta-Skill）— 专门用来创建其他 Skills 的 Skill。

**使用方式**：
```
你：/skill-creator
```

**四种操作模式**：

| 模式 | 命令 | 说明 |
|------|------|------|
| **Create** | `/skill-creator` | 通过交互式问答从零创建新 Skill，自动生成 SKILL.md |
| **Eval** | `/skill-creator eval` | 运行测试用例，对比有/无 Skill 的效果差异 |
| **Improve** | `/skill-creator improve` | 基于评测反馈自动迭代改进 Skill（最多 5 轮） |
| **Benchmark** | `/skill-creator benchmark` | A/B 盲测对比，量化 Skill 对输出质量的提升 |

**内置 4 个子 Agent**：

| Agent | 职责 |
|-------|------|
| Executor | 执行 Skill，生成输出结果 |
| Grader | 对输出结果评分（质量、准确性、完整性） |
| Comparator | A/B 盲测对比（有 Skill vs 无 Skill） |
| Analyzer | 分析评测结果，生成改进建议 |

**完整工作流程（Create 模式）**：

```
步骤 1: 捕获意图   → 理解你想让 Skill 做什么
步骤 2: 问答调研   → 收集边界情况、格式要求、依赖工具等
步骤 3: 编写 SKILL.md → 按最佳实践自动生成（含 frontmatter + 指令内容）
步骤 4: 定义测试用例 → 生成 2-3 个真实测试提示
步骤 5: 运行评估   → 执行 with-skill 和 baseline 对比打分
步骤 6: 迭代改进   → 根据反馈自动优化 SKILL.md 内容
步骤 7: 优化触发词 → 微调 description 字段提升触发精度
```

**实际用例**：

```
# 从零创建 Linux 驱动开发 Skill
你：/skill-creator
Claude：你想创建什么领域的 Skill？
你：Linux 内核驱动开发，包括设备树 DTS、GPIO/I2C/SPI 驱动、V4L2 摄像头驱动

# 从文档资料创建 Skill
你：/skill-creator
你：（提供 RK3588 SDK 文档、Android HAL 开发指南等资料）
Claude：自动消化资料 → 生成结构化的 SKILL.md

# 评估并优化已有 Skill
你：/skill-creator eval ~/.claude/skills/linux-driver/SKILL.md
你：/skill-creator improve ~/.claude/skills/linux-driver/SKILL.md
```

**生成的 SKILL.md 标准格式**：

```yaml
---
name: my-skill-name
description: 描述功能和触发时机（决定何时自动激活）
allowed-tools: Bash, Read, Grep, Glob    # 可选，限制可用工具
---

# Skill 标题

## 审查清单 / 排障速查表 / 构建流程
（结构化的专业知识内容）
```

**Skill 存放位置**：

| 范围 | 路径 | 说明 |
|------|------|------|
| 个人全局 | `~/.claude/skills/<name>/SKILL.md` | 所有项目通用（如你的 ESP32 Skills） |
| 项目级 | `.claude/skills/<name>/SKILL.md` | 仅当前项目 |
| 插件提供 | 插件安装目录内 | 通过 `claude plugins install` 安装 |

**与手动创建 Skill 的对比**：

| | 手动创建 | `/skill-creator` |
|---|---|---|
| 方式 | 自己编写 SKILL.md | 交互式引导 + 自动生成 |
| 测试 | 凭感觉验证 | 自动化评测 + A/B 对比 |
| 迭代 | 手动修改 | 自动分析 + 5 轮迭代优化 |
| 触发精度 | 靠经验写 description | 自动优化触发词 |
| 适合 | 熟悉 Skill 格式的用户 | 任何用户，尤其是新领域拓展 |

**最佳实践**：

```
准备资料（文档/教程/代码示例）
    ↓
/skill-creator（Create 模式，喂入资料）
    ↓
/skill-creator eval（评估效果）
    ↓
/skill-creator improve（迭代优化）
    ↓
投入使用，后续根据实际踩坑经验持续补充
```

---

## 四、ESP32 项目推荐工作流

### 日常开发流程

```
编码 → /simplify（检查简化）→ /commit（提交）
```

### 新功能开发流程

```
/feature-dev（引导开发）→ 编码 → 构建测试 → /code-review（快速审查）→ /commit-push-pr（发布）
```

### 重要功能上线流程

```
/feature-dev → 编码 → 构建测试 → /review-pr（深度审查）→ 修复审查问题 → /commit-push-pr
```

### 复杂 Bug 排查流程

```
/ralph-loop 排查并修复xxx问题 → 修复完成 → /revise-claude-md（记录经验）→ /commit
```

### 大规模重构流程

```
/autonomous-skill（自主执行重构）→ 检查结果 → /review-pr（审查）→ /commit-push-pr
```

### 定期维护流程（每 1-2 周）

```
/claude-md-improver（审计规则）→ /clean_gone（清理分支）
```

### 新领域 Skill 创建流程

```
收集资料（文档/教程/API手册）→ /skill-creator（创建）→ /skill-creator eval（评估）→ /skill-creator improve（优化）
```

**示例**：为香橙派 CM5 (RK3588S) 创建 Linux 驱动开发 Skills：
```
1. 准备 Rockchip BSP 文档、Linux 内核驱动教程、设备树语法说明
2. /skill-creator → 创建 linux-driver Skill
3. /skill-creator → 创建 android-hal Skill
4. /skill-creator → 创建 rk3588-build Skill
5. /skill-creator eval → 评估效果 → /skill-creator improve → 迭代优化
```

---

## 五、自定义 Skills 与自动触发

### Skills 自动触发机制

当前对话中，以下 Skills 会根据关键词自动激活：

| Skill | 触发条件 |
|-------|---------|
| esp-build | 你说"编译"、"构建"、"烧录" |
| esp-analyze-log | 你提供设备日志、提到 crash/panic |
| esp-troubleshoot | 你描述设备异常 |
| esp-optimize | 你提到"优化"、"内存不足" |
| esp-code-review | 你要求"代码审查"、"review" |
| esp-driver | 你说"写一个驱动" |
| linux-driver | 你说"Linux 驱动"、"设备树"、"内核模块" |
| android-hal | 你说"HAL"、"AIDL"、"HIDL"、"JNI" |
| rk3588-build | 你说"编译 SDK"、"刷机"、"Docker 编译环境" |
| rk3588-troubleshoot | 你描述驱动不工作、设备不识别、内核崩溃 |
| simplify | 通过 /simplify 调用 |
| loop | 通过 /loop 调用 |
| claude-api | 涉及 Anthropic SDK 开发 |

### ESP32 Skills 与插件配合

| 自定义 Skill | 触发方式 | 与插件配合 |
|-------------|---------|-----------|
| esp-build | "帮我编译" / "构建项目" | 编译 → `/commit` 提交 |
| esp-analyze-log | 提供日志文件路径 | 分析日志 → 修复 → `/revise-claude-md` 记录 |
| esp-troubleshoot | 描述设备异常现象 | 排障 → `/ralph-loop` 持续调试 |
| esp-optimize | "优化内存" / "固件太大" | 优化 → `/simplify` 检查 → `/commit` |
| esp-code-review | "帮我审查代码" | 先 esp-code-review → 再 `/review-pr` 双重审查 |
| esp-driver | "写一个I2C驱动" | `/feature-dev` 设计 → esp-driver 生成 → `/code-review` 审查 |

### RK3588/Linux 驱动 Skills 与插件配合

| 自定义 Skill | 触发方式 | 与插件配合 |
|-------------|---------|-----------|
| linux-driver | "写一个 GPIO/I2C/SPI 驱动" | `/feature-dev` 设计 → linux-driver 生成 → `/code-review` 审查 |
| android-hal | "开发 HAL 让 APP 控制硬件" | linux-driver 写驱动 → android-hal 写 HAL → `/review-pr` 审查 |
| rk3588-build | "编译内核" / "刷机" / "搭建编译环境" | 编译 → 刷机 → `/revise-claude-md` 记录踩坑 |
| rk3588-troubleshoot | "设备不识别" / "内核崩溃" | 排障 → `/ralph-loop` 持续调试 → `/revise-claude-md` 记录 |

---

## 六、注意事项

1. **Token 消耗**：`/review-pr`（6 Agent）和 `/ralph-loop`（持续迭代）消耗较多 token，按需使用
2. **`/ralph-loop` 需要手动取消**：通过 `/cancel-ralph` 停止，否则会一直运行
3. **`/autonomous-skill` 的进度文件**：保存在 `.autonomous/` 目录，不要手动删除未完成的任务
4. **`/spec-kit-skill` 依赖外部工具**：需要安装 GitHub Spec-Kit CLI，目前 ESP32 项目用不到
5. **插件更新**：运行 `claude plugins update` 可更新所有插件到最新版本
6. **`/skill-creator` 资料质量决定 Skill 质量**：喂入的文档越专业、越详细，生成的 Skill 审查清单和排障表越准确。建议提供官方文档 + 实战踩坑经验的组合
7. **Skill 持续迭代**：首次创建的 Skill 不一定完美，随着实际开发中遇到新问题，持续补充更新 SKILL.md（类似你现有 ESP32 Skills 的演进过程）