SKILL 编写指南

围绕 SKILL.md 的结构化写法，让智能体稳定触发、可组合、可维护。

一份好的技能文件应让「第一次用的人」和「六个月后的维护者」都能快速理解：前半部分回答「是什么、何时用」，后半部分回答「具体怎么做、怎样算完成」。命名与描述尽量与仓库内真实目录、CI 任务名一致，减少检索与自动化对接时的歧义。

使用 name、description 等字段声明技能标识与一句话触发案例，便于 Agent 检索与匹配。

正文用清晰步骤列出操作顺序，并写明完成标准，减少模型自由发挥带来的偏差。

说明不适用情况、常见误区或禁止行为，帮助 Agent 在复杂情况下正确拒答或降级。

可选标注 Cursor、Codex、MCP 或模型偏好，让使用者快速判断是否适用于当前流水线。

需要用户替换的内容用统一占位符（如 <REPO_ROOT>），并在文末列出「填写说明」。避免在步骤中留空泛的「请自行判断」。

破坏性变更时在正文顶部注明迁移说明；若技能依赖外部 API，写明最低版本或弃用日期。