来源：video2markdown + image-analyzer 两个 Skill 的开发实战。

教训与原则

1. 依赖开箱即用

Skill 不应要求用户手动安装依赖。像 whisper.cpp 编译 + HuggingFace 模型下载这种耗时操作，应在开发阶段就完成并收录到 Skill 目录中，用户使用时零配置。

• 做法：将预编译二进制放入 bin/<platform>/，模型放入 models/，SKILL.md 引用本地路径
• 反例：某个处理阶段最初要求用户自行提供模型路径，实际使用中下载失败率很高

2. subagent 不适用于跨模型场景

subagent 机制在模型切换上不可靠——配置了特定模型（如 model: kimi-for-coding）但运行时未必生效。对于需要特定模型能力的场景（如视觉分析），独立进程调用比 subagent 更可靠。

• 做法：需要特定模型时，走独立进程调用（显式指定 --model）
• subagent 适用场景：纯文本处理、不依赖特定模型的任务

3. Skill 定义与脚本同步交付

SKILL.md 和可执行脚本必须在同一轮开发中完成。只有设计文档没有脚本 = 不可用的 Skill。

• 反例：image-analyzer 先有 SKILL.md，scripts 目录为空，导致调用它的上游流程无法落地
• 检查项：每个 SKILL.md 中引用的脚本路径都必须存在且可执行

4. Skill 间协作需明确 I/O 约定

两个 Skill 协作时（如 video2markdown 调用 image-analyzer），产出路径、文件格式、命名规则要在双方 SKILL.md 中对齐。

• 反例：video2markdown 期望产出到 images/frame_xxx.md，image-analyzer 默认产出到 _pipeline/，两边约定不一致
• 做法：调用方在命令中显式指定输出路径，不在 Skill 间做隐式假设