write-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing for agents is test-first development applied to prose. The same loop ships every document an agent reads: skills, AGENTS.md, CLAUDE.md, system prompts.

Baseline first: run the scenario the document targets on an agent WITHOUT it, and record exactly how it fails or rationalizes. No observed failure means the document has nothing to teach.
Write the minimum prose that fixes those specific failures. Not a manual: the shortest process that changes the behavior.
Re-run the scenario with the document loaded. It passes or the document is wrong.
Close loopholes: new rationalizations found on re-runs get plugged, then verified again.

A test harness changes mechanics, not the loop: when one exists, automate the baseline re-run.

Conventions for skills in this repo:

Frontmatter carries
```
name
```
(letters, digits, hyphens) and
```
description
```
. The description states when to fire, with trigger phrasing ("Use when..."), not a summary of the process.
```
disable-model-invocation: true
```
only for skills that must never fire on their own; the description then reads as a human-facing one-liner.
Keep SKILL.md lean. Separate files only for heavy reference or reusable assets; link them relatively.
No em dashes. Decisive present tense. Zero upstream or status mentions.

Skip it when the work is a one-off, when standard practice is already well documented, or when a linter or hook could enforce the rule mechanically.

为Agent编写文本是将测试优先开发理念应用于文案创作。Agent读取的所有文档（skill、AGENTS.md、CLAUDE.md、系统提示词）都遵循相同的发布流程：

先建立基准：在不加载目标文档的情况下，让Agent运行文档针对的场景，并准确记录其失败或合理化解释的情况。如果未观察到失败，说明该文档没有可传授的内容。
编写能修复这些特定失败的最简文本。不要写成手册：只需用最短的流程来改变Agent的行为。
加载文档后重新运行场景。场景通过则文档有效，否则文档存在问题。
填补漏洞：重新运行中发现的新合理化解释需要被修正，然后再次验证。

测试工具会改变实现机制，但流程不变：当有测试工具时，可自动化基准重运行步骤。

本仓库中skill的编写规范：

前置元数据需包含
```
name
```
（仅允许字母、数字、连字符）和
```
description
```
。描述需说明触发时机，使用触发句式（“适用于……”），而非流程概述。
仅当skill绝对不能自行触发时，才设置
```
disable-model-invocation: true
```
；此时描述需写成面向人类的单行说明。
保持SKILL.md简洁。仅在需要大量参考内容或可复用资源时使用单独文件；使用相对路径链接这些文件。
禁止使用破折号。使用明确的一般现在时。不得提及上游依赖或状态信息。

以下情况可跳过此流程：工作为一次性任务、标准实践已有完善文档、或规则可通过代码检查工具（linter）或钩子（hook）进行机械性强制执行。