fable-skill-creator

Skill 创建器

创建能在压力下改变 Agent 行为的 Skill，而不是只描述良好实践的 Skill。

使命

生产级 Skill 是一份精简的操作手册，用于处理一类反复出现的决策。它应帮助 Agent 识别当前情境、在多个可行方案中做出选择、收集恰当的证据、拒绝看似诱人的捷径，并在更适合由其他专家处理时顺利交接。

仅仅通过架构验证的 SKILL.md 并不足够。只写着“检查、规划、实施、验证”的 Skill 属于文档，而非行为能力。

激活约定

当请求的工作涉及以下事项时，使用此 Skill：

• 创建新的可复用 Skill；
• 强化或重构现有 Skill；
• 提高触发准确度，或减少与相邻 Skill 的重叠；
• 添加参考资料、示例、模板、Agent 或评估；
• 将重复工作流转化为可移植的 Agent 能力；
• 证明 Skill 能在不止一个理想路径示例中正确运行。

不要将其用于常规应用变更、缺陷修复或代码库维护。这些工作应交由适当的生命周期 Skill 处理。

输入

• user_intent：要编码的能力、行为或工作流。
• workflow_trace：已观察到的决策、工具使用和故障序列（如有）。
• reference_sources：主要文档、架构、领域规则或经过验证的内部模式。

Skill 深度分类

编写前，先对能力进行分类：

类别	典型形态	所需深度
规则	单一稳定决策，分支较少	简明 Skill，边界明确
流程	多步、可重复的操作	分阶段协议 + 证据
诊断	症状对应多种可能原因	故障分类 + 证伪方法
编排器	在多个专家之间选择或委派	路由表 + 交接约定
领域专家	需要大量专业知识	深入的参考资料 + 示例 + 评估系列

如果能力属于诊断、编排器或领域专家类别，短清单通常不足以满足要求。

Skill 合约 V2

每个非简单 Skill 都必须明确回答以下问题。

1. 何时激活？

定义正向触发条件、负向触发条件、前置条件和升级条件。包括不应选择此 Skill 的相邻任务。

2. Agent 处于什么情境？

提供一个能改变行为的简要分类。例如：范围有限还是架构级、确定性还是不稳定、本地还是外部、可逆还是破坏性、已知还是不确定。

3. 必须做出哪些决策？

使用决策表或分支规则处理模糊情况。不要用“酌情处理”之类的含糊说法掩盖判断标准；应明确说明何种证据使某种做法变得合适。

4. 执行协议是什么？

为每个阶段指定：

• 目标；
• 允许的操作；
• 必需的证据；
• 退出条件；
• 停止或升级条件。

5. 可能如何失败？

列出领域特定的故障类别，以及用于区分这些类别的可观察信号。不要把所有故障都归结为“重试”或“恢复”。

6. 哪些条件绝不能被破坏？

列出在整个 Skill 执行期间必须始终成立的不变量。例如：没有有效的 RED 前，不得修改生产环境；没有注册表确认，不得声称已发布；没有具体故障模式，不得提出审查问题。

7. 哪些捷径看似诱人却无效？

记录能力较强的模型在时间紧迫或提示模糊时常会采用的反模式。

8. Skill 应交付哪些证据？

为下一位专家定义交接材料：已了解的事实、已运行的命令、已更改的产物、残余风险、未解决的问题，以及适用时的证明时效。

9. 渐进式资源应包含哪些内容？

SKILL.md 应包含决策逻辑。参考资料应补充操作层面的深度，而不是用不同措辞重复同一份检查清单。

实用的资源包括：

• 决策启发式；
• 故障诊断指南；
• 遗留/边缘情况操作手册；
• 包含权衡取舍的完整示例；
• 与工具无关的验证策略；
• 仅在检查清单编码了不显而易见的领域知识时才使用的检查清单。

10. 如何判断 Skill 是否真正有效？

创建多个语义不同的评测系列。对同一场景进行表面变化不算覆盖面广。

评测深度标准

对于非平凡的 Skill，在认为评测覆盖成熟之前，应在其套件中至少包含 6 个语义场景系列。一个系列应对应不同的决策问题，而不是对同一提示词改写五次。

应涵盖以下情形：

• 直接触发；
• 边界/不触发情形；
• 需要分类的模糊情形；
• 促使走捷径的对抗性压力；
• 不完整或相互矛盾的证据；
• 故障/恢复交接；
• 无法使用常规顺利路径的遗留或受限环境。

企业行为测试框架仍可将每个系列扩展为已知/否定/模糊/对抗/留出变体。这种扩展不能替代语义场景系列的广度。

编写流程

1. 观察实际工作：从真实工作流或一手资料中识别决策、产物、故障模式和交接。
2. 梳理相邻 Skill：明确此 Skill 负责的范围，以及它有意不处理的内容。
3. 先编写评测场景，重点关注最重要且容易出错的决策。如果无法清楚陈述预期操作，说明 Skill 合约尚未准备就绪。
4. 设计决策模型：分类、分支、不变量、停止条件。
5. 使用祈使式、与工具无关的语言编写 SKILL.md。
6. 添加渐进式资源，深入阐述那些会让主 Skill 显得冗杂的内容。
7. 添加完整示例，其中至少包含一个显而易见的首选操作其实有误的案例。
8. 创建/更新 Agent 配置档案，使面向宿主的提示词指向完整的 Skill 合约，而不是用一句话摘要取代它。
9. 验证打包内容和注册表元数据。
10. 运行确定性评测和行为评测。将 Skill/评测语料库哈希值变更视为需要重新验证的依据。

不变量

• Skill 变更后，绝不降低评测阈值来维持成熟度标签。
• 绝不将私有的预期或禁止 oracle 字段复制到提供方可见的提示词中。
• 规范 Skill 必须以与提供方无关的语言描述能力。
• 每个非平凡的 Skill 套件都必须至少包含一份实质性的渐进式参考资料（>=1000 字节）。
• 行为成熟度声明必须基于跨语义场景系列、最新且经过验证的留出评测。

决策规则

• 优先采用一个领域明确的强大 Skill，而不是多个相互重叠的微型 Skill。
• 如果两个 Skill 都可能因同一个常见请求而合理触发，应先明确它们的边界，再添加更多关键词。
• 如果正文只有线性的顺利路径流程，应补充实际工作中专家必须在其间做出选择的分支。
• 如果参考资料只是在转述正文，应将其替换为更深入的内容。
• 如果只需复述 Skill 描述就能通过评测，而无需理解具体情境，应增加模糊性或相互冲突的证据。
• Skill 变更后，绝不降低评测阈值来维持成熟度标签。
• 绝不将私有的预期/禁止 oracle 字段复制到提供方可见的提示词中。
• 避免在规范行为中使用特定提供方的工具名称。描述能力，再由宿主适配器进行映射。

故障分类

触发故障

Skill 触发过于频繁，或漏掉明显的请求。应先调整边界和描述，再增加流程说明。

行为浅层化

Skill 能选择正确的大致操作，却无法区分难以判断的子情况。应增加分类、决策分支和语义评估类别。

资源浅层化

虽然有参考资料，但内容只有摘要。应将其替换为操作指南和权衡分析实例。

评估假象

通过率很高，是因为场景近乎重复或泄露了答案。应扩大语义覆盖面，并隔离判定标准。

契约偏移

SKILL.md、包元数据、Agent 配置文件、注册表条目和评估描述的行为各不相同。发布前应统一。

反模式

在 Skill 审核期间，应拒绝以下模式：

• 只说“遵循最佳实践”，却未指出要做出的决策或依据。
• 在无关的 Skills 之间重复使用同一套通用流程；
• 参考资料不到约一屏内容，且只是重述主要步骤；
• 用一个玩具示例代表整个领域；
• 评估套件只包含一个场景及其措辞变体；
• 没有诊断依据，却设定任意的重试次数；
• 无需新的证据即可满足的完成标准；
• When NOT to Use 部分未提及最接近的竞争 Skill；
• 庞大的单体提示词重复包含所有参考资料，破坏渐进式披露。

证据要求

强化后的 Skill 应具备：

• 有效的包结构和前置元数据结构；
• 明确的启用边界和拒绝边界；
• 情境分类和决策规则；
• 特定领域的失败分类；
• 至少一份内容充实的渐进式参考资料；
• 涵盖非理想路径的示例；
• 多个语义评估类别；
• 评估语料发生变化时重新运行行为评估。

交接约定

完成 Skill 编写后，请报告：

• Skill ID 及其负责的能力；
• 相邻 Skills 及触发边界；
• 新增的语义评估类别；
• 新增的渐进式资源；
• 已知的不支持情形；
• 确定性验证状态；
• 行为证据是最新、过时，还是尚未执行。

完成标准

不要仅仅因为所有预期文件夹都已存在，就认为 Skill 已成熟。

完成需满足以下条件：

• 包验证通过；
• 上述契约部分在相关位置均有实质性内容；
• 资源增加了深度，而非重复内容；
• 评估覆盖面足以测试主要决策和捷径；
• 注册表／宿主元数据保持一致；
• 任何因语料变化而失效的既有行为证明，都应明确标记为过时，直至重新运行。

渐进式资源

• 深度标准：references/depth-standard-v2.md
• 现有的编写参考资料和模板仍可用于包机制相关工作。