技能设计指南

要解决的问题

很多技能能跑，但结构是「拍脑袋」出来的：一个 SKILL.md 塞了十几种职责，步骤全交给 LLM 现想，references 一次性塞进上下文。表现是触发不准、输出格式漂移、改一处动全身。这份指南处理的不是「怎么写一个技能文件」，而是这些设计决策背后的 WHY——什么时候该用 Workflow 而不是 Agent，为什么要把脑和手拆开。

它怎么工作

核心是四条不可违反的硬规则：

• 简洁优先：先写单个 SKILL.md，只有更简单的方案确实失效时才加复杂度
• 脑不等于手：决策写在 SKILL.md，确定性执行交给 scripts/，绝不混在一起
• 不全量预载：references/ 按需加载，不一次性倒进上下文
• 必备字段：触发条件、[Deterministic]/[LLM] 标注、Hard Rules、Failure Handling、Output Format

在此基础上，技能按四个阶段推进：

1. 判断 Workflow 还是 Agent——只问一个问题：步骤是否预先确定？绝大多数场景是 Workflow
2. 选模式：Prompt Chaining、Routing、Parallelization、Orchestrator-Workers、Evaluator-Optimizer 五种
3. 搭结构：SKILL.md 必需，references/、scripts/、assets/ 可选
4. 过检查清单：结构、原则、工具、护栏、可观测性五个维度

它还有一个关键判断：技能的主要读者是 Agent 运行时，不是逛市场的人。所以 description 要写成精确的能力声明，not_for 是核心路由字段——一次误触发比一次漏触发代价更大。

适用边界

• 它回答 WHY，不回答怎么写 SKILL.md 的 HOW，后者请用 skill-creator
• 需要代码实现而非设计时，会被转走
• 设计完成后的发布审计与推送，属于 skill-publish 的职责
• 模式比较有歧义时，需按需加载 references/pattern-details.md
• 反模式清单（God Skill、All-LLM、无护栏、输出模糊）适用于所有新建技能，不只是本指南产出的

一句话：它适合已经能跑但想变干净、或者想从第一行就按正确约束来写的技能设计场景。