# 写作手艺——description 与正文

Skill 的两个加载层各有各的写法：description 决定被不被触发，正文决定触发后好不好执行。

## description：唯一的自动触发信号

各 runtime（ZCode / Claude Code / Codex）都靠 frontmatter 的 `description` 决定何时加载 skill（连同 `name` 常驻上下文）。模型倾向于**漏触发**而不是误触发，所以 description 要写得主动一点。

**四件必须写进去的事：**

1. **做什么**：一句话职责。
2. **何时触发**：用户真实会说的话——"帮我做个 skill""把这个流程沉淀下来""给我的 skill 做体检"。给 3–8 条原话级别的触发词。
3. **负触发**：明确"不要用于……"的相邻请求。没有负触发的 description 会在边界请求上犹豫。
4. **丢来就触发**的说明：用户丢来 SKILL.md、目录、链接说"帮我看看"时该不该接。

**写法检查：**

- 用中英混合的真实口语测试：拿 5 条用户会说的原话（含 2 条不该触发的）逐条对照 description，每条都该能明确判出触发/不触发。
- 别写成功能清单（"支持 A、B、C"），写成场景句（"当用户想……时使用"）。
- 长度：3–8 行。太短盖不住场景，太长稀释信号。

## 正文：给模型的操作手册

正文只在触发后加载，目标是让模型照着执行，而不是让人读了佩服。

**七条手艺：**

1. **祈使句**。"读取文件后再编辑"，不是"你应该考虑读取文件"。
2. **讲为什么**。规则不明显时给理由——模型理解了原因才会在边界情况做对判断。发现自己在写全大写 MUST 时，通常说明该把理由讲清楚，而不是加重语气。
3. **示例胜过规则**。要求结构化输出就贴一个字面示例；要求调某工具就给调用样例。一段示例顶三条规则。
4. **正文 ≤500 行**。超了就把领域细节拆进 references，正文里留一句"做 X 前先读 references/x.md"。
5. **每节一个职责**。读者跳着读不迷路。
6. **失败模式要编码**。"遇到 X 时停下来问用户"比"小心行事"有用得多。
7. **写完删一遍**。删掉不承重的句子。规则越少，剩下的越有权威。

## 跨 runtime 约定（ZCode / Claude Code / Codex）

Skill 遵循 Agent Skills 开放格式：一个目录 + `SKILL.md`（frontmatter：`name` + `description`）。三个 runtime 都认这个格式，差别只在发现路径：

| runtime | 项目级 | 用户级 |
|---|---|---|
| ZCode | `.zcode/skills/`（优先）· `.agents/skills/` | `~/.zcode/skills/` · `~/.agents/skills/` |
| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
| Codex | `.codex/skills/` | `~/.codex/skills/`（实验性） |

- **frontmatter**：`name`（kebab-case，1–64 字符，必须与目录名一致）+ `description` 是必填；其余保留字段按需。
- **新建默认放 `.agents/skills/`**——跨工具标准位；目标 runtime 不读这个位置时，复制或软链到它的目录（一份源，多处入口，改完同步）。
- **目录即身份**：同名 skill 不同路径算两个安装，ZCode 里路径优先级高的胜出——起名字前先查各 runtime 的发现路径有没有撞名。
- **可移植三禁**：正文不写死某个 runtime 专属的工具名/技能名（如把"配置排障"指给单一 runtime 的指南）；不用私有绝对路径；脚本只用 python3/bash 标准库。做到这三条，同一个目录在三个 runtime 里行为一致。
- **先例研究时的提示**：搜 Claude 生态的 skill（数量最多）借鉴机制没问题，但安装路径、触发语法要按目标 runtime 换算，不要照搬。

## 命名

- 英文 kebab-case，≤3 个连字符段为佳：`weekly-report`、`api-docs-lint`。
- 名字要能自解释职责；人设名（如 `luban`）只有配合强 description 才可用。
- 与已有 skill 撞名 = 改名，不是覆盖。