# fix-skills

当 skill 或脚本未达到预期效果，或脚本报错时使用。

## 原则

**不要轻易使用 workaround。** 先定位根因，再决定修复方式。

## 流程

### 1. 收集信息

- 记录触发场景：怎么调用的，期望什么结果，实际什么结果
- 记录错误信息：完整输出（含 stack trace 或脚本调试输出）
- 确认环境：模型版本、节点、skill 版本（git log 有帮助）

### 2. 分析根因

按以下顺序排查：

1. **输入/参数是否正确** — 传给脚本或工具的参数是否符合预期？
2. **依赖是否满足** — 所需 secret、token、配置文件是否存在？
3. **脚本逻辑是否有 bug** — 读源码，必要时加 `set -x` 调试
4. **skill 设计是否有缺陷** — 逻辑本身是否覆盖了这个场景？

### 3. 定位到文件

- 确认问题出在哪个文件的哪一行
- 如果是 skill 本身的问题 → 进入 [improve-skills](./improve-skills.md) 流程
- 如果是脚本执行环境问题 → 记录在 memory/ 并提给 hang

### 4. 修复

- 在本地测试修复方案
- 如果需要修改 skill 文件 → 按 improve-skills 流程提交 PR 或直接 push 到分支
- 避免引入新的 side effect

### 5. 验证

- 复现原场景，确认问题已解决
- 记录修复内容到 memory/YYYY-MM-DD.md

### 6. 上报（如需要）

- 如果问题需要 hang 或其他 agent 介入 → 在 report channel 记录
- 包含：场景、期望/实际结果、根因、修复方案