# Skill Authoring

> Skill 编写规范。创建或修改 SKILL.md 时使用。规定 skill 只写 agent 推不出来的规则、必须自包含不引用代码、给判断标准而非操作脚本。

- Skill: `baijunjie/skill-authoring` (Agent Skill)
- Install (CLI): `npx skillmds@latest add baijunjie/skill-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/baijunjie/skill-authoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: baijunjie (https://skillmd.com/u/baijunjie)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/baijunjie/skill-authoring

---


# 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 根目录。
- 篇幅是信号。明显变长通常意味着混进了上面「不写这些」里的东西，回头砍。

## 自检

写完逐条问：

1. 这条 agent 自己想不到吗？想得到就删。
2. 这条脱离当前仓库还成立吗？不成立说明它是代码引用或临时缺陷。
3. 这条是在给判断标准，还是在替 agent 做决定？后者放宽。