504 lines
16 KiB
Markdown
504 lines
16 KiB
Markdown
# 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 的演进过程）
|