fable-skill-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Creator

Skill 创建器

Create Skills that change agent behavior under pressure, not Skills that merely describe good practice.

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

Mission

使命

A production Skill is a compact operating manual for a recurring class of decisions. It should help an agent recognize the situation, choose among plausible actions, collect the right evidence, reject tempting shortcuts, and hand off cleanly when another specialist is better suited.

A schema-valid

SKILL.md

is not enough. A Skill that only says "inspect, plan, implement, verify" is documentation, not a behavioral capability.

生产级 Skill 是针对某一类重复性决策的精简操作手册。它应帮助 Agent 识别情境、在多个合理行动之间进行选择、收集正确证据、拒绝看似合理的捷径，并在其他专家更适合处理时进行干净的交接。

仅有一个符合 schema 的

SKILL.md

并不足够。如果一个 Skill 只是说“检查、规划、实现、验证”，那它是文档，而不是行为能力。

Activation Contract

激活契约

Use this Skill when the requested work is to:

create a new reusable Skill;
strengthen or refactor an existing Skill;
improve triggering accuracy or reduce overlap with neighboring Skills;
add references, examples, templates, agents, or evals;
convert a repeated workflow into a portable agent capability;
prove that a Skill behaves correctly across more than a happy-path example.

Do not use it for ordinary application changes, bug fixes, or repository maintenance. Route those to the appropriate lifecycle Skill.

当请求的工作属于以下情况时，使用此 Skill：

创建新的可复用 Skill；
强化或重构现有 Skill；
提高触发准确性或减少与相邻 Skill 的重叠；
添加参考资料、示例、模板、Agent 或 eval；
将重复工作流转换为可移植的 Agent 能力；
证明某个 Skill 在超出单一理想路径示例的场景中能够正确运行。

不要将其用于常规应用变更、错误修复或仓库维护。将这些工作转交给相应的生命周期 Skill。

Inputs

输入

user_intent
: capability, behavior, or workflow to encode.
workflow_trace
: observed sequence of decisions/tools/failures, when available.
reference_sources
: primary docs, schemas, domain rules, or proven internal patterns.

user_intent
：需要编码的能力、行为或工作流。
workflow_trace
：观察到的决策、工具调用和失败序列（如有）。
reference_sources
：主要文档、schema、领域规则或经过验证的内部模式。

Skill Depth Classification

Skill 深度分类

Before authoring, classify the capability:

Class	Typical shape	Required depth
Rule	One stable decision with few branches	concise Skill, strong boundaries
Procedure	Multi-step repeatable operation	staged protocol + evidence
Diagnostic	Symptoms map to competing causes	failure taxonomy + falsification
Orchestrator	Chooses/delegates among specialists	routing table + handoff contracts
Domain expert	Requires substantial specialist knowledge	deep references + examples + eval families

If the capability is Diagnostic, Orchestrator, or Domain expert, a short checklist is presumptively insufficient.

开始创作前，对能力进行分类：

类别	典型形态	所需深度
规则	一个稳定决策，仅有少量分支	精简 Skill、明确边界
流程	可重复的多步骤操作	分阶段协议 + 证据
诊断	将症状映射到多个竞争性原因	失败分类 + 反证
编排	在多个专家之间选择或委派	路由表 + 交接契约
领域专家	需要大量专业领域知识	深度参考资料 + 示例 + eval 系列

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

Skill Contract V2

Skill 契约 V2

Every non-trivial Skill must answer these questions explicitly.

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

1. When does it activate?

1. 何时激活？

Define positive triggers, negative triggers, prerequisites, and escalation conditions. Include near-neighbor tasks that should not select this Skill.

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

2. What situation is the agent in?

2. Agent 处于什么情境？

Provide a small classification that changes behavior. Examples: bounded vs architectural, deterministic vs flaky, local vs external, reversible vs destructive, known vs uncertain.

提供一种能够改变行为的小型分类。例如：有界与架构性、确定性与偶发性、本地与外部、可逆与破坏性、已知与不确定。

3. What decisions must be made?

3. 必须做出哪些决策？

Use decision tables or branching rules for ambiguous cases. Do not hide judgment behind vague language such as "when appropriate" without defining the evidence that makes it appropriate.

对模糊情况使用决策表或分支规则。不要用“适当时”之类的含糊语言隐藏判断，也不要在未定义“何时适当”的证据标准时作出选择。

4. What is the execution protocol?

4. 执行协议是什么？

For each stage specify:

objective;
allowed actions;
required evidence;
exit condition;
stop/escalation condition.

每个阶段都要明确说明：

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

5. How can it fail?

5. 可能如何失败？

Name domain-specific failure classes and observable signals that distinguish them. Do not collapse every failure into "retry" or "use recover".

列出领域特定的失败类别，以及能够区分这些失败的可观察信号。不要将所有失败都归为“重试”或“使用恢复机制”。

6. What must never become false?

6. 哪些内容绝不能为假？

List invariants that stay true throughout the Skill. Examples: no production mutation before valid RED, no release claim without registry confirmation, no review finding without a concrete failure mode.

列出在整个 Skill 执行过程中始终成立的不变量。例如：在获得有效的 RED 之前不得修改生产环境；没有 registry 确认不得宣称已发布；没有具体失败模式不得提出审查发现。

7. Which shortcuts are tempting but invalid?

7. 哪些捷径看似诱人但实际上无效？

Document anti-patterns that capable models commonly choose under time pressure or ambiguous prompts.

记录能力较强的模型在时间压力或提示含糊时经常选择的反模式。

8. What evidence leaves the Skill?

8. Skill 会留下哪些证据？

Define a handoff packet for the next specialist: facts learned, commands run, artifacts changed, residual risk, unresolved questions, and proof freshness where relevant.

为下一位专家定义交接数据包：已掌握的事实、执行过的命令、已更改的产物、剩余风险、未解决问题，以及相关证据的新鲜度。

9. What belongs in progressive resources?

9. 哪些内容应放入渐进式资源？

SKILL.md

should hold decision logic. References should add operational depth, not repeat the same checklist in different words.

Useful resources include:

decision heuristics;
failure diagnosis guides;
legacy/edge-case playbooks;
worked examples with trade-offs;
tool-independent verification strategies;
checklists only where the checklist encodes non-obvious domain knowledge.

SKILL.md

应承载决策逻辑。参考资料应增加操作深度，而不是用不同措辞重复同一份清单。

有用的资源包括：

决策启发式；
失败诊断指南；
遗留系统或边缘场景手册；
包含权衡分析的实战示例；
与工具无关的验证策略；
仅在清单编码了不明显领域知识的场景中使用清单。

10. How will we know the Skill actually works?

10. 如何确认 Skill 确实有效？

Create multiple semantically distinct eval families. Surface variations of one scenario do not count as breadth.

创建多个语义上不同的 eval 系列。仅对同一场景进行表面改写不算作覆盖广度。

Eval Depth Standard

Eval 深度标准

For a non-trivial Skill, target at least 6 semantic scenario families across its package before calling evaluation coverage mature. A family is a different decision problem, not the same prompt rewritten five ways.

Include a mix of:

straightforward activation;
boundary/non-trigger case;
ambiguous situation requiring classification;
adversarial pressure to take a shortcut;
partial or contradictory evidence;
failure/recovery handoff;
legacy or constrained environment where the normal happy path is unavailable.

The enterprise behavior harness may still expand each family into known/negative/ambiguous/adversarial/holdout variants. That expansion does not replace semantic family breadth.

对于非平凡 Skill，在整个包中应至少覆盖 6 个语义场景系列，之后才能认为 eval 覆盖度已经成熟。一个系列代表不同的决策问题，而不是将同一个提示改写五次。

应包含以下类型的组合：

直接激活；
边界或非触发场景；
需要分类的模糊情境；
诱导采用捷径的对抗性压力；
部分或相互矛盾的证据；
失败、恢复与交接；
无法使用常规理想路径的遗留或受限环境。

企业行为测试框架仍可将每个系列扩展为已知、负向、模糊、对抗性和留出变体。这种扩展不能取代语义系列本身的广度。

Authoring Procedure

创作流程

Observe the real job: identify decisions, artifacts, failure modes, and handoffs from real workflows or primary sources.
Map neighboring Skills: define what this Skill owns and what it deliberately refuses.
Write eval scenarios first for the most important failure-prone decisions. If the expected action cannot be stated clearly, the Skill contract is not ready.
Design the decision model: classification, branches, invariants, stop conditions.
Write
SKILL.md
in imperative, tool-independent language.
Add progressive resources for depth that would otherwise make the main Skill noisy.
Add worked examples including at least one case where the obvious first move is wrong.
Create/refresh agent profiles so host-facing prompts point to the full Skill contract rather than replacing it with a one-line summary.
Validate packaging and registry metadata.
Run deterministic and behavioral evals. Treat changed Skill/eval corpus hashes as requiring fresh proof.

观察真实工作：从真实工作流或主要来源中识别决策、产物、失败模式和交接点。
映射相邻 Skill：定义此 Skill 负责的内容，以及它明确拒绝处理的内容。
优先编写 eval 场景：先为最重要且容易失败的决策编写 eval 场景。如果无法清晰说明预期行动，说明 Skill 契约尚未准备就绪。
设计决策模型：分类、分支、不变量和停止条件。
编写
SKILL.md
：使用祈使式、与工具无关的语言。
添加渐进式资源：补充深度内容，避免主 Skill 变得过于嘈杂。
添加实战示例：至少包含一个明显的第一步行动实际错误的案例。
创建或刷新 Agent 配置文件：确保面向宿主的提示词指向完整的 Skill 契约，而不是用一行摘要替代契约。
验证打包和 registry 元数据。
运行确定性和行为 eval：Skill 或 eval 语料库的哈希发生变化时，必须重新获取最新证明。

Invariants

不变量

Never lower evaluation thresholds to preserve a maturity label after a Skill changes.
Never copy private expected or forbidden oracle fields into provider-visible prompts.
Canonical Skills must describe capabilities in provider-neutral language.
Every non-trivial Skill package must include at least one substantial progressive reference (>=1000 bytes).
Behavioral maturity claims require fresh verified holdout evaluation across semantic scenario families.

Skill 发生变化后，绝不能为了保留成熟度标签而降低 eval 阈值。
绝不能将私有的预期或禁用 oracle 字段复制到服务提供方可见的提示词中。
规范化 Skill 必须使用与具体服务提供方无关的语言描述能力。
每个非平凡 Skill 包都必须至少包含一份实质性的渐进式参考资源（>=1000 字节）。
行为成熟度声明必须基于跨语义场景系列重新验证并确认有效的留出 eval。

Decision Rules

决策规则

Prefer one strong Skill with a clear domain over several overlapping micro-Skills.
If two Skills can both reasonably trigger from the same ordinary request, sharpen their boundaries before adding more keywords.
If the body contains only a linear happy-path procedure, add the branches that real work forces an expert to choose between.
If a reference merely paraphrases the body, replace it with deeper material.
If an eval can be passed by parroting the Skill description without understanding the situation, add ambiguity or conflicting evidence.
Never lower eval thresholds to preserve a maturity label after the Skill changes.
Never copy private expected/forbidden oracle fields into provider-visible prompts.
Avoid provider-specific tool names in canonical behavior. Describe capabilities, then let host adapters map them.

相比多个相互重叠的微型 Skill，优先选择一个具有明确领域边界的强 Skill。
如果同一个普通请求可以合理触发两个 Skill，应在添加更多关键词之前先明确它们的边界。
如果正文只包含线性的理想路径流程，应添加真实工作迫使专家作出选择时所必需的分支。
如果参考资料只是换一种说法复述正文，应将其替换为更深度的内容。
如果仅靠复述 Skill 描述就能通过 eval，而无需理解情境，则应加入模糊性或相互冲突的证据。
Skill 发生变化后，绝不能为了保留成熟度标签而降低 eval 阈值。
绝不能将私有的预期或禁用 oracle 字段复制到服务提供方可见的提示词中。
规范化行为中应避免使用特定服务提供方的工具名称。先描述能力，再由宿主适配器完成映射。

Failure Taxonomy

失败分类

Triggering failure

触发失败

Skill activates too often or misses obvious requests. Fix boundaries and description before adding more procedure text.

Skill 激活过于频繁，或遗漏了明显请求。应先修复边界和描述，然后再添加更多流程文本。

Behavioral shallowness

行为深度不足

Skill selects the right broad action but cannot discriminate difficult subcases. Add classification, decision branches, and semantic eval families.

Skill 选择了正确的大方向，但无法区分困难的子场景。应添加分类、决策分支和语义 eval 系列。

Resource shallowness

资源深度不足

References exist but contain only summaries. Replace with operational guides and worked trade-offs.

参考资料存在，但只包含摘要。应将其替换为操作指南和实战权衡。

Evaluation illusion

评估错觉

Pass rate is high because scenarios are near-duplicates or leak the answer. Increase semantic breadth and oracle isolation.

通过率很高，是因为场景近乎重复或泄露了答案。应增加语义广度并隔离 oracle。

Contract drift

契约漂移

SKILL.md

, package metadata, agent profiles, registry entries, and evals describe different behavior. Reconcile before release.

SKILL.md

、包元数据、Agent 配置文件、registry 条目和 eval 描述了不同的行为。发布前应使其保持一致。

Anti-Patterns

反模式

Reject these patterns during Skill review:

"Use best practices" without naming the decision or evidence.
one generic procedure reused across unrelated Skills;
references under ~one screen that only restate the main steps;
one toy example presented as domain coverage;
an eval suite made from one scenario plus wording variants;
arbitrary retry counts with no diagnostic reason;
completion criteria that can be satisfied without fresh evidence;
```
When NOT to Use
```
sections that omit the closest competing Skill;
giant monolithic prompts that duplicate every reference and destroy progressive disclosure.

在 Skill 审查中，应拒绝以下模式：

只说“使用最佳实践”，却没有指明具体决策和证据；
在互不相关的 Skill 中重复使用同一个通用流程；
参考资料不足一屏，且只是重述主要步骤；
将一个简单示例当作领域覆盖；
eval 套件仅由一个场景及其措辞变体组成；
在没有诊断依据的情况下任意设置重试次数；
无需最新证据即可满足的完成标准；
```
When NOT to Use
```
部分未提及最接近的竞争性 Skill；
巨型单体提示词重复所有参考资料，破坏渐进式披露。

Evidence Requirements

证据要求

A strengthened Skill should provide:

valid package/frontmatter structure;
explicit activation and refusal boundaries;
situation classification and decision rules;
domain-specific failure taxonomy;
at least one substantial progressive reference;
worked example(s) covering a non-happy path;
multiple semantic eval families;
behavioral evidence re-run when the evaluated corpus changes.

经过强化的 Skill 应提供：

有效的包结构和 frontmatter；
明确的激活与拒绝边界；
情境分类和决策规则；
领域特定的失败分类；
至少一份实质性的渐进式参考资源；
覆盖非理想路径的实战示例；
多个语义 eval 系列；
被评语料库发生变化时重新运行的行为证据。

Handoff Contract

交接契约

When finishing Skill authoring, report:

Skill ID and owned capability;
neighboring Skills and trigger boundaries;
semantic eval families added;
progressive resources added;
known unsupported cases;
deterministic validation status;
whether behavioral evidence is fresh, stale, or not yet executed.

完成 Skill 创作时，应报告：

Skill ID 及其负责的能力；
相邻 Skill 和触发边界；
新增的语义 eval 系列；
新增的渐进式资源；
已知的不支持场景；
确定性验证状态；
行为证据是最新、已过期，还是尚未执行。

Completion Criteria

完成标准

Do not call the Skill mature merely because all expected folders exist.

Completion requires:

package validation passes;
contract sections above are materially present where relevant;
resources add depth rather than duplication;
eval breadth tests the major decisions and shortcuts;
registry/host metadata remains consistent;
any prior behavioral proof invalidated by corpus changes is explicitly marked stale until rerun.

不要仅因为所有预期目录都存在，就认定 Skill 已成熟。

完成需要满足：

包验证通过；
在相关情况下，上述契约章节已实质性地呈现；
资源增加了深度而非重复内容；
eval 广度能够测试主要决策和捷径；
registry 或宿主元数据保持一致；
因语料库变化而失效的既有行为证明，在重新运行前必须明确标记为已过期。

Progressive Resources

渐进式资源

Depth standard:
```
references/depth-standard-v2.md
```
Existing authoring references and templates remain useful for package mechanics.

深度标准：
```
references/depth-standard-v2.md
```
现有创作参考资料和模板仍可用于处理包机制。