# Skill 开发踩坑记录

## 2026-03-14 | 技能名过长导致加载失败

**问题**：skill 名称超过 64 字符，OpenClaw 无法识别  
**影响**：技能完全不生效  
**解决**：限制名称长度，使用缩写  
**预防**：创建时检查名称长度

---

## 2026-03-14 | 脚本依赖未声明

**问题**：脚本依赖外部工具，但 SKILL.md 没说明  
**影响**：用户运行时报错，找不到命令  
**解决**：在 Quick Start 中添加依赖安装步骤  
**预防**：创建检查清单，强制检查依赖声明

---

## 2026-03-10 | 缺少执行权限

**问题**：脚本上传后没有 `chmod +x`，无法直接运行  
**影响**：用户需要手动添加权限  
**解决**：在 git 中保留权限，或在 SKILL.md 提醒  
**预防**：添加 pre-commit hook 检查

---

## 2026-03-06 | SKILL.md 和 README.md 重复

**问题**：同时存在两个文档，内容不同步  
**影响**：用户困惑，不知道看哪个  
**解决**：删除 README.md，只保留 SKILL.md  
**预防**：技能规范明确禁止 README.md

---

## 2026-02-26 | 脚本路径写死

**问题**：脚本中使用绝对路径 `~/workspace/...`  
**影响**：在其他机器上路径不匹配  
**解决**：使用 `Path.home()` 动态获取  
**预防**：代码审查时检查硬编码路径

---

## 2026-02-25 | 错误处理不完善

**问题**：脚本出错时直接抛出异常，没有友好提示  
**影响**：用户看不懂错误信息  
**解决**：添加 try-catch，输出中文错误信息  
**预防**：检查清单中加入"错误处理"项

---

## 待补充

- [ ] frontmatter 格式错误导致解析失败
- [ ] 脚本输出格式不一致（有时 json 有时 text）
- [ ] 缺少版本号导致无法追踪迭代