返回 Skills
vinvcn/mattpocock-skills-zh-cn· MIT 内容可用

writing-great-skills

编写和编辑优秀 skills 的参考：让技能可预测的词汇和原则。

安装

与 skills.sh 相同的 Command / Prompt 安装方式

name: writing-great-skills description: 编写和编辑优秀 skills 的参考：让技能可预测的词汇和原则。 disable-model-invocation: true

Skill 的存在，是为了从随机系统中拧出 determinism。Predictability 是根本美德：agent 每次采取相同的 process，而不是产出相同的 output。下面所有杠杆都服务于它。

粗体术语 在 GLOSSARY.md 中定义；需要完整含义时查那里。

Invocation

两种选择，成本不同：

  • Model-invoked skill 保留 description，所以 agent 可以自主触发它，其他 skills 也能触达它（用户仍可手动输入名称）。它会带来 context load：description 每轮都在 context window 中。机制：省略 disable-model-invocation，并写 model-facing description，带丰富触发措辞（"Use when the user wants..."、"mentions..."）。
  • User-invoked skill 把 description 从 agent 触达范围中拿掉：只有用户输入名称时才能调用，其他 skill 也不能调用它。零 context load，但会花 cognitive load：用户 必须记得它存在。机制：设置 disable-model-invocation: true；description 变成人类看到的一行摘要，不放触发列表。

只有当 agent 必须自行找到该 skill，或另一个 skill 必须调用它时，才选择 model-invocation。如果它只会被手动触发，就做成 user-invoked，不付 context load。

当 user-invoked skills 多到用户记不住时，用一个 router skill 解决 cognitive load：一个 user-invoked skill，负责命名其他 user-invoked skills 以及何时使用它们。

Writing the description

Model-invoked description 做两件事：说明 skill 是什么，并列出应触发它的 branches。每个词都会增加 context load，所以 description 比正文更需要修剪：

  • 把 skill 的 leading word 放前面。
  • 每个 branch 一个 trigger。 同义词如果只是重命名单一 branch，就是 duplication；合并它。
  • 删掉正文已有的 identity。 Description 只保留 triggers，以及必要的 "when another skill needs..." reach clause。

Information hierarchy

Skill 由两类内容构成：steps 与 reference。它可以全是 steps、全是 reference，或两者都有。核心决策是把内容放在 information hierarchy 的哪一层：

  1. In-skill step - SKILL.md 中的有序动作，是 primary tier。每个 step 以 completion criterion 结束。Criterion 要可检查，必要时要 exhaustive。
  2. In-skill reference - SKILL.md 中的定义、规则或事实，按需查阅。
  3. External reference - 从 SKILL.md 推到独立文件中，经 context pointer 触达。

强 completion criterion 会驱动充分 legwork。把太少内容下放会让顶层膨胀；把太多内容下放会隐藏 agent 实际需要的材料。

Progressive disclosure 是把 reference 下移到链接文件中，让顶层保持清晰。Mechanics：skill folder 中的 linked .md 文件，用内容命名。多用途 skill 的每种用法都是一个 branch：所有 branches 都需要的内容内联，只有部分 branches 需要的内容放到 pointer 后面。Context pointer 的措辞，而不是目标文件，决定 agent 何时以及多可靠地触达材料。

Co-location 决定内容一旦下放后放在哪里：把一个概念的定义、规则和 caveats 放在同一 heading 下，而不是散落各处。

When to split

Granularity 是 skill 切分粒度。每次切分都会花两种 load 之一，所以只有切分有收益时才切。

  • By invocation - 当你有一个独立 leading word 应自主触发，或另一个 skill 必须触达它时，拆出 model-invoked skill。你要为新 description 支付 context load，所以独立触达必须值得。
  • By sequence - 当后续 steps 会诱使 agent 急着结束前一步（premature completion）时，拆分 step sequence，把后面的内容隐藏起来。

Pruning

让每个 meaning 都有 single source of truth：一个权威位置，行为变化时只改一处。

逐行检查 relevance：它是否仍支撑 skill 的工作？

然后逐句寻找 no-ops。把每个句子单独做 no-op test；失败时删除整句，而不是只修剪词。要激进；多数失败 prose 应删除，不应重写。

Leading words

Leading word 是一个已经存在于模型预训练中的紧凑概念，agent 会在运行 skill 时用它思考（例如 lesson、fog of war、tracer bullets）。它在文本中反复出现，累积 distributed definition，并用最少 tokens 固定一片 behavior。

它从两方面服务 predictability。正文中它锚定 execution；description 中它锚定 invocation。当相同词出现在 prompts、docs 和 codebase 中，agent 更容易把 shared language 连到该 skill。

寻找机会把 skills 重构为使用 leading words。三处重复展开的 triad、花一句话绕一个概念的 description，都可能能 collapse 成一个 token。例如：

  • "fast, deterministic, low-overhead" -> tight
  • "a loop you believe in" -> red

你同时赢得更少 tokens 和更尖锐的 thinking hook。

Failure modes

  • Premature completion - 当前 step 尚未真正完成就结束。防御顺序：先 sharpen completion criterion；只有当 criterion 不可避免地模糊且你观察到 rush 时，才通过拆分隐藏 post-completion steps。
  • Duplication - 同一 meaning 出现在多个地方。它提高维护成本、浪费 tokens，并夸大该 meaning 在 hierarchy 中的重要性。
  • Sediment - 因为添加看似安全、删除看似有风险而沉积的 stale layers。
  • Sprawl - skill 太长，即使每一行都 live 且 unique。用 hierarchy 治疗：把 reference 放到 pointers 后，按 branch 或 sequence 拆分。
  • No-op - 模型默认就会做的 instruction。测试：它是否改变默认 behavior？弱 leading word（如 be thorough，当 agent 已经大致 thorough）就是 no-op；修法是换更强的词（如 relentless）。
  • Negation - 用禁止来引导会适得其反：don't think of an elephant 点名了 elephant，让它更容易浮现。应 prompt positive：直接说明目标 behavior，让被禁止的行为不进入表述；只有无法正向表达的 hard guardrail 才保留 prohibition，而且仍要配上应该怎么做。

附带文件

GLOSSARY.md
# Glossary - Building Great Skills

这是关于如何写好 skills 的 domain model。Skill 的存在，是为了从随机系统中拧出 determinism；根本美德是 **Predictability**，下面每个 term 都是作用于它的杠杆。它是 [`writing-great-skills`](SKILL.md) 的 disclosed reference。

Terms 按轴分组：**Invocation**（skill 如何被触达）、**Information Hierarchy**（内容如何安排）、**Steering**（如何塑造 agent 运行时行为）、**Pruning**（如何保持精瘦）。每个 **failure mode** 都放在治疗它的杠杆旁，并标记为 _failure mode_。

**粗体术语** 在定义中互相引用；按 heading 查找。

## Predictability

Skill 让 agent 每次以同样 _方式_ 行动的程度：同样的 process，不是同样的 output（brainstorming skill 应 _predictably_ diverge；tokens 会变，behavior 不变）。这是其他术语服务的根本美德；cost 和 maintainability 是它的症状，不是 rival。

_Avoid_: consistency, reliability, robustness, output-determinism

## Invocation

Skill 如何被触达，以及你为选择支付的两种 load。

### Model-Invoked

保留 **description** field 的 skill，所以 agent 能看到并自主触发它；用户也仍能输入名称调用它。Model-invocation 总是 _包含_ user reach。它为 discoverability 支付永久 **context load**。其他 skills 也能触达它，因为 description 让它能被 agent 发现。只有当 agent 必须自行触达时才选择它；如果永远只手动触发，就去掉 description，不付 context load。

_Avoid_: ability, tool, capability

### User-Invoked

去掉 agent 可见 **description** 的 skill，只能由人输入名称调用。它用零 **context load** 换取人工记忆成本。因为没有 description，除了人类以外没有任何东西能触达它；其他 skill 也不能触发它。

_Avoid_: procedure, workflow, command

### Description

Skill 的 machine-readable trigger，也是 model-invoked skill 被迫始终加载的 **context pointer**。它的存在本身就是 invocation axis：保留它就是 model-invoked；删除它就是 **user-invoked**。它是 model-invoked skill 的 **context load** 来源。

_Avoid_: frontmatter, summary

### Context Pointer

保存在 agent context 中的一段 reference，命名某个 out-of-context material，并编码何时触达它。**Description** 是顶层 context pointer；指向 disclosed files 的 pointers 是下一层。它的措辞，而不是目标，决定 agent 何时以及多可靠地触达材料。

_Avoid_: link, reference, import

### Context Load

**Model-invoked** skill 对 context window 施加的成本：它的 **description** 始终加载，消耗 tokens 和 attention。**User-invoked** skills 通过没有 description 避开它。

_Avoid_: token cost, context bloat

### Cognitive Load

**User-invoked** skill 对人施加的成本：人必须记住哪些 skills 存在以及何时使用它们。**Model-invocation** 通过 agent discoverability 消除这部分成本。它不是纯粹要最小化的成本；这是 human agency 的价格。

_Avoid_: human index, burden, overhead

### Router Skill

一个 **user-invoked** skill，职责是指出其他 user-invoked skills 以及何时使用它们。它只能提示，不能触发它们。它治疗 user-invoked skills 增多后的 **cognitive load**。

_Avoid_: dispatcher, menu, registry, index, router procedure

### Granularity

Skills 的切分细度。更细的切分会花两种 load 之一：更多 **model-invoked** skills 花 **context load**；更多 **user-invoked** skills 花 **cognitive load**。按 **invocation** 切时，需要一个独立 **leading word**；按 **sequence** 切时，是为了隐藏 **post-completion steps**，避免 premature completion。

_Avoid_: chunking, modularity

## Information Hierarchy

Skill 内容如何安排，以及每块内容在 ladder 上的位置。

### Information Hierarchy

按 agent 需要材料的即时程度对内容排序。Rungs：

- **Steps** - in-file, primary
- **Reference** - in-file, secondary
- **Reference**, disclosed - behind a **context pointer**

没有 **steps** 的 skill 只使用后两层，通常是 flat peer-set，这不是坏味道。Hierarchy 独立于 invocation：skill 可以 model- 或 user-invoked，也可以全 steps、全 reference 或两者都有。

_Avoid_: structure, organization, layout

### Steps

Agent 执行的有序动作。每个 step 都以 **completion criterion** 结束。不是所有 skill 都有 steps；skill 可以全是 steps、全是 **reference**，或两者都有。

_Avoid_: workflow, instructions, choreography

### Reference

Agent 按需查阅的材料：definitions、facts、parameters、examples、conditional instructions。它通过 **context pointers** 触达，是 **progressive disclosure** 的主要候选。

_Avoid_: supporting material, docs, background

### External Reference

位于 skill system 之外的 **Reference**：普通文件，没有 **description**，没有 **steps**，不可调用。它是多个 skills 都能指向的共享 reference home。

_Avoid_: doc, resource, knowledge base

### Progressive Disclosure

把 **reference** 从 `SKILL.md` 移到 **context pointer** 后面，让顶层保持清晰。这主要不是 token 优化，而是保护 **information hierarchy**。通过 **branching** 授权：所有路径都需要的内容内联，只有部分路径需要的内容 disclosed。

_Avoid_: lazy loading, chunking

### Co-location

把 agent 同时需要的材料放在一起：一个概念的 definition、rules 和 caveats 放在同一 heading，而不是散落各处。它是 **Information Hierarchy** 的文件内 companion。

_Avoid_: grouping, clustering, cohesion

### Sprawl

_Failure mode._ Skill 过长，即使每行都 live 且 unique。它伤害 readability、maintainability 和 tokens。治疗方式是 **information hierarchy**：把 **reference** 推到 **context pointers** 后，并按 **branch** 或 sequence 拆分。

_Avoid_: bloat, length, size, verbosity

## Steering

塑造 agent runtime behavior、提升 **Predictability** 的杠杆。

### Branch

Skill 可以被调用的一种不同方式；不同 runs 会沿着不同路径。线性 skill 没有 branch。

_Avoid_: path, case, fork

### Leading Word

一个紧凑概念，也叫 _Leitwort_，已经存在于模型预训练中，agent 会在运行 skill 时用它思考。它用最少 tokens 编码 behavioral principle，例如 _lesson_、_proximal zone of development_、_fog of war_、_tracer bullets_。

Leading word 同时服务 execution 与 invocation：正文中它让 agent 每次遇到该概念都触发同类行为；description 中它让 prompt、docs、codebase 中的 shared language 更容易触发 skill。

_Avoid_: keyword, term, motif

### Completion Criterion

告诉 agent 一段工作完成的条件。它的 **clarity** 抵抗 **premature completion**；它的 **demand** 决定 **legwork**。最强的 criteria 既可检查又 exhaustive。

_Avoid_: done condition, exit condition, stopping rule

### Legwork

Agent 在单个 step 内幕后做的工作：读文件、探索 codebase、修改、挖出所需材料，而不是把问题丢给用户。它受强 **leading word** 和 demanding **completion criterion** 驱动。

_Avoid_: scope, effort, diligence, coverage

### Post-Completion Steps

当前 step 之后的 **steps**。可见时，它们会把 agent 拉向 **premature completion**；防御方式是通过拆分 sequence 把它们隐藏。

_Avoid_: horizon, fog of war, lookahead

### Premature Completion

_Failure mode._ 当前 step 尚未真正完成就结束，因为 agent 注意力滑向 "being done"。它发生在 steps 之间；由 visible **post-completion steps** 与模糊 **completion criterion** 的拉扯产生。先 sharpen criterion；只有当 criterion 不可避免地模糊且确实观察到 rush 时，才隐藏后续 steps。

_Avoid_: premature closure, the rush, rushing, shortcutting

### Negation

_Failure mode._ 用 prohibition 引导：告诉 agent *不要* 做什么，会把被禁止的 behavior 带进 context，反而让它更容易出现。_Don't think of an elephant_，于是满脑子都是 elephant；_never write verbose comments_，模型刚读到的 pattern 恰恰是 verbosity。Negation 是弱 modifier，会被强烈激活的 concept 压过，因此禁令读起来有一半像是在指示它去做那件事。它的 **leading word** 是 _elephant_：prohibition 带入 frame 的任何东西。修复方法：prompt **positive**，描述目标 behavior（“write one-line comments”），让被禁止的行为根本不被说出。只有某种行为无法用正面措辞表达、必须作为 hard guardrail 时，prohibition 才有存在价值；即使如此，也要配上 positive target，让注意力落到应该怎么做。

_Avoid_: ironic rebound, don't-prompting, the pink elephant

## Pruning

保持 skill 精瘦；每个 remedy 对应一个 failure。

### Single Source of Truth

每个 meaning 只存在于一个权威位置。**Duplication** 是它的违反。

_Avoid_: home, canonical location

### Duplication

_Failure mode._ 同一个 meaning 出现在多个位置。它增加维护成本、消耗 tokens，并把 meaning 在 ladder 上的 prominence 夸大。

_Avoid_: repetition, redundancy

### Relevance

一行是否仍然支撑 skill 的工作。Relevance 问的是它是否与任务相关，不是它是否改变 behavior。

_Avoid_: load-bearing, staleness, freshness

### Sediment

_Failure mode._ stale layers 因为添加看似安全、删除看似有风险而沉积下来。它是缺少 pruning discipline 时的默认命运。

_Avoid_: accretion, bloat, cruft, rot

### No-Op

_Failure mode._ 一条 instruction 没有改变任何行为，因为模型默认就会这么做。测试：它是否改变默认 behavior？Leading word 也可能是 no-op；修法是换一个更强的词，而不是换技术。

_Avoid_: redundant instruction, restating the obvious, belaboring
    writing-great-skills | Prompt Minder