chrislee121 pitfall-skill（踩坑 Skill）
纯 Agent Skill（Agent Skills 协议）：踩坑错题本由 scripts/pitfall.js 维护（零 npm 依赖，Node ≥ 18）。
跨 runtime：Cursor / Claude Code / Codex / OpenClaw / Hermes / Workbuddy / CodeBuddy / Gemini / OpenCode 等。路径见 references/runtimes.md。
自动触发（提高命中）
出现下列任一情况时，先读本 Skill 再动手，不要只在对话里复述：
- 用户提到：踩坑、又踩、又出现、老问题、重复、错题本、recurring、pitfall、复盘、沉淀、固化、写 rule、总结踩坑经验、升级成规则/Skill
- 用户问：有没有触发踩坑 skill / 记进错题本了吗 / 帮我 log
- 修完一个「第二次才发现」或「预览 OK、粘贴/真机才坏」的问题
- 症状与
.pitfalls/ledger.yaml或已有导出/兼容 rule 高度相似 - Agent 自己准备「总结踩坑经验」——必须走本流程写入错题本，禁止只输出 Markdown 摘要
不确定时：先 status / 读 .pitfalls/；宁可 log 一笔草稿，也不要沉默。
Hard rules / 硬性约束
- 升级前先确认。 对话里先问用户；禁止静默改规则文件或生成领域 Skill。
- Threshold:
occurrence_count >= 2才可升级（CLI 子命令仍为promote）。 - 长经验 → skill，短约束 → rule，避免撑爆
CLAUDE.md/AGENTS.md。 - 用本目录
scripts/pitfall.js；找不到则按同样文件布局手写。 - 总结 ≠ 写入错题本：口头总结后若用户未反对，应继续
init（如需要）+log。
Scripts / 脚本
SKILL_ROOT = 含本 SKILL.md 的目录（例如项目 .cursor/skills/pitfall-skill 或 .agents/skills/pitfall-skill）。
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 / 步骤
detect+ 必要时init --cwd .- 读
.pitfalls/ledger.yaml→log（bump 或新建；补全现象/根因/错误/正确/验证） - 若已有「正确做法」，修复时优先遵循
- 用户确认后
resolve … --yes count >= 2时建议 target → 用户确认后promote（对外称「升级」）- 汇报写出路径；告知已写入错题本（避免「以为触发了其实只聊天」）
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/