how-to-write-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

How To Write AI Skills

如何编写AI技能

Overview

概述

Write skills as compact, reusable guidance for a smart and capable model.

Default to a self-contained

SKILL.md

. Keep the skill portable, concise, and easy to trigger.

将技能编写为针对智能模型的简洁、可复用指南。

默认采用独立的

SKILL.md

文件。确保技能具备可移植性、简洁性且易于触发。

Default Approach

默认方法

Prefer one self-contained
```
SKILL.md
```
.
Keep the skill high level by default. Give recommendations, decision rules, and good defaults rather than rigid scripts.
Use strict rigid step-by-step instructions only when the user explicitly asks for them or the task is fragile enough that ambiguity is likely to cause failure.
Avoid teaching basics the model already knows.
If the skill is growing too large, first cut repetition and boilerplate. If it is still too large, move heavy reference material or reusable tools into separate files only when they are clearly justified. Split into multiple skills only when the responsibilities are genuinely different.

优先使用单个独立的
```
SKILL.md
```
文件。
默认保持技能的高抽象层级。提供建议、决策规则和优质默认方案，而非僵化的脚本。
仅当用户明确要求，或任务足够脆弱、模糊性可能导致失败时，才使用严格的分步指令。
避免教授模型已掌握的基础知识。
若技能内容过于庞大，首先删除重复内容和模板代码。若仍过大，仅在确有必要时，将大量参考资料或可复用工具移至单独文件。仅当职责明确不同时，才将技能拆分为多个部分。

Frontmatter

Use portable frontmatter first.

```
name
```
: lowercase kebab-case, matches the directory name.
```
description
```
: say what the skill does and when to use it.
Prefer folded YAML such as
```
description: >-
```
instead of one very long line.

Hard constraints:

Keep
```
description
```
within the platform's limits.
```
1024
```
characters is a safe default.
Avoid XML angle brackets in frontmatter.
Do not use reserved names such as
```
claude
```
or
```
anthropic
```
in the skill name.
Use
```
compatibility
```
only for concrete platform or environment requirements, not as a general slogan.

Write

description

for discovery, not for marketing.

Assume the agent usually sees the directory name,
```
name
```
, and
```
description
```
before invocation.
Assume the body is mainly post-invocation guidance.
Put invocation guidance in
```
description
```
, not in the body.
Keep
```
description
```
focused on when to load. Put detailed instructions and decision rules in the body.
Put the main use case early.
Include words users would actually say.
Mention concrete tasks, artifacts, file types, symptoms, or domains when relevant.
Keep it specific enough to trigger correctly, but not so narrow that it misses obvious paraphrases.
Keep it trigger-oriented. State the outcome and when to use the skill, but do not stuff it with workflow steps or process summaries.
A strong default is a two-part description: first sentence gives the trigger, second sentence packs in task, domain, artifact, and tool keywords.

Good pattern:

yaml

description: Helps create portable, self-contained agent skills with clear frontmatter and strong discoverability. Use when creating or editing a SKILL.md, refining skill instructions, or improving skill triggering.

Another good pattern:

yaml

description: >-
  ALWAYS LOAD THIS SKILL WHEN ADDING LOGGING, CONFIGURING LOG OUTPUT, OR SETTING UP COLORLOG.
  Do not configure Python logging directly — use this skill first. Python logging, stdout/stderr behavior, rotating files, CLI vs GUI/server output.

Bad patterns:

yaml

description: Helps with skills.
description: Use when doing agent things.
description: Writes the perfect skill by following a strict 12-step workflow with validation gates and advanced optimization.

首先使用可移植的Frontmatter。

```
name
```
：小写短横线命名格式（kebab-case），与目录名称一致。
```
description
```
：说明技能的功能及适用场景。
优先使用折叠式YAML格式，例如
```
description: >-
```
，而非超长单行文本。

硬性约束：

确保
```
description
```
符合平台限制。默认1024字符是安全上限。
Frontmatter中避免使用XML尖括号。
技能名称中不得使用保留名称，如
```
claude
```
或
```
anthropic
```
。
仅当存在具体平台或环境要求时，才使用
```
compatibility
```
字段，勿将其用作通用口号。

编写

description

时以可发现性为目标，而非营销目的。

假设Agent通常会在调用前看到目录名称、
```
name
```
和
```
description
```
。
假设正文主要是调用后的指导内容。
将调用指导放入
```
description
```
，而非正文。
```
description
```
聚焦于加载时机，详细指令和决策规则放入正文。
将主要用例放在开头。
包含用户实际会使用的表述。
相关时提及具体任务、工件、文件类型、问题症状或领域。
表述需足够具体以确保正确触发，但又不能过于狭窄而错过明显的同义表述。
以触发为导向。说明预期结果及适用场景，但不要堆砌工作流步骤或流程摘要。
优质的默认模式分为两部分：第一句说明触发条件，第二句涵盖任务、领域、工件和工具关键词。

优秀示例：

yaml

description: Helps create portable, self-contained agent skills with clear frontmatter and strong discoverability. Use when creating or editing a SKILL.md, refining skill instructions, or improving skill triggering.

另一个优秀示例：

yaml

description: >-
  ALWAYS LOAD THIS SKILL WHEN ADDING LOGGING, CONFIGURING LOG OUTPUT, OR SETTING UP COLORLOG.
  Do not configure Python logging directly — use this skill first. Python logging, stdout/stderr behavior, rotating files, CLI vs GUI/server output.

不良示例：

yaml

description: Helps with skills.
description: Use when doing agent things.
description: Writes the perfect skill by following a strict 12-step workflow with validation gates and advanced optimization.

Writing the Body

正文编写

Keep the body short and load-bearing.

Start with the core principle and default approach.
Explain non-obvious constraints, heuristics, or patterns.
Prefer compact sections and short examples over long theory.
Give one-two good defaults, not five equal options.
If you include examples, make them realistic and directly reusable.

Optional sections that often help:

```
Overview
```
```
Default Approach
```
```
Frontmatter
```
or equivalent configuration guidance
```
Core Workflow
```
or
```
Decision Rules
```
```
Common Mistakes
```

保持正文简短且核心内容突出。

从核心原则和默认方法开始。
解释非显而易见的约束、启发式规则或模式。
优先使用简洁的章节和简短示例，而非冗长的理论。
提供1-2个优质默认方案，而非5个同等选项。
若包含示例，需确保示例真实且可直接复用。

通常有用的可选章节：

```
Overview
```
（概述）
```
Default Approach
```
（默认方法）
```
Frontmatter
```
或等效配置指导
```
Core Workflow
```
（核心工作流）或
```
Decision Rules
```
（决策规则）
```
Common Mistakes
```
（常见错误）

Discoverability

可发现性

Discovery is part of the skill design.

When writing

name

and

description

, optimize for how another agent will find the skill later.

Treat loading and behavior as separate design problems.
The
```
description
```
should help the skill load for the right tasks.
The body should tell the agent how strongly to apply the skill once loaded.
Some skills should load broadly but apply flexibly. Others should load narrowly and be followed rigidly.

Important: body text cannot rescue a skill that did not load. If a rule is about invocation, trigger scope, or when to reach for the skill, put it in

description

Example: an

advanced-repo-research

skill should load for all

inspect upstream source

requests, but explain the agent when to use simple research vs advanced.

Use descriptive names with real task words.
Cover likely synonyms.
Include concrete trigger phrases when they help.
Mention failure symptoms when the skill addresses a problem.
Mention specific tools, libraries, file types, or domains only when they are truly part of the trigger.
Prefer literal task-shaped names and descriptions over abstract goals.
Hard directives like
```
ALWAYS LOAD THIS SKILL WHEN X
```
are useful when you need to ensure a skill is consistently loaded for a clearly scoped class of work.
Scope
```
X
```
tightly enough to avoid bad matches.
Pair it with a second sentence such as
```
Do not do Y directly — read this skill first
```
when you need to steer the agent away from bypassing the skill.

Example:

ALWAYS LOAD THIS SKILL WHEN WORKING WITH PYSIDE6, QT, OR DESKTOP GUI CODE. Do not review or write PySide6 or Qt code directly — use this skill first.

Think in terms of search terms an agent might match:

user requests:

create skill

start backend

proceed to plan

artifacts:
```
SKILL.md
```
,
```
frontmatter
```

problems:

does not trigger

too vague

loads too often

goals:
```
portable
```
,
```
discoverable
```
,
```
self-contained
```

Undertriggering signs:

The skill does not load for obvious requests.
Agents keep asking for guidance the skill should already provide.
You need to invoke it manually for common matching tasks.

Overtriggering signs:

The skill loads for adjacent but different tasks.
The description is broad enough to match generic writing or documentation work.

If triggering is wrong, refine the description before adding more body text.

Also verify that the skill is discoverable from the expected directory layout for the target agents. For supported agent paths, check:

https://github.com/vercel-labs/skills#supported-agents

可发现性是技能设计的一部分。

编写

name

和

description

时，需优化以便其他Agent日后能找到该技能。

将加载逻辑和行为视为独立的设计问题。
```
description
```
应帮助技能针对正确的任务加载。
正文应告知Agent加载后如何灵活应用技能。
部分技能应广泛加载但灵活应用，其他技能应窄范围加载且严格遵循。

重要提示：正文内容无法挽救未加载的技能。若规则涉及调用、触发范围或何时使用该技能，需放入

description

。

示例：

advanced-repo-research

技能应针对所有

inspect upstream source

请求加载，但需向Agent说明何时使用简单研究 vs 高级研究。

使用包含真实任务词汇的描述性名称。
覆盖可能的同义词。
必要时包含具体触发短语。
当技能用于解决问题时，提及故障症状。
仅当工具、库、文件类型或领域确实属于触发条件的一部分时，才提及它们。
优先使用字面化的任务型名称和描述，而非抽象目标。
当需要确保技能针对明确范围的工作一致加载时，使用
```
ALWAYS LOAD THIS SKILL WHEN X
```
这类硬性指令非常有用。
需严格限定
```
X
```
的范围，避免错误匹配。
当需要引导Agent避免绕过该技能时，可搭配第二句表述，如
```
Do not do Y directly — read this skill first
```
。

示例：

ALWAYS LOAD THIS SKILL WHEN WORKING WITH PYSIDE6, QT, OR DESKTOP GUI CODE. Do not review or write PySide6 or Qt code directly — use this skill first.

从Agent可能匹配的搜索词角度思考：

用户请求：

create skill

、

start backend

、

proceed to plan

工件：
```
SKILL.md
```
、
```
frontmatter
```

问题：

does not trigger

、

too vague

、

loads too often

目标：
```
portable
```
、
```
discoverable
```
、
```
self-contained
```

触发不足的迹象：

针对明显的请求，技能未加载。
Agent持续询问该技能本应提供的指导。
针对常见匹配任务，需手动调用该技能。

触发过度的迹象：

技能针对相关但不同的任务加载。
描述过于宽泛，匹配通用写作或文档工作。

若触发逻辑存在问题，需先优化

description

，再添加更多正文内容。

同时需验证技能在目标Agent的预期目录结构中是否可发现。如需查看支持的Agent路径，请访问：

https://github.com/vercel-labs/skills#supported-agents

Verification

验证

Do not turn verification into ritual.

For simple skills, a small careful read by separate subagent is usually enough.

Match the verification effort to the risk. Use stronger checks when the main failure mode is triggering, discoverability, or behavior in realistic agent workflows.

Example: a tiny wording cleanup may only need a careful read, while a trigger-sensitive skill should usually get at least one realistic invocation test.

Use stronger verification only when the skill contains:

non-trivial scripts or other code
complex instructions
brittle workflows
decision logic that could be misread

In those cases:

Start with a cheap check: try a few prompts that should trigger the skill and a few that should not.
If the environment supports it, have a subagent or fresh reviewer try to use or review the skill.
Look at where the skill was misunderstood, skipped, or interpreted too narrowly or too broadly.
Fix the skill.
Repeat if the first verification exposed meaningful problems.

For skills where triggering matters, a realistic invocation test is often the most useful check:

give a fresh agent a plausible task
do not over-specify the workflow unless that is part of the requirement
see whether the skill loads or is disclosed naturally
check whether it changed the behavior you cared about, such as tool choice, escalation, or reporting

Example: ask a fresh agent to research an upstream package behavior from real sources, instruct it to report used skills and see whether it will use

advanced-repo-research

practices or not.

The goal is not formal TDD. The goal is to confirm that another agent can understand and apply the skill. And that it's instructions are correct.

勿将验证变成形式主义。

对于简单技能，通常由独立子Agent仔细阅读即可。

验证力度需与风险匹配。当主要故障模式为触发、可发现性或在真实Agent工作流中的行为时，需使用更严格的检查。

示例：微小的措辞调整可能仅需仔细阅读，而对触发敏感的技能通常至少需要一次真实调用测试。

仅当技能包含以下内容时，才使用更严格的验证：

非琐碎脚本或其他代码
复杂指令
脆弱的工作流
可能被误读的决策逻辑

在这些情况下：

先进行低成本检查：尝试几个应触发技能的提示和几个不应触发的提示。
若环境支持，让子Agent或新审阅者尝试使用或审核该技能。
查看技能被误解、跳过或解读过窄/过宽的地方。
修复技能。
若首次验证发现重大问题，重复上述步骤。

对于触发逻辑重要的技能，真实调用测试通常是最有用的检查方式：

给新Agent一个合理的任务
除非是需求的一部分，否则不要过度指定工作流
观察技能是否自然加载或被调用
检查是否改变了相关行为，如工具选择、升级或报告方式

示例：让新Agent从真实来源研究上游包的行为，指示其报告使用的技能，查看是否会采用

advanced-repo-research

的实践。

目标并非正式的测试驱动开发（TDD），而是确认其他Agent能够理解并应用该技能，且其指令正确。

When Extra Files Make Sense

何时需要额外文件

Default answer: they usually do not.

Keep the skill self-contained unless an extra file is meaningfully better outside the main markdown.

Good reasons:

executable scripts
templates the agent should fill in
structured data or large tables better kept as data files
external mutable artifacts that are part of the workflow, eg credentials.txt

Weak reasons:

optional reading
extra theory
long examples that can be shortened
reference docs that duplicate the main skill or are not explicitly linked from
```
SKILL.md
```

If the skill depends on another file, say so explicitly and make the dependency obvious.

默认答案：通常不需要。

保持技能独立，除非额外文件在主markdown之外能带来显著优势。

合理理由：

可执行脚本
Agent需填写的模板
更适合作为数据文件的结构化数据或大型表格
工作流中的外部可变工件，例如credentials.txt

不合理理由：

可选阅读材料
额外理论内容
可简化的冗长示例
重复主技能内容或未从
```
SKILL.md
```
明确链接的参考文档

若技能依赖其他文件，需明确说明并使依赖关系清晰可见。

Platform-Specific Notes

平台特定说明

Platform means "AI agent program", eg claude code, opencode or codex.

Default to standard frontmatter for portability.

Only add platform-specific fields when the task clearly needs platform-specific behavior such as invocation control, subagent execution, tool permissions, or argument substitution.

Check current docs for the target host before adding those fields.

Useful references:

Claude Code:

https://docs.anthropic.com/en/docs/claude-code/skills

OpenCode:
```
https://opencode.ai/docs/skills
```

If portability matters, keep the core skill useful even after those fields are removed.

平台指“AI Agent程序”，例如claude code、opencode或codex。

默认使用标准Frontmatter以确保可移植性。

仅当任务明确需要平台特定行为（如调用控制、子Agent执行、工具权限或参数替换）时，才添加平台特定字段。

添加这些字段前，请查看目标宿主的最新文档。

有用参考：

Claude Code:

https://docs.anthropic.com/en/docs/claude-code/skills

OpenCode:
```
https://opencode.ai/docs/skills
```

若可移植性重要，需确保即使移除这些字段，核心技能仍有用。

Common Mistakes

常见错误

Explaining basics instead of the non-obvious parts.
Writing a vague description that never triggers.
Writing a broad description that triggers on unrelated tasks.
Turning guidance into a rigid workflow without need.
Splitting a small skill into too many files.
Keeping a bloated skill instead of cutting or splitting it.
Adding platform-specific frontmatter by habit instead of need.
Assuming the agent will read optional extra files just because they exist.

解释基础知识而非非显而易见的内容。
编写模糊的描述，导致技能从未触发。
编写宽泛的描述，导致技能针对无关任务触发。
不必要地将指导内容变成僵化的工作流。
将小型技能拆分为过多文件。
保留臃肿的技能，而非精简或拆分。
习惯性添加平台特定Frontmatter，而非按需添加。
假设Agent会阅读可选的额外文件，仅仅因为它们存在。

Final Check

最终检查

Before finishing, quickly confirm:

The skill is still concise.
```
name
```
and directory name match.
```
description
```
states what the skill does and when to use it.
The core instructions are self-contained.
Extra files are absent unless they serve a clear purpose.
Verification level matches the skill's complexity.

完成前，快速确认：

技能仍保持简洁。
```
name
```
与目录名称一致。
```
description
```
说明了技能的功能及适用场景。
核心指令独立完整。
无额外文件，除非它们有明确用途。
验证力度与技能复杂度匹配。