Skills 説明

スキル説明(description)はスキルの中で最も重要な部分であり、エージェントがいつスキルをアクティブ化すべきかを正しく認識できるかどうかを決定します。このセクションでは、効果的なスキル説明の書き方を説明します。


なぜ説明が重要なのか

スキル説明は、エージェントがスキルを読み込むプロセスにおいて重要な役割を果たします:

  • 発見フェーズでは、エージェントは各スキルの名前と説明のみを読み込みます
  • 説明は、エージェントがスキルをアクティブ化するかどうかを判断する主要な根拠です
  • 良い説明はスキルのアクティブ化精度を向上させることができます

説明の書き方が悪いと、エージェントは次のような問題を起こす可能性があります:

  • 不要なときにスキルをアクティブ化する(誤検知)
  • 必要なときにスキルのアクティブ化を忘れる(見逃し)
  • 誤ったスキルをアクティブ化する

ヒント:スキル説明の品質はスキルの使いやすさに直接影響します。説明の最適化に時間を費やす価値はあります。


説明の基本構造

良いスキル説明は2つの部分を含むべきです:

  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文字

注意:説明は長ければ長いほど良いわけではありません。長すぎる説明には無関係な情報が多すぎて、かえってエージェントの判断を妨げる可能性があります。


説明のテストと最適化

スキルを作成したら、説明がスキルを正しくトリガーできるかどうかをテストする必要があります。以下はテスト手順です:

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:誤ったスキルがアクティブ化される

これは複数のスキルの説明が似すぎていることを示しています。解決方法は、説明をより区別しやすくすることです。

ヒント:スキル説明を定期的にテストして最適化することは良い習慣です。使用シナリオが増えるにつれて、説明の調整が必要になることに気づくかもしれません。

その他の拡張