Back to Details

writing-great-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

writing-great-skills

writing-great-skills

skill 的读者是模型，不是人。目标只有一个：可预期——每次跑同样的流程（不是同样的输出）。每条规则都为它服务。
Skills are read by models, not humans. There’s only one goal: predictability—running the same process (not the same output) every time. Every rule serves this purpose.

硬规则

Hard Rules

  1. 注释 ≤20 字，逐条说清，不重复，不为对齐加多余空格——版式是给人看的，模型只读内容。
  2. 删掉后行为不变的句子 = 废话句（no-op），整句删，别改写。默认模型已经很聪明：每段自问"这句值它的 token 吗"。
  3. 同一个意思只写一次（单一事实源），改行为只改一处。
  4. 写正向指令，不写禁令——"别 X"让模型满脑子 X；说清该做什么，X 自然不发生。硬约束除外，且必须配上"那该怎么做"。
  5. 用领衔词：挑一个模型预训练里已有的紧凑概念（如 收尾、拐点、探针）当锚点，一个词替代一长串解释。
  6. 能用正则/校验/脚本机械强制的，自动化掉，别写成文档——文档留给判断题。
  1. Comments ≤20 characters, clear per item, no repetition, no extra spaces for alignment—formatting is for humans; models only read content.
  2. Sentences that don’t change behavior when removed = no-op sentences, delete the entire sentence, don’t rewrite it. Assume the model is already smart: for each paragraph, ask yourself "Is this sentence worth its token?"
  3. Write the same meaning only once (single source of truth); modify behavior in only one place.
  4. Write positive instructions, not prohibitions—"Don’t do X" makes the model fixate on X; clarify what to do, and X won’t happen naturally. Except for hard constraints, which must be paired with "What to do instead."
  5. Use leading terms: Pick a compact concept already in the model’s pre-training (e.g., wrap-up, inflection point, probe) as an anchor, replacing a long explanation with one word.
  6. Automate anything that can be enforced mechanically with regex/validation/scripts; don’t write it into documentation—documentation is for judgment-based tasks.

结构与预算

Structure & Budget

  • SKILL.md
    只放每条分支都用到的：规则 + 常用命令/步骤。步骤必须带完成判据——可检查、能分清做完/没做完。
  • 预算：SKILL.md 正文 <500 行（官方上限建议）；高频常驻 skill 压到 200 词内。超了就把细节挪进 
    references/xx.md
    。
  • 指针写清"什么时候去读它"比"它在哪"更重要；引用链只一层深（SKILL.md → references，不再下钻）。
  • 取舍标准：这条内容多少分支要用。全堆顶层 = 臃肿；常用的藏进指针 = 藏拙。
  • SKILL.md
    only contains content used by every branch: rules + common commands/steps. Steps must include completion criteria—checkable, clear distinction between done and not done.
  • Budget: SKILL.md body <500 lines (official upper limit recommendation); high-frequency resident skills kept under 200 words. If exceeded, move details to 
    references/xx.md
    .
  • For pointers, clarifying "when to read it" is more important than "where it is"; reference chains are only one level deep (SKILL.md → references, no further drilling).
  • Trade-off criteria: How many branches use this content. Piling everything at the top = bloated; hiding commonly used content in pointers = poor usability.

frontmatter

frontmatter

  • name
    （必填）：1-64 字符，小写字母/数字/连字符，与目录名一致。
  • description
    （必填）：≤1024 字符，写法见下节。
  • 可选：
    compatibility
    （环境要求）、
    metadata
    （键值对，如 
    requires.bins
    ）、
    allowed-tools
    （预批工具，实验性）、
    license
    。
  • 不想让模型自动触发就设 
    disable-model-invocation: true
    （只认人类点名），description 随之变成给人看的一句话。
  • name
    (required): 1-64 characters, lowercase letters/numbers/hyphens, must match the directory name.
  • description
    (required): ≤1024 characters, see the next section for writing guidelines.
  • Optional: 
    compatibility
    (environment requirements), 
    metadata
    (key-value pairs, e.g., 
    requires.bins
    ), 
    allowed-tools
    (pre-approved tools, experimental), 
    license
    .
  • To prevent automatic invocation by models, set 
    disable-model-invocation: true
    (only responds to human calls), and the description becomes a human-readable sentence.

description（触发面）

description (Trigger Surface)

  • 结构 = 干什么（一句）+ 何时用（触发条件），第三人称。
  • 绝不概括工作流程——实测：description 写了流程，agent 就照着摘要做、不读正文（"任务间做 code review"让 agent 把两阶段评审干成了一阶段）。正文因此形同虚设。
  • 触发语写症状和场景（"race condition、时序依赖、时好时坏"），一分支一条；同义改写 = 同一分支写两遍，删。
  • 命名用动名词/动词开头（
    creating-skills
    不是 
    skill-creation
    ）。
  • Structure = what to do (one sentence) + when to use it (trigger conditions), in the third person.
  • Never summarize the workflow—actual testing shows: if the description includes the workflow, the agent will follow the summary instead of reading the body (e.g., "Do code review between tasks" made the agent turn a two-stage review into a single stage). This renders the body useless.
  • Trigger terms describe symptoms and scenarios (e.g., "race condition, timing dependency, intermittent issues"), one per branch; synonymous rewrites = writing the same branch twice, delete them.
  • Naming starts with gerunds/verbs (e.g., 
    creating-skills
    instead of 
    skill-creation
    ).

自由度（按任务脆弱度给指令强度）

Flexibility (Match Instruction Strength to Task Fragility)

  • 高自由（文字指引）：多条路都行、靠判断——如 code review。
  • 中自由（带参模板）：有推荐模式、允许变体——如报告生成。
  • 低自由（精确脚本/命令）：操作易碎、顺序必须严格——如数据库迁移。写死并注明"不要改命令、不要加参数"。
  • 类比：悬崖窄桥给护栏（低自由），旷野给方向（高自由）。给错档 = 要么束手束脚，要么步步惊心。
  • High flexibility (written guidelines): Multiple valid paths, relies on judgment—e.g., code review.
  • Medium flexibility (parameterized templates): Recommended patterns allowed with variations—e.g., report generation.
  • Low flexibility (precise scripts/commands): Fragile operations, strict sequence required—e.g., database migration. Write it verbatim and note "Do not modify the command, do not add parameters."
  • Analogy: Guardrails for narrow bridges over cliffs (low flexibility), directions for open fields (high flexibility). Choosing the wrong level = either overly restrictive or high-risk.

验证（写完必须做，不然等于没写）

Validation (Mandatory After Writing, Otherwise It’s Unfinished)

没看过 agent 不用这个 skill 时翻车，就不知道 skill 教没教对。照 TDD 循环来：
  1. 基线（红）：不装 skill，让 agent 跑真实场景，记录它怎么错、怎么自我合理化。
  2. 写 skill（绿）：只针对观察到的那些错法写，装回去重跑，确认合规。
  3. 补漏洞（重构）：换说法再压测，发现新的钻空子方式就补上，直到撬不动。
多模型共用时要逐个模型测：Opus 嫌啰嗦的，Haiku 可能嫌没说清。
You can’t know if a skill is correct unless you’ve seen the agent fail without using it. Follow the TDD cycle:
  1. Baseline (Red) : Run the agent in real scenarios without the skill installed, record how it fails and how it rationalizes its mistakes.
  2. Write the skill (Green) : Only write for the observed failure patterns, reinstall and re-run to confirm compliance.
  3. Fix vulnerabilities (Refactor) : Re-test with alternative phrasings, fix any new loopholes found until no more can be exploited.
When shared across multiple models, test each one individually: What Opus finds verbose, Haiku might find unclear.

常见病（诊断用）

Common Issues (For Diagnosis)

  • 提前完成：步骤没做完就想收工。先磨利完成判据；还不行就把后续步骤藏出视野。
  • 重复：同一意思多处写，维护与 token 双份。
  • 沉积：只敢加不敢删攒出的死层——没有修剪纪律的 skill 的默认结局。
  • 蔓延：每行都活着但整体太长。用结构治（references / 指针 / 拆分）。
  • 废话：见硬规则 2。
  • 否定：见硬规则 4。
  • 摘要替代正文：见 description 节——病因在触发面写流程。
  • Premature completion: Tries to finish before steps are done. First refine the completion criteria; if that doesn’t work, hide subsequent steps from view.
  • Redundancy: Same meaning written in multiple places, double maintenance and token cost.
  • Accumulation: Dead layers built up from only adding content and never deleting—the default outcome of skills without pruning discipline.
  • Bloat: Every line is useful but the whole is too long. Fix with structure (references / pointers / splitting).
  • No-op sentences: See Hard Rule 2.
  • Prohibitions: See Hard Rule 4.
  • Summary replaces body: See the Description section—root cause is writing workflows in the trigger surface.

来源

Sources

Anthropic 官方 best practices、agentskills.io 规范、obra/superpowers writing-skills（TDD 验证回路出处），2026-08-15 调研。
Anthropic official best practices, agentskills.io standards, obra/superpowers writing-skills (source of TDD validation loop), researched on 2026-08-15.