---
name: pitfall-skill
description: >-
  踩坑错题本与规则/Skill 升级（跨 Agent：Cursor、Claude Code、Codex、OpenClaw、
  Hermes、Workbuddy、CodeBuddy、Gemini CLI、OpenCode 等 Agent Skills 兼容端）。
  把反复出现的同类 bug/兼容坑记入 .pitfalls/，≥2 次且用户确认后升级为 .mdc /
  CLAUDE.md / AGENTS.md 或领域 Skill。MUST use when: 踩坑/又出现/错题本/
  recurring/pitfall/沉淀/固化规则/总结踩坑/用踩坑 skill 记录；预览正常但
  粘贴/真机才坏；问「触发了吗」。禁止只口头总结而不写错题本。
---

# pitfall-skill（踩坑 Skill）

纯 Agent Skill（[Agent Skills](https://agentskills.io) 协议）：**踩坑错题本**由 `scripts/pitfall.js` 维护（零 npm 依赖，Node ≥ 18）。

跨 runtime：Cursor / Claude Code / Codex / OpenClaw / Hermes / Workbuddy / CodeBuddy / Gemini / OpenCode 等。路径见 `references/runtimes.md`。

## 自动触发（提高命中）

出现下列任一情况时，**先读本 Skill 再动手**，不要只在对话里复述：

1. 用户提到：踩坑、又踩、又出现、老问题、重复、错题本、recurring、pitfall、复盘、沉淀、固化、写 rule、总结踩坑经验、升级成规则/Skill
2. 用户问：有没有触发踩坑 skill / 记进错题本了吗 / 帮我 log
3. 修完一个「第二次才发现」或「预览 OK、粘贴/真机才坏」的问题
4. 症状与 `.pitfalls/ledger.yaml` 或已有导出/兼容 rule 高度相似
5. Agent 自己准备「总结踩坑经验」——**必须走本流程写入错题本**，禁止只输出 Markdown 摘要

不确定时：先 `status` / 读 `.pitfalls/`；宁可 `log` 一笔草稿，也不要沉默。

## Hard rules / 硬性约束

1. **升级前先确认。** 对话里先问用户；禁止静默改规则文件或生成领域 Skill。
2. **Threshold:** `occurrence_count >= 2` 才可升级（CLI 子命令仍为 `promote`）。
3. **长经验 → skill，短约束 → rule**，避免撑爆 `CLAUDE.md` / `AGENTS.md`。
4. 用本目录 `scripts/pitfall.js`；找不到则按同样文件布局手写。
5. **总结 ≠ 写入错题本**：口头总结后若用户未反对，应继续 `init`（如需要）+ `log`。

## Scripts / 脚本

`SKILL_ROOT` = 含本 `SKILL.md` 的目录（例如项目 `.cursor/skills/pitfall-skill` 或 `.agents/skills/pitfall-skill`）。

```bash
node "$SKILL_ROOT/scripts/pitfall.js" <command> [flags]
```

| 命令 | 作用 |
|------|------|
| `init` | 创建项目 `.pitfalls/` |
| `log --title … --area …` | 新建或 bump |
| `resolve <slug>` | 确认后标记 resolved |
| `status` | 列出 count≥2 与建议 target |
| `promote <slug> [--target auto\|rule\|skill]` | **升级**：写出 rule 或领域 skill |
| `detect` | 探测宿主 |
| `sync-check` | 校验产物 |

Flags：`--cwd <项目根>`、`--host cursor,claude,codex,openclaw,hermes,workbuddy,…|all`、`--yes`、`--scope project|global`。

多端探测与写出路径见仓库 `references/runtimes.md`。

## Required confirmation / 必问

resolve 前：① 是否已在真实环境验证解决？② 根因是否准确可复用？  
升级前：③ 选 **rule** 还是 **skill**？是否同意写入路径？

## Workflow / 步骤

1. `detect` + 必要时 `init --cwd .`
2. 读 `.pitfalls/ledger.yaml` → `log`（bump 或新建；补全现象/根因/错误/正确/验证）
3. 若已有「正确做法」，修复时优先遵循
4. 用户确认后 `resolve … --yes`
5. `count >= 2` 时建议 target → 用户确认后 `promote`（对外称「升级」）
6. 汇报写出路径；告知已写入错题本（避免「以为触发了其实只聊天」）

`auto`：正文 ≳ 80 行或 ≥ 3 个「核心约束 / Core constraint」→ `skill`，否则 `rule`。

## Anti-patterns / 禁止

- 第一次出现就升级；刷 count；长文塞进 CLAUDE/AGENTS
- **只总结不写错题本 / `.pitfalls/`**（本 Skill 最大失败模式）
- 因 `--yes` 跳过对话确认

## Layout

```
pitfall-skill/
├── SKILL.md
├── scripts/pitfall.js
├── templates/
└── examples/
```