update-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

update-skill

更新技能

This guide provides instructions for creating or updating skills in this repository. It covers the required structure, frontmatter, and best practices for skills.

本指南提供了在本仓库中创建或更新技能的说明，涵盖了技能所需的结构、frontmatter及最佳实践。

Quick Start

快速开始

Every skill is a directory containing a

SKILL.md

file with YAML frontmatter and markdown body:

markdown

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

每个技能对应一个目录，其中包含带有YAML frontmatter和Markdown正文的

SKILL.md

文件：

markdown

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

PDF Processing

When to use this skill

Use this skill when the user needs to work with PDF files...

How to extract text

Use pdfplumber for text extraction...

Use pdfplumber for text extraction...

How to fill forms

...

undefined

...

undefined

Requirements

要求

Frontmatter (Required)

前置元数据（frontmatter）（必填）

Every SKILL.md must start with YAML frontmatter containing:

name: Kebab-case identifier (lowercase letters, numbers, hyphens only)
- Example:
```
add-feature-flag
```
  ,
```
pdf-processing
```
  ,
```
update-skill
```
description: Specific description of what the skill does and when to use it
- Must be non-empty
- Should include key terms for skill discovery
- Begin with an action verb to clearly state what the skill accomplishes (e.g., "Adds feature flags..." instead of "Helps with features..."), and immediately follow with a specific use case or context (e.g., "Use when working with feature flags")
- Write in third person (e.g., "Adds feature flags..." not "I can help you add...")

每个SKILL.md必须以包含以下内容的YAML frontmatter开头：

name：短横线命名法（kebab-case）标识符（仅允许小写字母、数字、短横线）
- 示例：
```
add-feature-flag
```
  ,
```
pdf-processing
```
  ,
```
update-skill
```
description：明确描述技能的功能及适用场景
- 不能为空
- 应包含技能发现所需的关键术语
- 以动作动词开头，清晰说明技能能完成的任务（例如："Adds feature flags..." 而非 "Helps with features..."），并紧跟具体使用场景或上下文（例如："Use when working with feature flags"）
- 使用第三人称表述（例如："Adds feature flags..." 而非 "I can help you add..."）

Writing Effective Descriptions

撰写有效的描述

The description field is critical for skill discovery. Include both what the skill does and when to use it. Some good examples:

```
git-commit
```
: "Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes."
```
pdf-processing
```
: "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."

Avoid vague descriptions like "Helps with code" or "Does development tasks". For more context, see "Description Best Practices" in references/best-practices.md.

描述字段对于技能发现至关重要，需同时包含技能功能和适用场景。以下是一些优秀示例：

```
git-commit
```
: "Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes."
```
pdf-processing
```
: "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."

避免使用模糊描述，例如"Helps with code"或"Does development tasks"。更多内容请参考references/best-practices.md中的“描述最佳实践”。

Skill Structure

技能结构

Typical sections in Warp skills:

Title and brief summary – Clear title and a concise overview of the skill's purpose and primary use cases. Link to sections, reference files or related skills if useful
Overview - Context about the skill's purpose (optional but common), extends the summary with more details and context
Main content - Steps, usage instructions, or workflow guidance
Best Practices - Guidelines and recommendations (optional)
Examples / Reference PRs - Links to real examples (optional)

Keep the structure flexible based on the skill's needs. Simple skills can omit the optional sections.

Warp技能的典型章节：

标题与简要概述——清晰的标题及对技能用途和主要适用场景的简洁概述。如有需要，可链接至相关章节、参考文件或关联技能
概述——说明技能用途的背景信息（可选但常见），在概述基础上补充更多细节和上下文
主要内容——步骤、使用说明或工作流指导
最佳实践——指南与建议（可选）
示例 / 参考PR——真实示例链接（可选）

可根据技能需求灵活调整结构。简单技能可省略可选章节。

Validation

验证

Optionally, use the skills-ref reference library to validate your skills:

bash

skills-ref validate ./my-skill

This checks that your SKILL.md frontmatter is valid and follows all naming conventions. If not installed, use the WebSearch tool to get context around this package.

可选择使用skills-ref参考库验证技能：

bash

skills-ref validate ./my-skill

该工具会检查SKILL.md的frontmatter是否有效，并是否符合所有命名规范。若未安装，可使用WebSearch工具获取该包的相关信息。

Main Content Best Practices

主要内容最佳实践

For guidance on what qualifies as good main content, see "Conciseness Principles" in references/best-practices.md
When formatting code examples, see "Code Example Formatting" in references/best-practices.md.

关于优质主要内容的编写指南，请参考references/best-practices.md中的“简洁性原则”
代码示例格式规范，请参考references/best-practices.md中的“代码示例格式”。

File Organization

文件组织

Simple skills (<=200 lines): Keep everything in SKILL.md
Complex skills (>200 lines): Split detailed content into
```
references/
```
subdirectory
- Reference files from SKILL.md with clear links
- Example: "See references/best-practices.md for detailed guidance"

简单技能（≤200行）：所有内容均放在SKILL.md中
复杂技能（>200行）：将详细内容拆分至
```
references/
```
子目录
- 在SKILL.md中通过清晰链接引用文件
- 示例："详细指导请参考references/best-practices.md"

When to Split Content

何时拆分内容

Create

references/

subdirectory when:

SKILL.md approaches 200+ lines
Skill covers multiple domains or workflows that can be loaded independently
Detailed reference material would clutter the main instructions

Keep only essential workflow and procedural instructions in SKILL.md. Move detailed reference material, schemas, and extensive examples to

references/

files.

当出现以下情况时，创建

references/

子目录：

SKILL.md内容接近200行
技能涵盖多个可独立加载的领域或工作流
详细参考资料会使主说明内容显得杂乱

仅将必要的工作流和流程说明保留在SKILL.md中。将详细参考资料、模式和大量示例移至

references/

目录下的文件中。

Examples from Existing Skills

现有技能示例

For reference on structure and style:

```
.agents/skills/add-feature-flag/SKILL.md
```
- Multi-step workflow with clear sequential steps

.agents/skills/remove-feature-flag/SKILL.md

- Cleanup workflow with search commands

如需参考结构和风格，可查看：

```
.agents/skills/add-feature-flag/SKILL.md
```
——包含清晰顺序步骤的多步骤工作流

.agents/skills/remove-feature-flag/SKILL.md

——包含搜索命令的清理工作流

Best Practices

最佳实践

See references/best-practices.md for detailed authoring guidance including:

Progressive disclosure patterns
Writing concise, effective instructions
Code example formatting
Common anti-patterns to avoid

详细的创作指南请参考references/best-practices.md，包括：

渐进式披露模式
撰写简洁有效的说明
代码示例格式
需要避免的常见反模式