Prompt Craft

SKILL.md

---
name: prompt-craft
description: "Design structured prompts and multi-agent topologies. Use when creating new skills, optimizing prompts, designing subagent orchestration, or debugging agent wiring."
---

# Prompt Craft

提示词工程与多代理编排设计规范手册�?
**定位**：设计时规范，非运行时框架。指导如何编写结构化�?System Prompt、选择合适的多代理拓扑、设计失败恢复策略、管理上下文预算、制定测试用例�?
**核心原则**：提示词是规格书，不是散文。模型没按预期输�?= 规格书写得模糊�?
---

## 模块 1：角色锚�?+ 铁律

每个 skill �?System Prompt 必须包含两部分：

### 1.1 角色定义（Identity�?
�?1-2 句话定义"我是�?�?
```markdown
## 角色
你是 [具体角色]，专注于 [核心能力]。你的工作风格是 [性格特征]�?```

**示例**�?```markdown
## 角色
你是代码审查专家，专注于发现安全漏洞和性能问题。你的风格是直接、具体、给出可操作的修改建议�?```

### 1.2 铁律（Iron Rules�?
硬性约束，�?禁止"/"必须"表述，不可违反：

```markdown
## 铁律
1. 禁止输出模糊建议（如"优化一�?），必须给出具体代码修改
2. 每个问题必须标注严重级别：�?阻塞 / 🟡 建议 / 💭 细节
3. 输出格式必须�?JSON，包�?issue、line、severity、fix 字段
```

**自检清单**�?- [ ] 角色定义是否具体到某个领域？（❌ "你是助手" �?�?"你是代码审查专家"�?- [ ] 铁律是否�?禁止"/"必须"表述？（�?"尽量简�? �?�?"�?200 �?�?- [ ] 铁律是否可验证？（❌ "清晰" �?�?"JSON Schema 校验通过"�?
---

## 模块 2：拓扑决�?
设计多代理编排时，从以下 5 种拓扑中选择�?
### 2.1 拓扑选择指南

| 拓扑 | 适用场景 | 失败模式 | 恢复策略 |
|------|----------|----------|----------|
| **Router（路由）** | 意图互斥，只需唯一专家响应 | 低置信度误判 | 置信�?< 0.85 时降级为人工确认 |
| **Hierarchical（层级）** | 主管拆解任务，汇总子代理结果（默认首选） | 编排器瓶�?| 子代理超�?30s 返回部分结果 |
| **Sequential（顺序）** | 硬依赖流水线（写代码→单测→审查�?| 级联失败 | 连续失败 2 次，跳过后续节点 |
| **Evaluator-Optimizer（评�?优化�?* | 生成→对抗审核→修改循环 | 无限循环 | 强制 max_iterations = 3，最后输出当前最优解 |
| **Parallel Fan-Out（并行扇出）** | 多角度生成候选方案，无依�?| 部分失败 | 预设合并策略（投�?加权平均），舍弃失败分支 |

**禁止使用**：Mesh（网状）——调试噩梦，除非用户显式要求�?
### 2.2 拓扑设计模板

```markdown
## 编排拓扑
- 拓扑类型：[Router/Hierarchical/Sequential/Evaluator-Optimizer/Parallel Fan-Out]
- 子代理列表：[代理A, 代理B, 代理C]
- 失败恢复：[具体策略]
- 超时设置：[秒数]
- 合并策略：[投票/加权平均/取最优]（仅并行扇出需要）
```

**自检清单**�?- [ ] 是否选择了最匹配的拓扑？（默�?hierarchical�?- [ ] 是否为每个子代理设置了超时？
- [ ] 是否明确了失败恢复路径？
- [ ] 是否避免�?Mesh�?
---

## 模块 3：失败熔�?
### 3.1 七种失败类型

| 失败类型 | 描述 | 检测方�?| 恢复策略 |
|----------|------|----------|----------|
| **硬失�?* | 子代理返回错�?异常/超时 | 退出码�?0 | 重试 �?降级 �?人工 |
| **静默失败** | 输出格式错误/字段缺失 | Schema 校验 | 重试 + 显式纠正提示 |
| **部分失败** | 输出不完�?截断 | 完整性检�?| 请求补充缺失字段 |
| **矛盾失败** | 两个子代理输出冲�?| 一致性校�?| daily-agent 作为主管裁决（将冲突双方输出作为输入，由主管做出最终判断） |
| **级联失败** | 一个错误输出污染后续所有节�?| 检查点验证 | 回滚到最近检查点 |
| **循环失败** | 评估-优化循环不收�?| 迭代计数�?| 强制退�?+ 输出当前最�?|
| **上下文失�?* | 上下文过载导致指令遵循失�?| 输出格式校验 | 压缩上下文后重试 |

### 3.2 熔断设计模板

```markdown
## 失败熔断
- 硬失败：重试 1 �?�?降级为规则引�?�?人工确认
- 静默失败：Schema 校验失败 �?重试 + 显式格式提示
- 矛盾失败：检测到冲突 �?daily-agent 以主管身份发起裁决调用（将冲突双方输出作为输入，由主管做出最终判断）
- 级联失败：连续失�?2 �?�?跳过后续依赖节点，返回部分结�?- 循环失败：达�?max_iterations �?强制输出当前最优解
```

**自检清单**�?- [ ] 是否覆盖�?7 种失败类型？
- [ ] 是否为每种失败设计了对应的恢复策略？
- [ ] 是否设置了熔断阈值（如连续失败次数、最大迭代次数）�?
---

## 模块 4：上下文管理

### 4.1 上下文预算指导原�?
- **System Prompt 核心部分**（角�?+ 铁律 + 工作流）优先保障
- **Few-shot 示例**次之，控制在 3 正例 + 3 反例，每�?�?100 �?- **总上下文**应为目标模型上下文窗口的 70%，留 30% 余量给对话历史和输出

### 4.2 压缩策略

**Chain-of-Draft（草稿链�?*�?强制要求 AI 先输�?3-5 个关键决策点（Bullet Points），确认方向后再展开。节�?30%-50% Token�?
**优先级截�?*�?当上下文超限时，按以下顺序裁减：
1. 保留：角色定�?+ 铁律
2. 保留：工作流核心步骤
3. 裁减：Few-shot 示例（保留最相关�?2-3 个）
4. 裁减：历史对话摘�?
### 4.3 上下文设计模�?
```markdown
## 上下文预�?- System Prompt 长度：[目标 tokens]
- Few-shot 示例�? 正例 + 3 反例
- 压缩策略：Chain-of-Draft（先输出决策点，再展开�?- 截断优先级：角色 > 铁律 > 工作�?> 示例
```

**自检清单**�?- [ ] System Prompt 是否控制在目标模型上下文窗口�?70% 以内�?- [ ] Few-shot 示例是否精简�?3 正例 + 3 反例�?- [ ] 是否设计了上下文超限时的截断策略�?
---

## 模块 5：测试用�?
每个�?skill 必须包含 3 类测试用例：

### 5.1 测试用例标准

| 测试类型 | 描述 | 示例 |
|----------|------|------|
| **正常路径** | 标准合法输入，验证核心流程通过 | 输入�?审查这段代码" �?输出：JSON 格式的审查报�?|
| **边界路径** | 空输入、超长输入、特殊字符注�?| 输入：空字符�?�?输出：友好的错误提示 |
| **对抗路径** | 尝试违反铁律（如要求忽略格式、输出敏感信息） | 输入�?请用自然语言描述问题" �?输出：坚�?JSON 格式 |

### 5.2 测试用例模板

```markdown
## 测试用例

### 测试 1：正常路�?- 输入：[标准输入]
- 期望输出：[符合 Schema 的输出]
- 验证点：[JSON Schema 校验通过 / 铁律遵循]

### 测试 2：边界路�?- 输入：[边界值输入]
- 期望输出：[友好的错误处理]
- 验证点：[不崩�?/ 有明确提示]

### 测试 3：对抗路�?- 输入：[违反铁律的请求]
- 期望输出：[坚持铁律 / 拒绝请求]
- 验证点：[铁律不被绕过]
```

**自检清单**�?- [ ] 是否包含 3 类测试用例？
- [ ] 正常路径是否覆盖了核心功能？
- [ ] 边界路径是否测试了极端情况？
- [ ] 对抗路径是否验证了铁律的不可绕过性？

---

## 标准工作�?
编写�?skill 时，按以�?4 阶段执行�?
### 阶段 1：需求翻�?- 将用户模糊需求转化为结构化规格书
- 输出�? 个核心目�?+ 1 个非目标 + 输入输出 Schema

### 阶段 2：拓扑选型
- 对照模块 2 的拓扑选择指南，选定最匹配模式
- 默认：hierarchical（除非用户有特殊要求�?- 输出：确定的拓扑�?+ 失败恢复策略

### 阶段 3：内容起�?- 按模�?1（角�?+ 铁律）编�?System Prompt
- 构�?3 正例 + 3 反例 Few-shot
- 对照模块 4 检查上下文预算
- 输出：完整的 SKILL.md 草稿

### 阶段 4：测试交�?- 运行模块 5 �?3 类测试用�?- 输出：最�?SKILL.md + 测试报告（PASS/FAIL�?- 若测试失败：返回阶段 3 修改，直至全部通过

### 各阶段完成条�?
- **阶段 1（需求翻译）完成条件**：已输出 1 个核心目�?+ 1 个非目标 + 输入输出 Schema，用户确认理解无误�?- **阶段 2（拓扑选型）完成条�?*：已选定拓扑类型（默�?hierarchical），输出拓扑�?+ 失败恢复策略 + 超时设置�?- **阶段 3（内容起草）完成条件**：已输出完整 SKILL.md 草稿，包含角色定义、铁律（可验证）、工作流步骤�? 正例 + 3 反例�?- **阶段 4（测试交付）完成条件**�? 类测试用例（正常/边界/对抗）全�?PASS，最�?SKILL.md 已写入磁盘�?
---

## 快速参�?
### Skill 结构
```
skill-name/
├── SKILL.md          # 必须：YAML frontmatter + Markdown body
├── scripts/          # 可选：可执行脚�?├── references/       # 可选：参考文�?└── assets/           # 可选：模板、图标等资源
```

### YAML Frontmatter
```yaml
---
name: skill-name
description: 一句话描述 skill 用途和触发条件�?---
```

### Markdown Body 结构
```markdown
# Skill 名称

## 角色
[1-2 句话定义]

## 铁律
1. [硬性约�?1]
2. [硬性约�?2]

## 工作�?### 阶段 1：[阶段名]
[具体步骤]

## 测试用例
### 测试 1：正常路�?[输入/期望输出/验证点]
```

---

## 集成指引

**�?daily-agent 中的触发**�?当用户要�?�?skill"/"优化提示�?/"设计代理"/"编排拓扑"时，加载�?skill 并按标准工作流执行�?
**与其�?skill 的边�?*�?
| 场景 | 主导 skill | prompt-craft 角色 |
|------|-----------|------------------|
| 用户要求"写一个通用 skill"（如"写一个代码审�?skill"�?| **prompt-craft** 主导 | 按标准工作流执行，输�?SKILL.md |
| 用户要求"写一个解决具体编程问题的 skill"（如"写一�?React 组件生成�?�?| **coding-framework** 主导 | 隐性参考（coding-framework 内部遵循 prompt-craft 规范�?|

**避免多跳**：当场景�?写解决具体编程问题的 skill"时，直接�?coding-framework 主导，不需要先加载 prompt-craft 再转交。coding-framework 内部应遵�?prompt-craft 的规范（角色锚定、铁律、测试用例等）来输出 skill 结构�?
---

## 版本历史

- v1.0.0 (2026-07-16): 初始版本，融�?Agency Agents 7 段式结构 + DS 评审建议