write-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write Skills

编写Skill

A skill is not documentation. It is compressed operational memory for an agent that already knows how to code and reason. Its job is predictability — the agent taking the same process every run, not producing the same output. Put only the context that changes what the agent will do.

Skill并非文档。它是为已具备编码和推理能力的Agent准备的压缩式操作记忆。它的核心作用是可预测性——让Agent每次执行时遵循相同的流程，而非生成相同的输出。仅保留会改变Agent行为的上下文信息。

First Principles

核心原则

Trigger from the description. The frontmatter
```
description
```
is the only part read before the skill loads. Say what the skill does and the concrete situations that should trigger it. Do not hide trigger rules in the body.
Spend tokens like they are scarce. Assume the agent is already good at general reasoning. Keep only non-obvious workflow, domain constraints, tool choices, failure modes, and validation rules. Delete background, motivation, and generic advice.
Write procedures, not essays. Prefer imperative rules, decision points, and small examples. A good skill changes behavior in the next turn; it does not merely explain the topic. And match the procedure to the deliverable's shape: a catalog of techniques with "pick what fits" produces tool-picking, not a flow — if the job is a shaped interaction (an interview, a staged walk), the workflow must be that shape, with the techniques demoted to steps inside it.
Use progressive disclosure. Keep the main skill file short. Push long schemas, examples, provider docs, or variant-specific guidance out into linked
```
references/
```
files, reached by a pointer that fires only when needed. Put repeatable fragile operations in
```
scripts/
```
. Put reusable output material in
```
assets/
```
.
Validate by use. A skill is good when a fresh agent applies it correctly on a realistic task — run it blind, and on the weakest model that will run it; a skill that only drives correct behavior on the frontier model that authored it is too fragile to ship. After editing, read it as if you had no conversation history and remove anything that would not affect action.
Examples document the PROBLEM, not the solution. An example earns its tokens by teaching the agent to recognise a recurring problem — the smell, the symptom, how you knew it was wrong. That is durable. The fix you happened to apply is not: code changes, and a baked-in solution goes stale, or worse prescribes a move that won't fit next time. Write the failure mode and its tell; let the agent derive the fix fresh against the current code. "A directional question gated on a centroid distance read wrong from every bearing" teaches; "so we keyed it on FRONT_ARC" rots. When in doubt, state what was broken and how you spotted it, and stop there.

通过描述触发：前置元数据（frontmatter）中的
```
description
```
是Skill加载前唯一会被读取的部分。明确说明Skill的功能以及触发它的具体场景，不要将触发规则隐藏在正文内容中。
像对待稀缺资源一样使用Tokens：假设Agent已具备出色的通用推理能力。仅保留非显而易见的工作流程、领域约束、工具选择、故障模式和验证规则。删除背景介绍、动机说明和通用建议。
编写流程，而非散文：优先使用命令式规则、决策节点和小型示例。优质的Skill会在下次执行时改变Agent的行为，而非仅仅解释主题。同时要让流程与交付成果的形态匹配：如果是“选择合适技术”的技巧目录，会引导Agent进行工具选择，而非固定流程；如果任务是结构化交互（如访谈、分阶段演示），工作流程必须贴合该形态，将具体技巧降级为流程内的步骤。
渐进式披露信息：保持主Skill文件简洁。将冗长的模式、示例、供应商文档或特定变体的指导内容移至关联的
```
references/
```
文件夹中，仅在需要时通过指针加载。将可重复的易出错操作放在
```
scripts/
```
中，将可复用的输出素材放在
```
assets/
```
中。
通过实际使用验证：当一个全新的Agent能在真实任务中正确应用该Skill时，它才是合格的——要在无前置信息的情况下测试，且使用能运行它的最弱模型；仅能在创作它的前沿模型上驱动正确行为的Skill过于脆弱，无法投入使用。编辑完成后，假设自己没有对话历史，重新阅读并删除所有不会影响行动的内容。
示例用于描述问题，而非解决方案：示例的价值在于教会Agent识别重复出现的问题——问题的特征、症状以及如何判断它是错误的。这是持久有效的。而你当时采用的修复方案并非如此：代码会变化，固化的解决方案会过时，甚至可能给出不适合下一次场景的操作。描述故障模式及其识别标志，让Agent根据当前代码重新推导修复方案。“基于质心距离的定向问题从所有方位读取结果都错误”是有效的教学；“所以我们将其基于FRONT_ARC”则会失效。不确定时，只需说明哪里出了问题以及如何发现它即可。

Leading Words

Leading Word

A leading word is a compact concept already in the model's pretraining that the agent thinks with while running the skill (e.g. fog of war, tracer bullets, red, tight). One word recruits priors the model already holds and anchors a whole region of behavior in the fewest tokens.

It anchors execution in the body (same word → same behavior every time) and invocation in the description (when that word also lives in the user's prompts, docs, and code, the skill fires more reliably).
Hunt for restatements that a leading word retires. "fast, deterministic, low-overhead" → a tight loop. "a loop you believe in" → the loop goes red. You win twice: fewer tokens and a sharper hook.
A weak leading word is a no-op (
```
be thorough
```
when the agent already is). The fix is a stronger word (relentless), not more sentences.

Leading Word是模型预训练中已存在的简洁概念，Agent在执行Skill时会依托这些概念进行思考（例如fog of war、tracer bullets、red、tight）。单个词汇就能调动模型已有的先验知识，用最少的Tokens锚定一整套行为模式。

它在正文中锚定执行（相同词汇→每次行为一致），在描述中锚定调用（当该词汇同时出现在用户提示、文档和代码中时，Skill的触发会更可靠）。
寻找可以用Leading Word替代的冗余表述。“快速、确定性、低开销”→tight循环；“你信任的循环”→循环变为red。这样做一举两得：减少Tokens消耗，同时让触发更精准。
无效的Leading Word不会产生任何作用（比如Agent本来就会“be thorough”）。解决方法是使用更强有力的词汇（如relentless），而非增加更多句子。

Invocation

调用方式

Choose how the skill is reached; each choice spends a different cost.

Model-invoked (default): keep a
```
description
```
so the agent can fire it on its own and other skills can reach it. Costs context load — the description sits in the window every turn. Write rich trigger phrasing.
User-invoked: set
```
disable-model-invocation: true
```
. Only the user typing its name can invoke it; zero context load, but the user must remember it exists. The
```
description
```
becomes a human-facing one-liner.

Pick model-invocation only when the agent or another skill must reach it unprompted. When user-invoked skills pile up past memory, add a router skill that names the others and when to reach for each.

选择Skill的调用方式，不同的方式会消耗不同的成本：

模型调用（默认）：保留
```
description
```
，让Agent可以自行触发，其他Skill也能调用它。成本是上下文加载——描述内容会在每次交互时留在上下文窗口中。要编写丰富的触发表述。
用户调用：设置
```
disable-model-invocation: true
```
。只有用户输入Skill名称时才能调用它；无需加载上下文，但用户必须记住它的存在。此时
```
description
```
变为面向人类的单行说明。

仅当Agent或其他Skill需要无提示调用时，才选择模型调用方式。当用户调用的Skill过多超出记忆范围时，添加一个路由Skill，列出其他Skill及其适用场景。

Description

描述规范

The description does two jobs: state what the skill is, and list the distinct situations (branches) that trigger it.

Front-load the leading word — invocation work happens here.
One trigger per branch. Synonyms that rename one branch are duplication; collapse them and keep only genuinely distinct branches.
Cut identity already in the body. Keep triggers plus any "when another skill needs…" reach clause.

描述有两个作用：说明Skill的用途，以及列出触发它的不同场景（分支）。

将Leading Word放在开头——调用逻辑在此处生效。
每个分支对应一个触发条件。属于同一分支的同义词是冗余的，应合并，仅保留真正不同的分支。
删除正文中已有的身份信息。仅保留触发条件以及任何“当其他Skill需要…时”的调用条款。

Information Hierarchy

信息层级

A skill is steps and reference, mixed freely. Rank each piece by how immediately the agent needs it:

In-skill step — an ordered action in
```
SKILL.md
```
. Each ends on a completion criterion: make it checkable (can the agent tell done from not-done?) and, where it matters, exhaustive ("every modified model accounted for", not "produce a change list"). A vague criterion invites premature completion.
In-skill reference — a definition or rule consulted on demand. A flat peer-set of rules is fine, not a smell.
External reference — pushed out of
```
SKILL.md
```
into a linked file, loaded only when its pointer fires.

Keep a concept's definition, rules, and caveats under one heading (co-location) so reading one part brings its neighbors. Push too little down and the top bloats; push too much down and you hide what the agent needs.

Skill由步骤和参考资料混合组成。根据Agent对信息的即时需求程度排序：

Skill内步骤：
```
SKILL.md
```
中的有序操作。每个步骤都有明确的完成标准：要具备可检查性（Agent能否判断是否完成？），必要时还要具备穷尽性（“所有修改的模型都已处理”，而非“生成变更列表”）。模糊的标准会导致提前完成。
Skill内参考资料：按需查阅的定义或规则。扁平的规则集合是可行的，并非问题。
外部参考资料：从
```
SKILL.md
```
移至关联文件中，仅在指针触发时加载。

将一个概念的定义、规则和注意事项放在同一标题下（共置），这样阅读一部分就能关联到相关内容。下放的内容太少会导致顶部过于臃肿；下放太多则会隐藏Agent需要的信息。

When to Split

拆分时机

Each cut spends a cost, so split only when it earns it:

By invocation — split off a model-invoked skill when a distinct leading word should trigger it alone, or another skill must reach it. You pay context load for the new always-loaded description.
By sequence — split a run of steps when the steps still ahead tempt the agent to rush the one in front of it. Hiding later steps forces more work on the current one. The tell is stage compression: several steps' work lands in one message, or the agent narrates a later step as complete without ever having opened it. A "when you enter a step, read its file" pointer in the main skill fires reliably, even on weaker models.

每次拆分都会产生成本，因此仅当收益大于成本时才进行拆分：

按调用方式拆分：当某个独特的Leading Word应单独触发它，或其他Skill需要调用它时，拆分出一个模型调用的Skill。你需要为新的常驻描述支付上下文加载成本。
按流程顺序拆分：当后续步骤会诱使Agent跳过当前步骤时，拆分连续的步骤。隐藏后续步骤能迫使Agent专注于当前步骤。判断标志是阶段压缩：多个步骤的工作被合并到一条消息中，或Agent在未执行后续步骤的情况下就声称其已完成。在主Skill中添加“进入步骤时读取其文件”的指针，即使在较弱的模型上也能可靠触发。

Failure Modes

故障模式

Diagnose a misbehaving skill against these:

Premature completion — ending a step before it's done. Fix the completion criterion first (cheap); only split to hide later steps if the criterion is irreducibly fuzzy and you see the rush. When the skill's job ends in a handover artifact, name it as the only skill-level done-condition — otherwise runs end at whichever intermediate artifact feels finished.
Embargo — an ordered workflow over-obeyed: the agent withholds a finding made early to honor a later step's choreography, so the user decides something while the agent sits on information that bears on it. Any skill that sequences steps needs the escape valve stated: order governs presentation, never disclosure.
Lucky pass — a validation run that succeeds only because the user or world volunteered a critical input unprompted. The outcome was right but the process didn't produce it; encode the eliciting probe as an explicit step instead of banking on the luck recurring.
Duplication — the same meaning in two places. Keep a single source of truth.
Sediment — stale layers that accumulate because adding feels safe. Prune deliberately.
War story — a lesson written as the play-by-play of the change that taught it: function names, tuned values, one bug's trajectory. Those specifics date fast and bury the transferable rule. State the principle and the smell to watch for; let the codebase hold the mechanics. One concrete touchstone grounds it; a paragraph of them drowns it.
Implementation index — a skill that points at today's source files, line numbers, current literals, or exact internal functions when its job is really to teach judgment. Those locators rot and make agents chase old mechanics. Keep durable principles, symptoms, acceptance criteria, and reference assets in the skill; put task-specific implementation notes in the active spec. If code location matters, tell the agent to find the current owner in the codebase.
Sprawl — too long even when every line is live. Cure with the ladder: disclose reference behind pointers, split by branch or sequence.
No-op — a line the model already obeys by default. Test each sentence in isolation; when it fails, delete the whole sentence, don't trim words.

针对以下故障模式诊断运行异常的Skill：

提前完成：步骤未完成就结束。首先优化完成标准（成本低）；仅当标准无法简化且确实存在跳过行为时，才拆分隐藏后续步骤。当Skill的任务以移交工件结束时，将其作为唯一的Skill级完成条件——否则流程会在某个中间工件看起来完成时就结束。
信息封锁：过度遵循有序工作流：Agent提前发现了问题，但为了遵守后续步骤的编排而隐瞒信息，导致用户在做出决策时无法获取相关信息。任何包含步骤顺序的Skill都需要明确的例外规则：顺序仅控制展示方式，绝不限制信息披露。
侥幸通过：验证运行成功仅仅是因为用户或外部环境主动提供了关键输入。结果正确但流程并未主动生成该结果；应将获取该输入的明确步骤编码到Skill中，而非依赖偶然情况。
重复冗余：同一含义出现在两个地方。保持单一数据源。
陈旧堆积：因添加内容看似安全而积累的陈旧层级。要刻意进行修剪。
经验故事：将教训写成某次变更的详细过程：函数名、调整后的值、某个Bug的轨迹。这些细节会很快过时，掩盖可迁移的规则。应陈述原则和需要警惕的问题特征；让代码库保留具体实现细节。一个具体的案例足以支撑原则；过多案例则会淹没核心内容。
实现索引：Skill指向当前的源文件、行号、当前常量或确切的内部函数，而其真正目的是传授判断能力。这些定位信息会过时，导致Agent追逐旧的实现机制。在Skill中保留持久的原则、症状、验收标准和参考资源；将特定任务的实现说明放在当前规范中。如果代码位置很重要，告诉Agent在代码库中查找当前负责人。
内容膨胀：即使每一行都有用，内容仍过长。解决方法是逐步优化：将参考资料放在指针后，按分支或流程拆分。
无操作：模型默认已经遵循的语句。单独测试每一句话；如果它对行为没有影响，就删除整句话，而非删减词汇。

Shape

结构模板

Use this structure unless there is a strong reason not to:

markdown

---
name: short-verb-phrase
description: What this does. Use when ...
---

除非有充分理由，否则使用以下结构：

markdown

---
name: short-verb-phrase
description: What this does. Use when ...
---

Skill Title

One short paragraph defining the job.

Workflow

Do the first load-bearing thing.
Make the key decision.
Produce or verify the artifact.

Do the first load-bearing thing.
Make the key decision.
Produce or verify the artifact.

Rules

Keep the constraints that prevent common mistakes.
Link only the references that should be loaded conditionally.

undefined

Keep the constraints that prevent common mistakes.
Link only the references that should be loaded conditionally.

undefined

Edit Pass

编辑流程

When creating or revising a skill:

Name it with lowercase hyphen-case; keep the folder name identical.
Make the description specific enough to trigger without the body.
Remove any "when to use" section from the body.
Remove stale history, attribution, placeholders, and setup notes.
Remove file paths, line numbers, current constants, and implementation knobs unless the skill is explicitly a code-navigation runbook. Prefer durable principles plus a directive to inspect the current code.
Prefer one strong rule over several overlapping bullets.
Refactor restatements into a leading word where one fits.
Keep examples tiny and realistic.
Add no README, changelog, or auxiliary docs unless they are actual references the skill tells the agent when to read.
Run the skill validator when available.

创建或修订Skill时：

使用小写连字符命名；保持文件夹名称与Skill名称一致。
让描述足够具体，无需正文即可触发。
删除正文中的“使用场景”部分。
删除陈旧的历史记录、署名、占位符和设置说明。
删除文件路径、行号、当前常量和实现参数，除非Skill明确是代码导航手册。优先保留持久原则，加上检查当前代码的指令。
优先使用一条明确的规则，而非多条重叠的项目符号。
如有合适的Leading Word，将冗余表述重构为该词汇。
保持示例简洁且贴近实际。
除非是Skill明确指定Agent何时读取的参考资料，否则不要添加README、变更日志或辅助文档。
如有可用的Skill验证工具，运行它。

Done

完成标准

The skill is done when its metadata triggers correctly, its body is short enough to read in one pass, and a fresh agent can follow it without asking why the skill exists.

当Skill的元数据能正确触发、正文简短到可以一次读完，且全新Agent无需询问Skill存在的原因就能遵循它时，Skill即编写完成。