skill-authoring

Skill 编写

通过渐进式披露、明确的上下文指引、可检查的完成标准和单一事实来源，创建行为可预测的 Agent Skills。

原则

• 每个触发短语对应一个 skill。 一个 skill 只认领用户会说的一件事。两个 skill 若会响应同一句话，就应该合并为一个；一个 skill 若会响应几句互不相关的话，就应该拆分为多个。
• 按动词拆分，绝不按名词拆分。 动词负责路由；名词容易冲突。create 和 refine 是两个 skill。Feature、Epic 和 Story 则属于一个 skill，由它推断类型，因为用户往往不知道自己需要哪种。
• 按误路由的代价权衡拆分。 误路由会导致错误的 写入 时就合并；会导致明显的错误 回答 时就拆分。只读误路由会立即显现；错误的修改则不会。
• 需要用子命令消除歧义的 skill，应该拆成两个 skill。 如果正文一开始就询问用户想要哪种模式，路由器就应该已经做出判断。
• 将每个分支都会执行的步骤放在 SKILL.md 中；仅适用于特定分支的参考内容，应通过说明何时阅读的指引链接提供。
• 参考资料保持一层深度，并且可独立使用。
• 描述控制在 1024 个字符以内，skill 正文控制在 500 行以内。正文限制仅适用于 SKILL.md——也要统计整个目录，并思考行数统计所暗示的问题：调用者必须学习哪些词汇？ 一个触发短语只会让调用者接触一套词汇。这个包中有两个 skill 的总行数分别达到 4,029 行和 7,784 行，但它们的 SKILL.md 文件仍远低于限制。
• 将确定性验证和转换逻辑放入脚本。

重复

应按层级而非数量来判断。

禁止重复提示词。 如果相同的指令、协议或领域规则会出现在两个 skill 中：若没有现有归属，就提取为参考 skill；若已有模块负责，就执行现有接口；若它是规则而非能力，就只记录一次。两个调用者是提取的门槛；只有一个调用者时，内容应归属于其所属 skill。

预期会有代码重复。 随附脚本应自包含，以便 skill 可以单独安装。应复制辅助工具，而不是跨越边界调用。

Agent 在运行时、无论身处哪个仓库都需要遵循的规则，必须放在 skill 中。仓库自身的 AGENTS.md、决策记录和术语表只约束该仓库中的工作，安装 skill 时不会一同带上——因此，引用这些内容的 skill 对所有安装者而言都是不完整的。

命名

名称应描述主题。按领域再加动词命名，与 skill 认领的触发短语保持一致：<domain>-create、<domain>-review。同系列 skill 对同一事物应使用相同词语。

先问 skill 讲的是什么，再据此命名。若 skill 讲的是某个产品或系统，就使用该产品的名称；若确实是通用 skill，即使与特定产品的 skill 一同发布，也应使用通用名称。夸大适用范围的前缀不如没有——它会让人误以为 skill 具备实际并不具备的知识。

名称是供人阅读的，呈现在一个扁平列表中，文件夹结构已不可见。路由是另一个问题，应通过描述来解决：保留字面上的专有名词——项目键、仓库名称、文件名、工具名、示例标识符——因为字面标记是最有力的定位锚点。

锚点的作用取决于它是否出现，因此绝不要为了声明某个字面标记不适用，而在描述中写入它。“像 ABC-123 这样的键不是 sprint”会让该 skill 成为它明确拒绝处理的请求的候选项。应不带该标记地说明适用范围：“适用于团队和看板，绝不处理单个 issue 键”。

在宿主仓库中工作

设计技能前，先阅读仓库说明的规范——通常包括 AGENTS.md、术语表和决策记录。这些规范约束你即将编写的技能。安装技能后，它们不再约束该技能，因此你写入技能的内容不得依赖于能够读取这些规范。

如果仓库发布了一组技能，请预期其中会规定：哪些技能由人工调用、是否适用名称前缀、技能如何组合、成员清单位于何处，以及测试会检查哪些内容。遵循这些规定。

面试依赖

创建技能或面试技能相关需求时，需要先使用面试技能，在起草前对范围进行严格检验——本集合中的 /grilling。如果宿主无法通过名称调用它，请在开始起草前停止，并说明创建工作必须先满足此条件。除非要开展面试，否则审计和整合无需使用该技能。

条件式参考资料

只加载一个分支。该分支自身会指出后续所需的规范、说明、架构、脚本或质量参考资料。

• 阅读 references/create.md，从头开始面试、起草并审查新技能——“创建技能”、“起草 SKILL.md”、“打包这项专业知识”。
• 阅读 references/audit.md，审查、修复或诊断现有技能——“为什么它从不触发”、“检查这个 SKILL.md”、“改进此技能”。
• 阅读 references/consolidation-guide.md，将重叠的技能合并为更少的技能，或检查合并是否过度。通过 references/create.md 中的第 5 阶段审查完成流程。

完成条件

选定分支的审查清单全部通过、所有引用的资源均可访问、不再有旧技能名称下重复的行为，并且每个已更改的 .py 文件均通过宿主代码检查工具，工作才算完成。