Описание навыков

Описание навыка (description) — самая важная часть навыка. Оно определяет, может ли агент правильно определить, когда навык должен быть активирован. В этом разделе вы узнаете, как писать эффективные описания навыков.


Почему описания важны

Описание навыка играет ключевую роль в процессе загрузки навыков агентом:

  • На этапе обнаружения агент загружает только имя и описание каждого навыка
  • Описание — основной критерий, по которому агент решает, активировать ли навык
  • Хорошее описание может повысить точность активации навыка

Если описание написано плохо, агент может:

  • Активировать навык, когда он не нужен (ложноположительный результат)
  • Не активировать навык, когда он нужен (ложноотрицательный результат)
  • Активировать неправильный навык

Совет: качество описания навыка напрямую влияет на удобство использования навыка. Стоит потратить время на оптимизацию описания.


Базовая структура описания

Хорошее описание навыка должно включать две части:

  1. Функциональное описание: описывает, что навык умеет делать
  2. Условия срабатывания: объясняют, когда его использовать
description: 从 PDF 文件中提取文本和表格,填写 PDF 表单,合并多个 PDF。处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。
#                         ↑ 功能说明                                      ↑ 触发条件

Советы по написанию эффективных описаний

1. Указывайте конкретные ключевые слова-триггеры

Включите в описание конкретные слова и фразы, которые могут использовать пользователи. Эти ключевые слова помогают агенту определять релевантные задачи.

Хорошее описание:

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

2. Будьте конкретны, а не обобщайте

Избегайте слишком общих описаний, так как это помешает агенту делать точные выводы.

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

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

3. Укажите несколько сценариев использования

Перечислите различные сценарии, в которых может применяться навык, помогая агенту точнее сопоставлять.

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

4. Различайте похожие навыки

Если у вас есть несколько связанных навыков, убедитесь, что их описания чётко различимы.

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

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

Контроль длины описания

Максимальная длина поля description — 1024 символа. Но это не цель; описание должно быть кратким и точным.

Случай Рекомендуемая длина
Простой навык 50-100 символов
Навык средней сложности 100-200 символов
Сложный навык 200-400 символов

Примечание: более длинное описание не обязательно лучше. Чересчур длинное описание может содержать слишком много нерелевантной информации и вместо этого мешать оценке агента.


Максимальная длина поля description — 1024 символа. Но это не цель; описание должно быть кратким и точным.

После создания навыка следует проверить, может ли описание корректно активировать навык. Ниже приведены шаги тестирования:

1. Базовое функциональное тестирование

Проверьте с ключевыми словами, включёнными в описание, чтобы убедиться, что навык может быть активирован.

2. Тестирование граничных случаев

Проверьте несколько сценариев, которые могут активировать навык, но не должны его активировать.

3. Итеративная оптимизация

Корректируйте описание на основе результатов тестирования:

  • Если увеличивается число ложных срабатываний: добавьте больше ограничивающих условий в описание
  • Если увеличивается число ложноотрицательных срабатываний: добавьте больше возможных слов-триггеров в описание
  • Если активируется не тот навык: убедитесь, что описание достаточно отличается от других похожих навыков

Пример оптимизации:

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

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

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

Типичные проблемы и решения

Проблема 1: Навык всегда активируется

Это означает, что описание слишком широкое. Решение — добавить больше уточняющих условий и сценариев использования.

Решение:

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

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

Проблема 2: Навык никогда не активируется

Это означает, что в описании не хватает ключевых слов, которые могут использовать пользователи. Решение — добавить больше слов-триггеров.

Решение:

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

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

Проблема 3: Активируется не тот навык

Это означает, что описания нескольких навыков слишком похожи. Решение — сделать описания более различимыми.

Совет: полезная привычка — регулярно тестировать и оптимизировать описания навыков. По мере увеличения сценариев использования вы можете обнаружить, что описания нуждаются в корректировке.

Другие расширения