Leroy
d3e9bd45bd
- SKILL.md 双工作流（创建/迭代）+ 两道门（验料/通用化）+ 三档位 - 7 篇方法论 references + 3 个纯标准库脚本（scaffold/validate/trigger_eval） - 自身触发用例 16 条 + 先例研究/创建/迭代证据报告 - 方法论吸收自 qiaomu-meta-skill 与 luban-skill，取舍见 reports/prior-art.md
57 lines
3.9 KiB
Markdown
57 lines
3.9 KiB
Markdown
# 写作手艺——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 撞名 = 改名，不是覆盖。
|