smart
67837df8d0
- 新增全套考试卷、评估卷、参考答案与考试培训包模板 - 修正slidev培训课件：调整模块标题、链路图缩放，替换工单示例为通用业务对象 - 修正课堂红线表述为证据红线，将小组作业调整为个人作业要求 - 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块 - 整理AI工程技能交付包，迁移旧资产至客户专属交付包并统一术语 - 新增考试输出模板与TRAE使用记录文档
138 lines
5.9 KiB
Markdown
138 lines
5.9 KiB
Markdown
# 模块 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。
|
||
-->
|