# 模块 5：Skill 的难点是决策边界

<div class="mt-6 text-sm">

Skill 的价值不在于堆叠说明，而在于把任务拆成可核对的输入条件、决策顺序、交接结果和停止边界。

只有这些边界被显式定义，复杂任务才能在不同项目事实下保持可控。

</div>

<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">输入条件</div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">决策顺序</div>
<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">交接结果</div>
<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">停止边界</div>
</div>

<!--
逐字稿：Skill 的难点不是把步骤写得很长，而是把一次复杂任务的决策边界拆清楚。它要明确输入是否齐全、判断按什么顺序进行、结果交给谁，以及在哪些情况下必须停止。只有这四件事稳定，Skill 才能跨任务复用而不失控。

这一模块使用交付包中真实的 Skill 目录结构，重点是解释每类文件如何承接判断、输入、输出和验证，而不是记住固定目录。
-->

---

# 一个真实 Skill 包如何按职责拆开

<div class="mt-5 text-xs">

```text
skill-name/
├── SKILL.md                 # 触发条件、输入、工作流、输出与门禁
├── agents/
│   └── openai.yaml          # 展示名、简介与默认触发提示
├── assets/
│   ├── 生成.prompt.md       # 可复用任务 Prompt
│   ├── 检查清单.md           # 固定遗漏点
│   └── 报告.template.md      # 结构化输出模板
├── references/              # 稳定背景知识与兼容性说明
└── scripts/                 # 可重复执行的机械检查
```

</div>

<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
`SKILL.md` 负责决策和编排；模板、检查单、参考资料和脚本各自承担单一职责，避免同一约束出现多个版本。
</div>

<!--
逐字稿：这个目录不是必须照抄的模板，而是一种职责拆分方式。`SKILL.md` 保存判断和编排，检查单保存固定遗漏点，模板保存输出结构，参考资料保存稳定背景，脚本保存机械检查。把它们全部堆进一个文件，后续更新时就很难判断哪一份是权威来源。

这个目录来自当前工程 Skill 交付包，例如 project-knowledge-builder、generate-project-constraints 与 track-review-fix-loop。并非所有 Skill 都需要全部子目录，但不应把每类内容都堆进 SKILL.md。
-->

---

# SKILL.md 的核心结构

<div class="mt-5 text-xs">

```md
---
name: state-change-safety
description: 当任务涉及业务状态写入、资源占用或释放时使用。
---

## Inputs
变更目标、相关源码、状态规则、测试或 diff、项目约束。

## Workflow
提取事实 -> 判断状态与副作用 -> 比较候选方案 -> 生成验证清单。

## Output Contract
事实表、影响链路、最小改动建议、验证项、待确认事项。

## Stop Conditions
证据不足、规则冲突、范围越界或关键验证失败时停止并说明原因。
```

</div>

<!--
逐字稿：`SKILL.md` 的核心不是说明文字，而是四个契约。Inputs 说明需要什么证据，Workflow 说明判断顺序，Output Contract 说明交付格式，Stop Conditions 说明什么情况下不能继续。缺少停止条件的 Skill 很容易在证据不足时继续生成看似完整的答案。

Frontmatter 决定 Agent 能否发现和触发 Skill；正文决定它读什么、怎么判断和交付什么。真正的 Skill 必须有 Stop Conditions，否则模型遇到证据缺口时容易继续编造。
-->

---

# agent 配置只解决“如何被发现”

<div class="mt-5 text-xs">

```yaml
interface:
  display_name: "状态变更安全审查"
  short_description: "分析状态写入、资源副作用与验证边界"
  default_prompt: "Use $state-change-safety to review this change."

policy:
  allow_implicit_invocation: true
```

</div>

<div class="mt-6 grid grid-cols-2 gap-3 text-sm">
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">配置文件：让 Agent 找得到</div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">SKILL.md：让 Agent 做得对</div>
</div>

<!--
逐字稿：这里要区分发现层和执行层。agent 配置只帮助系统识别 Skill 的名称、简介和触发入口，不负责承载业务流程。真正的判断、输入要求和停止边界仍然在 `SKILL.md` 中，这样展示配置变化时不会误伤业务工作流。

agents/openai.yaml 的真实格式包含 display_name、short_description、default_prompt 与 allow_implicit_invocation。它是发现层，不应复制业务工作流；工作流仍放在 SKILL.md 中。
-->

---

# 什么不该做成 Skill？

<div class="mt-5 text-xs">

| 情况 | 更合适的资产 | 原因 |
|---|---|---|
| 只有一条永远成立的约束 | Rule | 没有多步决策必要 |
| 只需固定格式生成一段内容 | Prompt 或 Command | 不需要上下文编排 |
| 只检查五个固定项目 | Checklist | 不需要 Agent 主动分析 |
| 只有一个项目的临时异常 | 任务记录或 Example | 复用价值不足 |
| 需要读取、判断、生成、验证并输出结构化结果 | Skill | 需要多个资产协同 |

</div>

<!--
逐字稿：不要因为任务复杂就一律创建 Skill。只有一条长期约束时用 Rule，固定格式输出时用任务上下文契约或 Command，少量固定检查时用 Checklist。只有任务同时需要读取证据、做多步判断、组织验证并输出结构化结果时，Skill 才能真正降低重复成本。

Skill 过度膨胀会造成触发不准、维护困难和上下文浪费。只有当任务确实存在多步判断和明确交付契约时，才值得封装为 Skill。
-->