agent-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Skills

Agent Skills are folders of instructions, scripts, and resources that agents discover and load on demand. This skill covers creating, modifying, and reviewing skills to ensure they follow the specification and best practices.

Agent Skills是包含指令、脚本和资源的文件夹，可供Agent按需发现和加载。本Skill涵盖Skill的创建、修改和审核，确保其符合规范与最佳实践。

When to Use This Skill

适用场景

Creating a new skill from scratch
Modifying or improving an existing skill
Reviewing skill quality before sharing
Reorganizing skill content for better progressive disclosure

从零开始创建新Skill
修改或优化现有Skill
分享前审核Skill质量
重新组织Skill内容以实现更优的渐进式披露

RFC 2119 Keywords

RFC 2119 关键词

This skill and skills created with it use RFC 2119 keywords to indicate requirement levels.

Keyword	Meaning
MUST, REQUIRED, SHALL	Absolute requirement. No exceptions.
MUST NOT, SHALL NOT	Absolute prohibition. No exceptions.
SHOULD, RECOMMENDED	Strong recommendation. Valid reasons to deviate may exist, but understand implications first.
SHOULD NOT, NOT RECOMMENDED	Strong discouragement. Valid reasons to do it may exist, but understand implications first.
MAY, OPTIONAL	Truly optional. Implement if useful for your context.

Reference: RFC 2119

本Skill及使用本Skill创建的Skill均采用RFC 2119关键词来表示要求级别。

关键词	含义
MUST、REQUIRED、SHALL	绝对要求，无例外情况。
MUST NOT、SHALL NOT	绝对禁止，无例外情况。
SHOULD、RECOMMENDED	强烈建议。存在合理的偏离理由，但需先了解潜在影响。
SHOULD NOT、NOT RECOMMENDED	强烈不建议。存在合理的实施理由，但需先了解潜在影响。
MAY、OPTIONAL	完全可选。若对当前场景有用则可实施。

参考文档：RFC 2119

Specification Quick Reference

规范速查

Required Frontmatter

必填前置元数据

Every

SKILL.md

MUST start with YAML frontmatter containing

name

and

description

yaml

---
name: skill-name
description: What this skill does and when to use it.
---

每个

SKILL.md

必须以包含

name

和

description

的YAML前置元数据开头：

yaml

---
name: skill-name
description: What this skill does and when to use it.
---

Name Field Rules

名称字段规则

The

name

field:

MUST be 1-64 characters
MUST use only lowercase alphanumeric characters and hyphens (
```
a-z
```
,
```
0-9
```
,
```
-
```
)
MUST NOT start or end with a hyphen
MUST NOT contain consecutive hyphens (
```
--
```
)
MUST match the parent directory name exactly

Valid:

pdf-processing

code-review

data-analysis

Invalid:

PDF-Processing

-pdf

pdf--processing

my_skill

name

字段需满足：

长度必须为1-64个字符
只能使用小写字母、数字和连字符（
```
a-z
```
、
```
0-9
```
、
```
-
```
）
不能以连字符开头或结尾
不能包含连续连字符（
```
--
```
）
必须与父目录名称完全一致

有效示例：

pdf-processing

、

code-review

、

data-analysis

无效示例：

PDF-Processing

、

-pdf

、

pdf--processing

、

my_skill

Description Field Rules

描述字段规则

The

description

field:

MUST be 1-1024 characters
SHOULD be written in third person (not "I can help you" or "You can use this")
MUST include a "Use when..." clause specifying trigger conditions
SHOULD contain specific keywords that help agents identify relevant tasks

Good:

yaml

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Bad:

yaml

description: Helps with PDFs.

description

字段需满足：

长度必须为1-1024个字符
建议使用第三人称表述（避免“我可以帮你”或“你可以使用本Skill”）
必须包含“Use when...”从句，明确触发条件
建议包含特定关键词，帮助Agent识别相关任务

优秀示例：

yaml

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

糟糕示例：

yaml

description: Helps with PDFs.

Optional Frontmatter Fields

可选前置元数据字段

These fields are all OPTIONAL (MAY include):

Field	Purpose
`license`	License name or reference to bundled LICENSE file
`compatibility`	Environment requirements (max 500 chars)
`metadata`	Arbitrary key-value pairs for custom properties
`allowed-tools`	Space-delimited list of pre-approved tools (experimental)

以下字段均为可选（可按需包含）：

字段	用途
`license`	许可证名称，或指向捆绑的LICENSE文件的引用
`compatibility`	环境要求（最多500字符）
`metadata`	用于自定义属性的任意键值对
`allowed-tools`	预批准工具的空格分隔列表（实验性功能）

Directory Structure

目录结构

A skill is a directory that MUST contain a

SKILL.md

file:

skill-name/
├── SKILL.md          # REQUIRED - main instructions
├── scripts/          # MAY include - executable code
├── references/       # MAY include - additional documentation
└── assets/           # MAY include - static resources (templates, images, data)

Skill是一个必须包含

SKILL.md

文件的目录：

skill-name/
├── SKILL.md          # 必填 - 主指令文件
├── scripts/          # 可选 - 可执行代码
├── references/       # 可选 - 附加文档
└── assets/           # 可选 - 静态资源（模板、图片、数据）

When to Add References

何时添加参考文档

You SHOULD add separate reference files when:

SKILL.md exceeds ~300 lines
Content applies to specific contexts (language-specific patterns, domain-specific schemas)
Details are needed only for certain tasks (advanced features, edge cases)

References MUST be one level deep from SKILL.md. Nested reference chains (SKILL.md → ref1.md → ref2.md) are NOT RECOMMENDED.

在以下场景中，建议添加独立的参考文件：

SKILL.md内容超过约300行
内容适用于特定场景（特定语言的模式、特定领域的 schema）
仅某些任务需要相关细节（高级功能、边缘案例）

参考文档必须与SKILL.md处于同一层级。不建议使用嵌套的参考链（SKILL.md → ref1.md → ref2.md）。

Best Practices

最佳实践

The following are RECOMMENDED practices. They represent strong guidance with valid reasons to deviate in specific contexts.

以下为推荐实践，代表了具有强指导性的建议，在特定场景下存在合理的偏离理由。

Conciseness is Key

简洁为核心

The context window is shared with conversation history, system prompts, and other skills. Challenge every piece of information:

Does the agent really need this explanation?
Can the agent be assumed to know this?
Does this paragraph justify its token cost?

Target: You SHOULD keep SKILL.md body under 500 lines. Move detailed reference material to separate files.

上下文窗口需与对话历史、系统提示词及其他Skill共享。请对每一条信息进行审视：

Agent是否真的需要这个解释？
是否可以默认Agent已了解该内容？
这段内容的token成本是否合理？

目标： 建议将SKILL.md主体内容控制在500行以内。将详细的参考材料移至独立文件中。

Progressive Disclosure

渐进式披露

Skills SHOULD be structured for efficient context usage:

Metadata (~100 tokens):
```
name
```
and
```
description
```
loaded at startup for all skills
Instructions (<5000 tokens): Full SKILL.md loaded when skill activates
Resources (as needed): Reference files loaded only when required

SKILL.md SHOULD serve as an overview that points to detailed materials. Like a table of contents.

Skill的结构应优化上下文的使用效率：

元数据（约100 tokens）：
```
name
```
和
```
description
```
在启动时加载，对所有Skill可见
指令（少于5000 tokens）：当Skill激活时加载完整的SKILL.md
资源（按需加载）：仅在需要时加载参考文件

SKILL.md应作为概述文档，指向详细的材料，类似目录的作用。

Degrees of Freedom

自由度等级

Match specificity to task fragility:

Freedom Level	When to Use	Example
High (text instructions)	Multiple valid approaches, context-dependent	Code review guidelines
Medium (templates/pseudocode)	Preferred pattern exists, some variation OK	Report generation template
Low (exact scripts)	Fragile operations, consistency critical	Database migrations

根据任务的脆弱性匹配内容的具体程度：

自由度等级	适用场景	示例
高（文本指令）	存在多种有效实现方式，依赖上下文	代码审核指南
中（模板/伪代码）	存在首选模式，允许一定变化	报告生成模板
低（精确脚本）	操作脆弱，一致性要求高	数据库迁移

Workflow Checklists

工作流检查清单

For multi-step processes, you SHOULD provide a checklist the agent can copy and track:

Task Progress:
- [ ] Step 1: Analyze requirements
- [ ] Step 2: Create plan
- [ ] Step 3: Implement
- [ ] Step 4: Validate

对于多步骤流程，建议提供可供Agent复制和跟踪的检查清单：

任务进度：
- [ ] 步骤1：分析需求
- [ ] 步骤2：制定计划
- [ ] 步骤3：实施
- [ ] 步骤4：验证

Feedback Loops

反馈循环

Quality-critical tasks SHOULD include validation steps:

Perform action
Run validation
If validation fails → fix and retry
Only proceed when validation passes

对质量要求高的任务，建议包含验证步骤：

执行操作
运行验证
若验证失败 → 修复并重试
仅在验证通过后继续

Authoring Workflow

编写工作流

Copy this checklist when creating or modifying a skill:

Skill Authoring Progress:
- [ ] Step 1: Define purpose (what problem does this solve?)
- [ ] Step 2: Identify triggers (when should agent use this?)
- [ ] Step 3: Write frontmatter (name matches directory, description is specific)
- [ ] Step 4: Draft body (core instructions, workflows, examples)
- [ ] Step 5: Extract references (move detailed/contextual content)
- [ ] Step 6: Review against checklist (see references/best-practices-checklist.md)
- [ ] Step 7: Test with real tasks

创建或修改Skill时，可复制以下检查清单：

Skill编写进度：
- [ ] 步骤1：明确用途（解决什么问题？）
- [ ] 步骤2：识别触发条件（Agent何时应使用本Skill？）
- [ ] 步骤3：编写前置元数据（名称与目录一致，描述具体）
- [ ] 步骤4：撰写主体内容（核心指令、工作流、示例）
- [ ] 步骤5：提取参考文档（将详细/特定场景的内容移出）
- [ ] 步骤6：对照检查清单审核（参考references/best-practices-checklist.md）
- [ ] 步骤7：通过真实任务测试

Writing Effective Descriptions

编写有效的描述

The description enables skill discovery. It SHOULD include:

What it does: Core capabilities in active voice
When to use it: Specific triggers and keywords
Third person: "Extracts text from PDFs" not "I extract text from PDFs"

描述是Skill被发现的关键。建议包含：

功能：用主动语态说明核心能力
触发场景：具体的触发条件和关键词
第三人称：例如“从PDF中提取文本”而非“我可以从PDF中提取文本”

Required "Use when..." Clause

必填的“Use when...”从句

Every description MUST include a "Use when..." sentence. This phrase signals trigger conditions to agents scanning skill metadata.

Pattern:

[What it does]. Use when [trigger conditions].

Example:

yaml

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

每个描述必须包含“Use when...”语句。该短语向扫描Skill元数据的Agent传递触发条件。

格式：

[功能描述]。Use when [触发条件]。

示例：

yaml

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Using RFC 2119 in Skills

在Skill中使用RFC 2119

Skills created with this skill SHOULD use RFC 2119 keywords to indicate requirement levels.

Choosing the right keyword:

Use This	When
MUST / MUST NOT	Hard constraint. A validator could check this. Breaking it causes failure.
SHOULD / SHOULD NOT	Strong recommendation. Valid exceptions exist, but they're rare.
MAY	Truly optional. No preference either way.

Example transformations:

markdown

undefined

使用本Skill创建的Skill建议采用RFC 2119关键词来表示要求级别。

选择合适的关键词：

使用该关键词	适用场景
MUST / MUST NOT	硬性约束。可通过验证工具检查。违反会导致功能失败。
SHOULD / SHOULD NOT	强烈建议。存在合理的例外情况，但较为罕见。
MAY	完全可选。无偏好倾向。

示例转换：

markdown

undefined

Before (ambiguous)

优化前（表述模糊）

Keep SKILL.md under 500 lines. The name field must match the directory. Consider adding a checklist for multi-step tasks.

After (precise)

优化后（表述精确）

SKILL.md SHOULD be under 500 lines. The name field MUST match the directory. Multi-step tasks MAY include a checklist for tracking.


**Guideline:** If you're unsure between MUST and SHOULD, ask: "Would breaking this rule cause the skill to malfunction, or just be suboptimal?" Malfunction → MUST. Suboptimal → SHOULD.

SKILL.md SHOULD be under 500 lines. The name field MUST match the directory. Multi-step tasks MAY include a checklist for tracking.


**指导原则：** 若不确定选择MUST还是SHOULD，可提问：“违反该规则会导致Skill功能故障，还是仅表现不佳？” 功能故障→MUST，表现不佳→SHOULD。

Common Anti-Patterns

常见反模式

Vague Descriptions

模糊的描述

Descriptions SHOULD NOT be vague or generic:

yaml

undefined

描述不应模糊或泛泛而谈：

yaml

undefined

Bad - agent can't determine when to use this

糟糕示例 - Agent无法判断适用场景

description: Helps with documents.

Good - specific capabilities and triggers

优秀示例 - 明确的功能与触发条件

description: Extract text and tables from PDF files, fill PDF forms, merge multiple PDFs. Use when working with PDF files or document extraction.

undefined

description: Extract text and tables from PDF files, fill PDF forms, merge multiple PDFs. Use when working with PDF files or document extraction.

undefined

Over-Explaining Common Knowledge

过度解释常识

Skills SHOULD NOT explain concepts agents already know:

yaml

undefined

Skill无需解释Agent已知的概念：

yaml

undefined

Bad - agent knows what PDFs are

糟糕示例 - Agent了解PDF是什么

PDF (Portable Document Format) files are a common file format that contains text, images, and other content. To extract text from a PDF...

Good - get to the actionable content

优秀示例 - 直接提供可操作内容

Use pdfplumber for text extraction:

python

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

Use pdfplumber for text extraction:

python

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

Deeply Nested References

深度嵌套的参考文档

Reference chains MUST NOT exceed one level:

markdown

undefined

参考链不能超过一层：

markdown

undefined

Bad - agent may partially read nested files

糟糕示例 - Agent可能仅部分读取嵌套文件

SKILL.md → references/advanced.md → references/details.md

Good - one level deep

优秀示例 - 仅一层深度

SKILL.md → references/advanced.md SKILL.md → references/details.md

undefined

SKILL.md → references/advanced.md SKILL.md → references/details.md

undefined

Time-Sensitive Information

时效性信息

Skills SHOULD NOT include time-sensitive information:

markdown

undefined

Skill不应包含时效性信息：

markdown

undefined

Bad - becomes outdated

糟糕示例 - 会过时

If you're doing this before August 2025, use the old API.

Good - use "old patterns" section

优秀示例 - 使用“旧模式”章节

Current method

当前方法

Use the v2 API endpoint.

使用v2 API端点。

Old patterns (deprecated)

旧模式（已弃用）

<details> <summary>Legacy v1 API</summary> The v1 API used: `api.example.com/v1/messages` </details> ```

Too Many Options Without Defaults

提供过多选项却无默认值

Skills SHOULD NOT present options without clear defaults:

markdown

undefined

Skill不应在未提供明确默认选项的情况下给出大量选择：

markdown

undefined

Bad - decision paralysis

糟糕示例 - 导致决策困难

You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image...

Good - clear default with escape hatch

优秀示例 - 明确默认选项，同时提供替代方案

Use pdfplumber for text extraction. For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.

undefined

Use pdfplumber for text extraction. For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.

undefined

Inconsistent Terminology

术语不一致

Skills SHOULD NOT mix synonyms. Pick one term and use it throughout:

Always "API endpoint" (not mixing with "URL", "route", "path")
Always "field" (not mixing with "box", "element", "control")

Skill不应混用同义词。选择一个术语并保持一致：

始终使用“API endpoint”（不要混用“URL”、“route”、“path”）
始终使用“field”（不要混用“box”、“element”、“control”）

Quality Review

质量审核

Before finalizing a skill, review against the full checklist in

references/best-practices-checklist.md

For example patterns and structures, see

references/examples.md

<IMPORTANT> Every skill should answer two questions clearly: 1. What does this skill enable the agent to do? 2. When should the agent use this skill?

If your description doesn't answer both, revise it. </IMPORTANT>

在Skill定稿前，请对照

references/best-practices-checklist.md

中的完整检查清单进行审核。

如需参考示例模式和结构，请查看

references/examples.md

。

<IMPORTANT> 每个Skill都应清晰回答两个问题： 1. 该Skill能让Agent实现什么功能？ 2. Agent应在何时使用该Skill？

若你的描述无法回答这两个问题，请进行修改。 </IMPORTANT>