Skills Description

The skill description (description) is the most important part of a skill. It determines whether the agent can correctly identify when the skill should be activated. This section will teach you how to write effective skill descriptions.

Why descriptions are important

The skill description plays a key role in the agent's skill loading process:

  • During the discovery phase, the agent only loads the name and description of each skill
  • The description is the main basis for the agent to decide whether to activate the skill
  • A good description can improve the activation accuracy of the skill

If the description is poorly written, the agent may:

  • Activate the skill when it is not needed (false positive)
  • Fail to activate the skill when it is needed (false negative)
  • Activate the wrong skill

Tip: The quality of the skill description directly affects the usability of the skill. It is worth investing time in optimizing the description.

Basic structure of the description

A good skill description should include two parts:

  1. Functional description: describes what the skill can do
  2. Trigger conditions: explains when to use it
description: 从 PDF 文件中提取文本和表格，填写 PDF 表单，合并多个 PDF。处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。
#                         ↑ 功能说明                                      ↑ 触发条件

Tips for writing effective descriptions

1. Include specific trigger keywords

Include specific words and phrases that users may use in the description. These keywords help the agent identify relevant tasks.

Good description:

description: 提取 PDF 文本和表格，填写表单，合并 PDF。使用场景：处理 PDF 文件、提取文档内容、填写 PDF 表单、合并多个 PDF、用户提及「PDF」「提取」「表单」「合并」等关键词。

2. Be specific rather than general

Avoid overly broad descriptions, as this will prevent the agent from making accurate judgments.

# 不好的描述 - 太笼统
description: 帮助处理各种文件。

# 好的描述 - 具体明确
description: 处理图像文件，包括调整大小、转换格式、应用滤镜。使用场景：处理图片、调整图像尺寸、转换图片格式。

3. Specify multiple use scenarios

List the different scenarios to which the skill may apply, helping the agent match more accurately.

description: 执行代码审查，检查安全漏洞、代码质量和性能问题。使用场景：代码审查、PR 审查、代码检查、安全扫描、质量评估、用户要求「review」「检查代码」「安全性」等。

4. Distinguish similar skills

If you have multiple related skills, make sure their descriptions are clearly distinguishable.

# 技能 1：PDF 文本提取
name: pdf-extract
description: 从 PDF 文件中提取文本内容和表格数据。使用场景：提取 PDF 文字、读取 PDF 内容、PDF 转文本、用户提及「PDF 提取」「读取 PDF」等。

# 技能 2：PDF 表单处理
name: pdf-form
description: 填写 PDF 表单字段，提取表单数据。使用场景：填写 PDF 表单、填充表单字段、PDF 表单数据处理、用户提及「PDF 表单」「填写表单」等。

Description length control

The maximum length of the description field is 1024 characters. But that is not the goal; the description should be concise and accurate.

Case Recommended length
Simple skill 50-100 characters
Medium-complexity skill 100-200 characters
Complex skill 200-400 characters

Note: A longer description is not necessarily better. An overly long description may contain too much irrelevant information and instead interfere with the agent's judgment.

The maximum length of the description field is 1024 characters. But that is not the goal; the description should be concise and accurate.

After creating a skill, you should test whether the description can correctly trigger the skill. The following are the testing steps:

1. Basic functional testing

Test with the keywords included in the description to confirm that the skill can be activated.

2. Edge case testing

Test some scenarios that might trigger the skill but should not trigger it.

3. Iterative optimization

Adjust the description based on the test results:

  • If false positives increase: add more qualifying conditions to the description
  • If false negatives increase: add more possible trigger words to the description
  • If the wrong skill is activated: ensure the description is sufficiently distinguishable from other similar skills

Optimization example:

# 初始版本 - 可能漏报
description: 提取 PDF 文本。

# 优化版本 - 减少漏报
description: 从 PDF 文件中提取文本内容和表格数据。使用场景：提取 PDF 文字、读取 PDF 内容、PDF 转文本。

# 最终版本 - 进一步优化
description: 从 PDF 文件中提取文本内容和表格数据。使用场景：提取 PDF 文字、读取 PDF 内容、PDF 转文本、用户提及「PDF 提取」「读取 PDF」「PDF 文字」「PDF 内容」等关键词时使用。

Common problems and solutions

Problem 1: The skill is always activated

This means the description is too broad. The solution is to add more qualifying conditions and use scenarios.

Solution:

# 修改前 - 太宽泛
description: 处理文本。

# 修改后 - 更具体
description: 使用正则表达式处理和转换文本字符串。使用场景：文本匹配、字符串替换、模式提取、数据清洗。

Problem 2: The skill is never activated

This means the description lacks keywords that users may use. The solution is to add more trigger words.

Solution:

# 修改前 - 关键词太少
description: 优化数据库查询。

# 修改后 - 添加更多触发词
description: 优化 SQL 查询性能，分析执行计划，添加索引。使用场景：SQL 优化、查询慢、数据库性能、调优索引、执行计划分析。

Problem 3: The wrong skill is activated

This means the descriptions of multiple skills are too similar. The solution is to make the descriptions more distinctive.

Tip: It is a good habit to regularly test and optimize your skill descriptions. As use scenarios increase, you may find that the descriptions need adjustment.

Other extensions