16 KiB
16 KiB
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 会自动：
- 运行
git diff分析所有变更 - 理解变更内容和意图
- 生成符合项目风格的提交信息
- 执行
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
- CLAUDE.md 合规检查 ×2（检查代码是否遵循项目规则）
- Bug 扫描（检测潜在 Bug）
- 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
工作原理：
- Initializer Agent：分析任务，分解为子任务清单
- 生成
.autonomous/<task-name>/task_list.md和progress.md - Executor Agent：逐个执行子任务，自动更新进度
- 会话中断后，下次启动自动从
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 标准格式：
---
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 记录 |
六、注意事项
- Token 消耗：
/review-pr（6 Agent）和/ralph-loop（持续迭代）消耗较多 token，按需使用 /ralph-loop需要手动取消：通过/cancel-ralph停止，否则会一直运行/autonomous-skill的进度文件：保存在.autonomous/目录，不要手动删除未完成的任务/spec-kit-skill依赖外部工具：需要安装 GitHub Spec-Kit CLI，目前 ESP32 项目用不到- 插件更新：运行
claude plugins update可更新所有插件到最新版本 /skill-creator资料质量决定 Skill 质量：喂入的文档越专业、越详细，生成的 Skill 审查清单和排障表越准确。建议提供官方文档 + 实战踩坑经验的组合- Skill 持续迭代：首次创建的 Skill 不一定完美，随着实际开发中遇到新问题，持续补充更新 SKILL.md（类似你现有 ESP32 Skills 的演进过程）