baijunjie Skill 编写规范
Skill 是给 agent 的规则，不是操作手册。写多了限制它发挥，写少了它做错。 判据只有一条：agent 自己推不出来的，才写。
只写这些
- 反直觉的事实、隐蔽的前提、容易踩空的判定条件
- 必须遵守的硬约束
- 判断标准与取舍原则
不写这些
- 指向代码的引用 —— 不写「见
xxx.ts」「照xxx目录的写法」这类让 agent 去翻代码的指引。 需要的知识直接写进正文。skill 必须自包含，脱离任何仓库的当前状态都成立。 - 其它 skill 的名字 —— 默认不写，每个 skill 都要能单独安装、单独工作。需要提到别处的规范时， 写成能力或约定本身（「项目有自己的文档规范时按它的」），不点名是哪个 skill。 用户明确要求把两个 skill 串成链路时才可以点名；安装器 skill 提到它自己安装的那份不在此列。
- 副作用与已知缺陷 —— 只写怎么做。工具的 bug、环境的怪癖将来可能被修掉， 写进 skill 只会过期并误导。
- agent 从工具输出、报错信息、常识就能得到的内容——包括它自己有哪些工具、能力边界在哪
- 别处已有规范的复述
- 铺陈式解释（「理由很直接…」「这是最常见的失误…」）—— 规则本身说清了就不解释
- 单次任务里的特例、具体变量名、示例代码片段
写法
- 步骤只留动作，判断留给 agent。 不要把一次成功的操作过程逐步固化成脚本。
- 一条规则一行。有条件分支用表格，不用段落。
- 用祈使句写死约束：「必须」「不要」「先…再…」。不用「建议」「可以考虑」。
description写清做什么 + 什么时候用 + 触发关键词，模型靠它决定是否自动调用。- 双宿主 skill 的通用 frontmatter 只依赖
name与description；宿主专属能力放各自的元数据文件， 不把 Claude Code 或 Codex 的工具名、路径和调用语法写成另一端也必须支持的前提。 - 需要禁止隐式调用时，Claude Code 使用
disable-model-invocation: true，Codex 同时在agents/openai.yaml设置policy.allow_implicit_invocation: false。发布到 OpenAI 公共目录前， 另行生成不含 Claude 专属 frontmatter 的 Codex 包；不要为通过校验而悄悄放开 Claude Code 的隐式调用。 - 附带资源优先从
PLUGIN_ROOT定位，回退CLAUDE_PLUGIN_ROOT；两者都没有时按当前SKILL.md的绝对路径定位，不能假定进程工作目录就是 plugin 根目录。 - 篇幅是信号。明显变长通常意味着混进了上面「不写这些」里的东西，回头砍。
自检
写完逐条问：
- 这条 agent 自己想不到吗？想得到就删。
- 这条脱离当前仓库还成立吗？不成立说明它是代码引用或临时缺陷。
- 这条是在给判断标准，还是在替 agent 做决定？后者放宽。