skill-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Writing

Skill 编写

Skills are bundled instruction modules that load into an agent's context when activated. They are the highest-leverage mechanism for controlling agent behavior because they deliver focused instructions at the moment of relevance.
Skill 是打包的指令模块,激活时会加载到 Agent 的上下文中。它们是控制 Agent 行为时杠杆率最高的机制,因为能在最相关的时机提供聚焦的指令。

The Iron Law

铁律

No skill without a failing test first. Before writing a skill, run a subagent on the target task WITHOUT the skill. Document what it gets wrong — the exact rationalizations, shortcuts, and skipped steps. Then write the skill addressing those specific failures. This is TDD applied to documentation.
TDD StepSkill Equivalent
REDRun scenario without skill. Document what the agent does wrong.
GREENWrite minimal skill addressing those specific failures. Verify agent now complies.
REFACTORFind new rationalizations the agent invents. Close loopholes. Re-test.
先有失败的测试,才能编写 skill。 在编写 skill 之前,先在不使用该 skill 的情况下,让 subagent 执行目标任务。记录它出错的具体情况——确切的合理化借口、走捷径和被跳过的步骤。然后编写 skill 来解决这些具体失败。这就是将 TDD 应用于文档。
TDD 步骤Skill 对应阶段
RED在不使用 skill 的情况下运行场景。记录 Agent 做错了什么。
GREEN编写解决这些具体失败的最小 skill。验证 Agent 现在能够遵循要求。
REFACTOR找出 Agent 编造的新合理化借口。堵住漏洞。重新测试。

When to Create a Skill

何时创建 Skill

Create when: the technique wasn't obvious, you'd reference it across projects, others would benefit, or the agent repeatedly fails without it.
Don't create for: one-off solutions, standard practices documented elsewhere, project-specific conventions (use CLAUDE.md), or mechanical constraints (enforce with linters/hooks instead).
以下情况应创建: 该技巧并不显而易见;你会在多个项目中引用它;其他人也会受益;或者没有它时 Agent 会反复失败。
以下情况不要创建: 一次性解决方案;其他地方已有文档说明的标准实践;项目特定约定(使用 CLAUDE.md);机械性约束(改用 linters/hooks 强制执行)。

Core Principles

核心原则

Instructions are a finite budget. Models reliably follow ~150 instructions. The system prompt burns ~50. Every instruction you add degrades compliance across ALL instructions. Be ruthless about what earns a slot.
Peripheral positions get more attention. First and last sections receive disproportionate attention. Bury a critical rule in the middle and it gets skipped.
Specificity drives compliance. "Consider running audits" gets ignored. "Call
accessibility_audit
before emitting
RUN_COMPLETED
" gets followed.
Unconditional beats conditional. "You MUST call X" works. "When appropriate, consider X" does not.
指令预算是有限的。 模型通常只能可靠遵循约 150 条指令。系统提示词会消耗约 50 条。每增加一条指令,所有指令的遵循率都会下降。对于哪些指令值得占用一个名额,必须毫不留情。
边缘位置会获得更多关注。 首尾章节受到的关注明显更多。如果把关键规则埋在中间,它就会被跳过。
具体性推动遵循。 “可以考虑运行审计”会被忽略。“在输出
RUN_COMPLETED
前必须调用
accessibility_audit
”则会被遵循。
无条件优于有条件。 “必须调用 X”有效。“视情况考虑 X”无效。

Description Optimization

Description 优化

The
description
field controls when the skill activates. The agent reads it to decide: "Should I load this right now?" Describe triggering conditions, not workflow.
Bad:
description: A skill for TDD - write test first, watch it fail, write code
Good:
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently. Covers flaky tests, hanging tests, zombie processes.
Checklist for descriptions:
  • Start with "Use when..." focusing on triggering conditions
  • Include specific symptoms and error messages the user would mention
  • Include synonyms (timeout/hang/freeze, cleanup/teardown/afterEach)
  • Name tools, commands, file types that signal relevance
  • Max 500 characters. Under 200 for frequently-loaded skills
  • Never summarize the skill's process — this causes agents to follow the description instead of loading the full skill
description
字段决定 skill 何时激活。Agent 会读取它来判断:“现在应该加载它吗?”应描述触发条件,而不是工作流程。
不佳:
description: A skill for TDD - write test first, watch it fail, write code
良好:
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently. Covers flaky tests, hanging tests, zombie processes.
Description 检查清单:
  • 以“Use when...”开头,聚焦触发条件
  • 包含用户可能提到的具体症状和错误消息
  • 包含同义词(timeout/hang/freeze、cleanup/teardown/afterEach)
  • 指明能表明相关性的工具、命令和文件类型
  • 最多 500 个字符。经常加载的 skill 应少于 200 个字符
  • 绝不概括 skill 的流程——这会导致 Agent 遵循 description,而不加载完整 skill

Skill Structure

Skill 结构

.agents/skills/<skill-name>/
  SKILL.md          # Required. Under 200 lines.
  references/       # Optional. Heavy reference docs (100+ lines).
.agents/skills/<skill-name>/
  SKILL.md          # Required. Under 200 lines.
  references/       # Optional. Heavy reference docs (100+ lines).

Frontmatter

Frontmatter

yaml
---
name: kebab-case-name
description: Use when [triggering conditions]. Covers [symptoms, tools, keywords].
---
Use verb-first active naming:
creating-skills
not
skill-creation
,
condition-based-waiting
not
async-helpers
.
yaml
---
name: kebab-case-name
description: Use when [triggering conditions]. Covers [symptoms, tools, keywords].
---
使用动词在前、主动语态的命名方式,例如
creating-skills
,而不是
skill-creation
;使用
condition-based-waiting
,而不是
async-helpers
。

Writing Instructions That Get Followed

编写真正会被遵循的指令

Lead with identity, then constraints

先定义身份,再给出约束

One-line role statement, then hard constraints immediately. Do not build up to them.
markdown
undefined
用一行说明角色,然后立即列出硬性约束。不要先铺垫,最后才提到它们。
markdown
undefined

Browser Test Executor

Browser Test Executor

You are executing adversarial browser tests against code changes.
REQUIRED for every test run:
  1. Call accessibility_audit before completing
  2. Call performance_metrics before completing
  3. Call close to flush the session
undefined
You are executing adversarial browser tests against code changes.
REQUIRED for every test run:
  1. Call accessibility_audit before completing
  2. Call performance_metrics before completing
  3. Call close to flush the session
undefined

Use numbered checklists gated on completion

使用以完成为门槛的编号检查清单

Numbered lists signal sequence and completeness. Tie them to whatever marks the task "done."
markdown
Before marking the task complete, you MUST:
1. Run the linter
2. Run the type checker
3. Run the test suite
Do not skip any step. A skipped step is a failed task.
The trailing "do not skip" is not redundant — it closes the escape hatch.
编号列表能传达顺序和完整性。将它们与用于标记任务“完成”的操作绑定。
markdown
Before marking the task complete, you MUST:
1. Run the linter
2. Run the type checker
3. Run the test suite
Do not skip any step. A skipped step is a failed task.
末尾的“不要跳过”并非冗余——它堵住了逃避执行的漏洞。

Name tools and commands exactly

准确指明工具和命令

Never "run the appropriate checks." Always
call accessibility_audit
or
run pnpm typecheck
.
绝不要写“运行适当的检查”。始终写
call accessibility_audit
或
run pnpm typecheck
。

Put mandatory behaviors at the end

将强制行为放在末尾

The last section is the last thing read before acting. Put the non-negotiable checklist there.
最后一个章节是 Agent 行动前最后读到的内容。把不可妥协的检查清单放在那里。

One good example, one bad example

一个正面示例,一个反面示例

Examples are worth more than explanations.
markdown
**Bad:** `test the login page`
**Good:** `Submit login with empty fields, invalid email, wrong password, valid credentials. Verify errors and redirect.`
示例比解释更有价值。
markdown
**Bad:** `test the login page`
**Good:** `Submit login with empty fields, invalid email, wrong password, valid credentials. Verify errors and redirect.`

Bulletproofing Against Rationalization

防范合理化借口

Agents invent reasons to skip rules. Anticipate and close every loophole explicitly.
Close escape hatches: After every mandatory rule, add: "No exceptions for 'just this once', 'it's simple enough', or 'I'll do it next time'."
Build a rationalization table from your RED phase testing. Every excuse the agent made becomes an explicit counter in the skill:
Agent SaysSkill Responds
"This change is too small to test"Every change gets tested. Size is not an exemption.
"I already verified manually"Manual verification is not a substitute. Run the tool.
"The user didn't ask for this"The skill requires it. User silence is not opt-out.
Create a red flags list: "If you catch yourself thinking any of these, stop and follow the checklist."
Agent 会编造跳过规则的理由。预判并明确堵住每一个漏洞。
堵住逃避路径: 在每条强制规则后添加:“不存在‘只这一次’、‘这点改动很简单’或‘我下次再做’之类的例外。”
根据 RED 阶段测试建立合理化借口表: Agent 提出的每个借口,都要在 skill 中配上明确的反驳:
Agent 说Skill 回应
“这次改动太小,不需要测试”每项改动都要测试。改动大小不是豁免理由。
“我已经手动验证过了”手动验证不能替代工具验证。运行工具。
“用户没有要求这样做”skill 要求这样做。用户未提出异议并不等于选择退出。
创建危险信号清单: “如果你发现自己正在想以下任何一项,请停止并遵循检查清单。”

Anti-Patterns

反模式

PatternWhy It Fails
"Consider running X when appropriate"Conditional + vague = ignored
Giant skill files (>200 lines)Exceeds instruction budget, compliance drops
Duplicating CLAUDE.md rulesBurns budget twice for the same instruction
Listing every edge caseShow one example, not twenty — the agent infers the rest
"Be thorough" / "Be careful"Vibes, not instructions. Say what "thorough" means concretely
Multi-paragraph justificationsThe agent needs the rule, not the backstory. One sentence of "why" max
Critical rules in the middleMiddle-of-prompt blindspot. Move to top or bottom
Writing a skill without testing firstYou don't know what failures to address. Delete it, start with RED.
Workflow-summarizing descriptionsAgent follows the summary instead of loading the full skill
模式失败原因
“视情况考虑运行 X”有条件 + 模糊 = 被忽略
巨型 skill 文件(>200 行)超出指令预算,遵循率下降
重复 CLAUDE.md 中的规则同一指令消耗两次预算
列举每一种边缘情况给出一个示例,而不是二十个——Agent 可以推断其余情况
“要全面”/“要谨慎”只讲感觉,不是指令。具体说明“全面”意味着什么
多段理由说明Agent 需要的是规则,而不是背景故事。原因最多用一句话说明
关键规则位于中间提示词中部盲区。移到顶部或底部
未先测试就编写 skill你不知道要解决哪些失败。删除它,从 RED 开始。
概括工作流程的 descriptionAgent 会遵循摘要,而不是加载完整 skill

Checklist: Before Shipping

发布前检查清单

  • Tested without the skill first (RED phase) and documented failures
  • Skill addresses those specific failures, not hypothetical ones
  • Description starts with "Use when..." and lists triggering conditions, not workflow
  • Under 200 lines total
  • Mandatory behaviors in a numbered checklist at top or bottom
  • Every tool/command named exactly — no "appropriate" or "relevant"
  • No hedging ("consider", "when appropriate", "if needed")
  • At least one good/bad example pair
  • No duplication with CLAUDE.md or other skills
  • Escape hatches closed with explicit "no exceptions" language
  • Re-tested with the skill (GREEN phase) and agent now complies
  • 先在没有 skill 的情况下测试(RED 阶段),并记录失败
  • skill 针对的是这些具体失败,而不是假设出来的失败
  • description 以“Use when...”开头,并列出触发条件,而不是工作流程
  • 总行数少于 200 行
  • 顶部或底部有包含强制行为的编号检查清单
  • 每个工具/命令都被准确指明——不使用“适当”或“相关”之类的模糊说法
  • 不使用犹豫措辞(“考虑”“视情况”“如有需要”)
  • 至少包含一组正反示例
  • 不与 CLAUDE.md 或其他 skill 重复
  • 使用明确的“不例外”措辞堵住逃避路径
  • 使用 skill 重新测试(GREEN 阶段),确认 Agent 现在能够遵循要求