Leroy
d3e9bd45bd
- SKILL.md 双工作流（创建/迭代）+ 两道门（验料/通用化）+ 三档位 - 7 篇方法论 references + 3 个纯标准库脚本（scaffold/validate/trigger_eval） - 自身触发用例 16 条 + 先例研究/创建/迭代证据报告 - 方法论吸收自 qiaomu-meta-skill 与 luban-skill，取舍见 reports/prior-art.md
3.9 KiB
3.9 KiB
写作手艺——description 与正文
Skill 的两个加载层各有各的写法：description 决定被不被触发，正文决定触发后好不好执行。
description：唯一的自动触发信号
各 runtime（ZCode / Claude Code / Codex）都靠 frontmatter 的 description 决定何时加载 skill（连同 name 常驻上下文）。模型倾向于漏触发而不是误触发，所以 description 要写得主动一点。
四件必须写进去的事：
- 做什么：一句话职责。
- 何时触发：用户真实会说的话——"帮我做个 skill""把这个流程沉淀下来""给我的 skill 做体检"。给 3–8 条原话级别的触发词。
- 负触发：明确"不要用于……"的相邻请求。没有负触发的 description 会在边界请求上犹豫。
- 丢来就触发的说明：用户丢来 SKILL.md、目录、链接说"帮我看看"时该不该接。
写法检查：
- 用中英混合的真实口语测试：拿 5 条用户会说的原话（含 2 条不该触发的）逐条对照 description，每条都该能明确判出触发/不触发。
- 别写成功能清单（"支持 A、B、C"），写成场景句（"当用户想……时使用"）。
- 长度：3–8 行。太短盖不住场景，太长稀释信号。
正文：给模型的操作手册
正文只在触发后加载，目标是让模型照着执行，而不是让人读了佩服。
七条手艺：
- 祈使句。"读取文件后再编辑"，不是"你应该考虑读取文件"。
- 讲为什么。规则不明显时给理由——模型理解了原因才会在边界情况做对判断。发现自己在写全大写 MUST 时，通常说明该把理由讲清楚，而不是加重语气。
- 示例胜过规则。要求结构化输出就贴一个字面示例；要求调某工具就给调用样例。一段示例顶三条规则。
- 正文 ≤500 行。超了就把领域细节拆进 references，正文里留一句"做 X 前先读 references/x.md"。
- 每节一个职责。读者跳着读不迷路。
- 失败模式要编码。"遇到 X 时停下来问用户"比"小心行事"有用得多。
- 写完删一遍。删掉不承重的句子。规则越少，剩下的越有权威。
跨 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 撞名 = 改名，不是覆盖。