skill写作规范
源自agent-browser/browser-use三方包对照精华（2026-08-23）与既有迭代标准合并。一句话总纲：文档跟版本走、动作前先探测、失败有剧本、高危必确认、长度做减法。
五条核心原则
- 文档指针化（discovery stub）：skill有可执行宿主（CLI/脚本/API）时，SKILL.md只写触发词+环境探测+指针（如
agent-browser skills get core式命令），操作细节由宿主按已装版本实时供出；无宿主的skill才写全操作细节。防文档与版本漂移。 - 先探测后行动：正式动作前先拿环境快照（浏览器场景=先read_page拿ref再form_input；数据场景=先验证API可达再取数）。skill须写明探测步骤。
- 等待=轮询+验证：异步/加载场景禁盲sleep，用「轮询读状态→验证结果→再动作」；关键动作后必验证行为（改文案≠改机制，报done前看实现）。
- 失败有剧本：每个skill必备故障剧本节——常见失败模式+第一步恢复动作（如：会话坏了先关再重开；元素找不到先滚屏再重新快照）。
- 高危动作须确认：能力边界表加「高危动作」列——cookie导出、云同步、公网暴露、账号变更、文件覆盖类动作，执行前须用户确认，不得混在普通流程里无标注。
SKILL.md标准结构（按序）
frontmatter（name/description含触发词与排除区/version）→ 环境探测 → 核心流程 → 能力边界表（含高危动作列）→ FAQ/故障剧本 → 自检清单。模板类skill另附templates/。
长度纪律（防形式工程）
编号硬规则、阶段门控、evals.json等形式无实质的不学；SKILL.md不是越长越强，每节须能答「删了会坏什么」；反例黑名单好过空泛建议；质量标记类规范优先吸收外部已验证做法（如〔A/D/E〕数据质量分级）。
升版与同步流程
改SKILL.md+模板→升版本号（语义化，只加不改）→同步桌面副本（Desktop\同名目录）→md5sum三处（本机skills/桌面/备份）校验一致并向用户报告结果。
Pitfalls
- 操作细节写死在SKILL.md里，宿主升级后文档stale（应指针化）
- 高危动作混在普通流程里没有标出
- FAQ写成形式工程（凑条数、无第一步恢复动作）
- 触发词太宽导致误触发（须写排除区，description里说明不管什么）
- 升级只改了本机忘了桌面副本，三处失同步
自检清单（交付前）
□ description含触发词与排除区 □ 有环境探测 □ 高危动作已标注 □ 有故障剧本 □ 每节通过「删了会坏什么」测试 □ 升版后三处md5一致并报告
适用边界
管skill的写法与升级流程；不管安装决策（skill-gatekeeper六维门禁负责）、不管经验沉淀与记忆瘦身（self-evolving负责）、不管create-skill工具的格式操作细节（互补：create-skill管格式，本skill管写作纪律）。
