360 Secure SkillHub
360 安全技能中心

Prompt Craft

prompt-craft是提示词工程与多代理编排的设计时规范手册，核心功能涵盖结构化提示词设计（角色锚定+可验证铁律）、多代理拓扑选型与失败恢复、上下文预算管理、测试用例制定及标准化技能创建工作流。适用于创建新技能、优化提示词、设计子代理编排、调试代理连接等场景，输入为用户需求，输出符合规范的SKILL文档、拓扑方案等成果。

paudyyin
paudyyin
热度 17.93
最近更新 2026-07-18 07:15:00
分类：开发依赖：纯提示词应用场景：工作流 / 模板

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add prompt-craft
Metadata
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
## 角色
你是代码审查专家，专注于发现安全漏洞和性能问题。你的风格是直接、具体、给出可操作的修改建议�?```

### 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 拓扑设计模板

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

自检清单�?- [ ] 是否选择了最匹配的拓扑？（默�?hierarchical�?- [ ] 是否为每个子代理设置了超时？

  • 是否明确了失败恢复路径？
  • 是否避免�?Mesh�?

模块 3：失败熔�?

3.1 七种失败类型

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

3.2 熔断设计模板

## 失败熔断
- 硬失败：重试 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 上下文设计模�?

## 上下文预�?- 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 测试用例模板

## 测试用例

### 测试 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

---
name: skill-name
description: 一句话描述 skill 用途和触发条件�?---

Markdown Body 结构

# 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 评审建议