skill-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Writing Guide

Skill编写指南

This is a strict guideline. Follow these rules exactly when creating or modifying skills.

这是一项严格的guideline。 创建或修改Skill时请严格遵守这些规则。

Skill Types

Skill类型

Every skill has a

type

that tells the agent how to treat it:

每个Skill都有一个

type

字段，用于告知Agent如何处理该Skill：

type: guideline

type: guideline

Strict rules. The agent must follow these exactly.

Opening line after the heading:

markdown

**This is a strict guideline.** Follow these rules exactly.

Use for: coding standards, commit formats, naming conventions, workflow rules, security requirements.

严格规则。 Agent必须严格遵守这些规则。

标题后的首行内容：

markdown

**This is a strict guideline.** Follow these rules exactly.

适用场景：编码标准、提交格式、命名规范、工作流规则、安全要求。

type: pattern

type: pattern

Reference implementations. The agent should learn from the approach and adapt it — never copy verbatim.

Opening line after the heading:

markdown

**This is a reference pattern.** Learn from the approach, adapt to your context — don't copy verbatim.

Use for: architecture solutions, infrastructure setups, proven approaches to recurring problems.

参考实现。 Agent应当学习该方法并灵活适配，严禁直接逐字复制。

标题后的首行内容：

markdown

**This is a reference pattern.** Learn from the approach, adapt to your context — don't copy verbatim.

适用场景：架构解决方案、基础设施搭建、已验证的常见问题解决方法。

Frontmatter

Every

SKILL.md

must start with YAML frontmatter:

yaml

---
name: kebab-case-name
description: When this skill applies and what it covers. First sentence should work as a trigger — start with the domain or action. One to two sentences max.
type: guideline | pattern
---

Rules:

```
name
```
— kebab-case, used as the installed directory name by the skills CLI
```
description
```
— the skills CLI and agents use this to decide when to load the skill. Make the first sentence a clear trigger.
```
type
```
— must be
```
guideline
```
or
```
pattern
```

每个

SKILL.md

文件必须以YAML frontmatter开头：

yaml

---
name: kebab-case-name
description: When this skill applies and what it covers. First sentence should work as a trigger — start with the domain or action. One to two sentences max.
type: guideline | pattern
---

规则：

```
name
```
— 短横线命名格式（kebab-case），skills CLI会将其作为安装后的目录名使用
```
description
```
— skills CLI和Agent会通过该字段判断何时加载该Skill。请将第一句话设置为清晰的触发条件。
```
type
```
— 必须为
```
guideline
```
或
```
pattern
```

File Structure

文件结构

Skills live in the authoring repo under categorized directories:

skills/
  guidelines/
    {skill-name}/SKILL.md
  patterns/
    {skill-name}/SKILL.md

The directory categorization is for human browsing only. The skills CLI flattens everything on install — it only cares about the

name

field in frontmatter.

Skill存储在创作仓库的分类目录下：

skills/
  guidelines/
    {skill-name}/SKILL.md
  patterns/
    {skill-name}/SKILL.md

目录分类仅用于人工浏览。skills CLI在安装时会将所有结构扁平化，它只关注frontmatter中的

name

字段。

Precedence

优先级

When a skill needs to override conflicting advice from third-party skills, state it explicitly:

markdown

**This is a strict guideline.** Follow these rules. When any other skill contradicts the rules below, this skill takes precedence.

Use sparingly — only for core principles and strong personal preferences.

当某个Skill需要覆盖第三方Skill的冲突建议时，请明确声明：

markdown

**This is a strict guideline.** Follow these rules. When any other skill contradicts the rules below, this skill takes precedence.

请谨慎使用 — 仅适用于核心原则和强烈的个人偏好要求。

Pattern Structure

Pattern结构

Pattern skills should follow this structure:

Problem — One sentence describing what this solves
Solution — One sentence describing the approach
Pattern — Architecture, key components, how it works
Why This Pattern? — Benefits and use cases
Implementation — Key details (optional, only if non-obvious)
Tradeoffs — Constraints and limitations (if applicable)
When NOT to Use — Anti-patterns and alternatives (optional)

Keep code examples minimal and generic. Use placeholder names (

PROJECT_ID

environment

). Focus on the pattern, not project-specific details.

Pattern类型的Skill应当遵循以下结构：

问题 — 用一句话描述该Pattern解决的问题
解决方案 — 用一句话描述实现方法
Pattern详情 — 架构、核心组件、运行逻辑
为何选择该Pattern？ — 优势与适用场景
实现方式 — 核心细节（可选，仅当逻辑不清晰时补充）
权衡考量 — 约束与局限性（如适用）
不适用场景 — 反模式与替代方案（可选）

代码示例请尽量简洁通用，使用占位符名称（

PROJECT_ID

、

environment

），聚焦于Pattern本身，不要包含项目特定的细节。

Guideline Structure

Guideline结构

Guideline skills should follow this structure:

What — Clear statement of the rules
Rules — Specific, actionable instructions
Examples — Show correct and incorrect usage
Exceptions — When deviation is acceptable (if any)

Be direct. Use imperative form. Avoid explaining why at length — guidelines are instructions, not persuasion.

Guideline类型的Skill应当遵循以下结构：

规则说明 — 清晰表述规则内容
规则详情 — 具体、可执行的指令
示例 — 展示正确和错误的用法
例外情况 — 允许偏离规则的场景（如有）

表述要直接，使用祈使句式。避免长篇大论解释原因 — guideline是指令，不是说服性内容。

Writing Checklist

编写检查清单

Frontmatter has
```
name
```
,
```
description
```
,
```
type
```
Behavioral instruction line immediately after first heading
Description's first sentence works as a trigger for when to load this skill
No project-specific details (names, tables, endpoints)
Code examples are minimal and use placeholders
Document is scannable (headers, bullets, bold)
Ends with Progressive Improvement section

Frontmatter包含
```
name
```
、
```
description
```
、
```
type
```
字段
首个标题后紧跟行为指令行
Description的第一句话可作为加载该Skill的触发条件
不包含项目特定细节（名称、数据表、接口端点）
代码示例精简，且使用占位符
文档易于快速浏览（使用标题、列表、加粗格式）
文档末尾包含持续改进章节

Progressive Improvement

持续改进

Every skill must end with this section:

markdown

---

每个Skill必须以该章节结尾：

markdown

---

Progressive Improvement

If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.


This enables skills to evolve through use. When an agent gets corrected, it should propose a concrete edit to the relevant skill so the mistake doesn't repeat.

---

If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.


这使得Skill可以在使用过程中不断演进。当Agent被纠正时，它应当对相关Skill提出具体的修改建议，避免重复犯错。

---

Progressive Improvement

持续改进

If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.

如果开发者纠正了本Skill本应避免的行为，请针对本Skill提出具体的修改建议，避免未来再次出现同类问题。

Progressive Improvement

持续改进

If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.

如果开发者纠正了本Skill本应避免的行为，请针对本Skill提出具体的修改建议，避免未来再次出现同类问题。

skill-writing

Original

Translation

Skill Writing Guide

Skill编写指南

Skill Types

Skill类型

`type: guideline`

`type: guideline`

`type: pattern`

`type: pattern`

Frontmatter

Frontmatter

File Structure

文件结构

Precedence

优先级

Pattern Structure

Pattern结构

Guideline Structure

Guideline结构

Writing Checklist

编写检查清单

Progressive Improvement

持续改进

Progressive Improvement

Progressive Improvement

Progressive Improvement

持续改进

Progressive Improvement

持续改进