skill-authoring

技能编写 — easy-cheese 约定

本文档将 easy-cheese 的技能编写规则规范化，内容取自 obra/superpowers（CSO 原则、压力测试门槛）和 Matt Pocock 的技能仓库（大小预算、编写检查清单）。这是任何人添加或修订技能时应遵循的权威参考。

---

描述规则（CSO）

描述是模型在选择技能时，运行框架展示给它的唯一内容。优化描述时应以触发为目标，而非解释。

**规则：**第 1 句说明能力；第 2 句采用“在 [触发条件] 时使用”的格式。不要概述工作流、描述其在流程中的位置，也不要列出功能。

理由：概述技能工作流的描述会为模型提供一条捷径，让它不读 SKILL.md 正文就直接采用该技能。于是，技能会悄然退化为其自身的一行描述。

约束：

• 最多 1024 个字符（Codex 会拒绝更长的描述）。
• 使用第三人称、现在时。
• 触发条件应包含用户可能会说的具体短语。

**测试：**删去描述，然后问：仅凭这些文字，模型能否从所有其他技能中选出这个技能？如果不能，说明缺少触发条件。

---

大小预算

保持 SKILL.md 正文精简。目标是让模型能够一遍读完正文而不失去思路。

预算：SKILL.md 正文估算为 3,600 个 token（不含 frontmatter）。按本仓库测得的文本密度计算，大约相当于 150 行；但受限单位是 token，而非行数——在文本密集的情况下，行数会造成误导：本仓库的 16 个技能都符合 Anthropic 的 500 行规则，但其中 8 个技能的正文超过了我们的 3,600-token 预算。

**执行方式：**CI 以仅允许缩减的方式执行这一限制 — .github/scripts/validate_skills.py，基准值记录在 .github/skill-budgets.json 中，通过 just update-skill-budgets 重新生成。 在该限制引入时已超出预算的技能，以记录值为祖父条款基准，此后只能缩减；处于或低于预算的技能必须保持在 3,600 以下。

Anthropic 公布的 Level-2 数值为 500 行 / 少于 5k token。 easy-cheese 有意将限制设得比该上限更严格。

实用预算：

• 将辅助细节——分步子协议、参考表、提示词模板、大型示例——移入命名明确的 references/*.md 文件。 SKILL.md 正文应指向这些文件，而不是重复其中的内容。
• references/ 目录适合存放：冗长的合理化理由表、输出格式模板、详细的子协议步骤、图表约定。
• 只有当 SKILL.md 说明了何时阅读参考文件时，拆分才有帮助。 参考文件只有在正文明确链接到它时才会加载——不加指引就将正文移入 references/，只是把 token 移出可见预算，并没有将其推迟到模型后续阅读。

**异味测试：**如果 SKILL.md 正文已经长到 Flow 部分被一大段 Inputs 部分和三张标志表格压在下面，就该进行拆分了。

来源：该预算最初改编自 Matt Pocock 为其技能仓库设定的 <100 行上限，之后根据本仓库测得的文本密度重新表述为 token 数。

---

纪律章节

纪律型技能（用于强制执行流程，而不仅是解释技巧的技能）应在 SKILL.md 正文中通过 ## Discipline 章节说明规则；如果正文已达到预算，则应将其放在 references/<skill>-discipline.md 辅助文件中。

章节应保持简短。用一句话说明规则，列出即将违反规则的可观察信号，并指出必须采取的行动。只有在实践中观察到相关自我辩解时，才添加反驳表。

编写审核清单

技能发布前，请确认：

• 包含触发语。 描述中列出了用户可能会说的具体短语（而非能力介绍）。
• 不含时效性信息。 技能正文不得包含可能过时的版本号、带日期的定价或 API 端点。请改为指向文档。
• 包含具体示例。 至少提供一个完整示例，可放在正文中，也可放在 references/ 文件中。
• 参考资料只深入一层。 SKILL.md 正文指向 references/*.md 文件；这些文件不会再通过 Markdown 链接指向各自的子参考资料。以 head 方式只读取参考文件的一部分，可能会悄然漏掉隐藏在第二跳中的内容。若某个参考文件本身也被 SKILL.md 链接，那么指向该文件的链接属于横向引用，而非第二跳，符合要求。
• 规范说明简短。 设定门槛或循环流程的技能，应在几行内说明规则、即将违反规则的信号，以及必须采取的行动。
• 双重列出。 技能目录必须出现在 .claude-plugin/plugin.json 的 skills 数组中。CI 检查 tests/python/test_plugin_manifest.py::test_claude_plugin_manifest_matches_top_level_skills 会强制执行此要求。

---

先进行压力测试的编写门槛

规则：技能发布前，必须先运行一次未通过基线测试的子 Agent。

编写新的技能正文前：

1. 构造一个有代表性的压力场景——描述技能旨在改进的任务的提示词。
2. 在未启用该技能的情况下，让子 Agent 处理该场景。将输出保存为基线。
3. 找出具体问题：子 Agent 做错了什么、遗漏了什么，或对任务的理解有何偏差？
4. 编写技能正文，针对这一具体问题进行改进。
5. 启用该技能后重新运行子 Agent，并确认问题已得到纠正。

如果技能正文从未针对未通过的基线进行测试，它可能会解决模型实际并不存在的问题，也可能描述模型在没有提示时就已经遵循的工作流。

---

disable-model-invocation frontmatter（候选项——尚未应用）

Matt Pocock 的技能仓库在纯提示词技能（无需再次提示模型即可立即执行的技能）的 frontmatter 中使用 disable-model-invocation: true。Claude Code frontmatter 验证器（.github/scripts/validate_skills.py）已允许使用此键。

**状态：**候选项待验证运行环境。运行环境行为得到确认前，不要将其应用于任何 easy-cheese 技能：确认设置此键后运行环境会如何处理，以及是否符合预期的“立即执行”语义。应用前，请在此记录验证结果。