057、编写第一个 Skill：SKILL.md 规范、触发条件设计、参数传递与回退策略
从一次凌晨三点的事故说起
上周四凌晨，我盯着终端里Claude Code反复重试同一个API调用，日志里全是“Skill execution failed: missing required parameter”。那个Skill是我花了两天写的，自测时跑得飞起，一上生产环境就翻车。原因很简单——触发条件写得太死，参数传递路径没考虑网络抖动，回退策略压根没写。
这种痛，写过三个以上Skill的人应该都懂。今天这篇笔记，就是把我踩过的坑、重构后的最佳实践，以及那些文档里没写的潜规则，一次性倒出来。
SKILL.md 规范：别把它当README写
很多人第一次写Skill，习惯性把SKILL.md写成使用说明书。这是第一个坑。Claude Code解析Skill时，SKILL.md是行为契约，不是人类阅读的文档。
文件结构铁律
skill-name/ ├── SKILL.md # 必须，行为定义 ├── handler.sh # 必须，执行入口 └── config.json # 可选，环境配置SKILL.md的YAML front matter里，name字段必须和目录
