ratel-tune-definitions

/ratel-tune-definitions — ツールとスキルの定義を検索・利用可能にする

Ratel は定義をもとにツールとスキルを検索します。語彙（BM25）インデックスでは、説明的な名前、パラメーター名、列挙値、正確なトリガー用語が評価されます。一方、セマンティック／ハイブリッドモードでは、セマンティックインデックスが説明の意味を照合します。その後、モデルが上位 K 件の結果のうち、どれを呼び出すかを判断します。定義に問題があると、どちらの段階もうまく機能しません。曖昧な説明はどちらの検索方式でも見つからず、冗長な説明は近隣の候補を押しのけ、よく似たツールが二つあるとモデルの確信が分散し、制約の緩いスキーマではモデルがツールを誤って呼び出す可能性があります。このスキルは、定義ごとに具体的な修正前・修正後の書き換え例を示しながら、こうした問題を手作業で調整します。

成果物は、<repo>/.ratel/ratel-tune-definitions.md に作成する Markdown 形式の計画です。定義ごとの修正前・修正後の表と、優先順位を付けた修正リストを含みます。この計画は利用者が実行できる内容であり、このスキルが利用者のツールやスキルのコードを直接編集することはありません。

このスキルは、/ratel-assessment の「Definition Quality」評価項目から案内される修正手段です。次のスキルと連携します。

• /ratel-decompose-prompt — このスキルはプロンプトからスキルを抽出します。こちらのスキルは、抽出したスキルの description と tags を磨き、実際に検索できるようにします。抽出した項目に対して、分解の後に実行してください。
• /ratel-assessment — 定義の弱点を指摘し、こちらのスキルを案内する、最初の監査です。

LLM 主導の提案、すなわち説明の自動書き換え、不足パラメーターの検出、冗長なツールの統合案は、Ratel Cloud の提案エンジン（近日公開予定）の開発方針です。このエンジンは、エクスポートされたテレメトリーをもとにサーバー側で優先順位付きの提案を生成します。このスキルはその作業を手動で行うものです。エンジンの公開後に利用者が任せられる修正があれば、計画に記載してください。

基本方針

ルールは三つです。どれか一つでも破ると、検索しやすさを改善せずにカタログを見栄えよくしただけになるか、検索性を高める代わりにモデルを混乱させることになります。

1. 定義は二つの読み手、つまりインデックスとモデルに役立つものでなければならず、修正は両方を満たす必要があります。 語彙インデックスは名前、説明、パラメーター名、列挙値を読み取ります（ADR-0004 のスキーマ対応プロジェクションでは、JSON Schema の構造が取り除かれます）。セマンティック／ハイブリッドモードでは、セマンティックインデックスが説明の意味を埋め込みます。モデルは説明を読んでいつ呼び出すかを判断し、スキーマを読んでどのように呼び出すかを判断します。「いつ使うか」の説明がなく、キーワードだけを詰め込んだ説明は、語彙検索には役立っても、セマンティック検索やモデルには不利です。書き換えはすべて、両方の読み手にとって改善となるものでなければなりません。
2. 長くするより、引き締めることが重要です。 説明の問題を直すのに、単語を増やす必要があることはほとんどありません。説明が不十分なら、段落ではなく「何をするか＋いつ使うか」の一文を加えます。冗長なら、削ります。スキーマは、説明を足して補うのではなく、制約の不足をなくします（additionalProperties: true や空の {} など）。
3. 問題を作り出さないこと。 定義がすでに簡潔であれば、そのままにして、そう記載してください。きれいな説明を無理に書き換えて内容を増やしたり、実際には重複していないツールを分割したり、値の範囲が本当に自由なフィールドに列挙値を追加したりしないでください。修正前・修正後の表には、変更する定義だけを記載します。

ワークフロー

ステップ 1 — ツールとスキルの定義をすべて洗い出す

ツールとスキルが宣言されている場所をすべて見つけ、定義に含まれる情報を漏れなく記録します。名前、説明、パラメーター名、列挙値、スキーマ、スキルの場合はタグも対象です。

# Manifests
test -f package.json && jq -r '.dependencies // {}, .devDependencies // {} | keys[]' package.json | sort -u
test -f pyproject.toml && head -200 pyproject.toml

# Tool definition sites
grep -rEn 'defineTool|createTool|registerTool|new Tool|@tool\b|@function_tool\b|tools:\s*\{|tools:\s*\[|inputSchema|parameters:\s*\{|catalog\.register|McpServer\(' \
  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.py' | head -100

# Skill definition sites + Ratel skills folder
grep -rEn 'new Skill|Skill\(|SkillCatalog|skillCatalog\.register' \
  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.py' | head -50
ls ~/.ratel/skills/ 2>/dev/null

各ツールについて、ID／名前、説明（おおよそのトークン数も含む）、すべてのパラメーター名と列挙値、スキーマの制約の緩さ（additionalProperties、空のオブジェクト、required の不足）を記録します。各スキルについては、名前、説明、タグを記録します。ツールもスキルも見つからない場合は、正直にスキップする手順を使用します。

Step 2 — 最新の Ratel ドキュメントを取得する

Ratel の 0.4.x 系列は更新が速いため、インデックスのルールやデータモデルを記憶だけで説明せず、実行時に次の順序で最新の情報を取得してください。

1. Context7（推奨） — Ratel Local 経由（search_capabilities を呼び出して Context7 の resolve-library-id / get-library-docs ツールを探し、その後 invoke_tool を呼び出す）、または直接設定した Context7 MCP を使います。ratel-ai/ratel を解決し、SDK とスキルのドキュメントを取得してください。
2. docs.ratel.sh（フォールバック） — WebFetch で https://docs.ratel.sh/llms.txt（ページマップ）を取得し、次に https://docs.ratel.sh/llms-full.txt（全文）を取得します。または、特定のページ /docs/core/sdks/typescript、/docs/core/sdks/python、/docs/core/skills-suite を取得します。
3. GitHub raw／インストール済みパッケージ（最後の手段） — https://raw.githubusercontent.com/ratel-ai/ratel/main/README.md と src/sdk/ts/README.md／src/sdk/python/README.md を参照します。または、顧客が指定したバージョンの node_modules/@ratel-ai/sdk/README.md／Python の ratel_ai パッケージの README を参照します。

ドキュメントに照らして、次の 2 点を確認してください。語彙インデックスがトークン化する対象と、セマンティックアームが意味をどのように順位付けするか（書き換えの対象となるフィールドを把握するため）、および現在の Skill データモデルです。ドキュメントの内容が references/definition-rubric.md と異なる場合は、ドキュメントを優先し、計画でそのファイルの更新が必要であることを明記してください。

Step 3 — 失敗パターンに照らして診断する

Step 1 の各定義をすべて、references/definition-rubric.md のルーブリックに照らして確認してください。具体的な失敗パターンは次のとおりです。

失敗パターン	検出ヒューリスティック
肥大化した説明	約300トークンを超える、複数の段落がある、スキーマを文章で繰り返している
不十分な説明	約8トークン未満、またはツール名を説明の代わりにしている（「Order tool」など）
「使用するタイミング」の欠落	機能は説明しているが、呼び出すタイミングが説明されていない。同類のツールと区別できない
類似しすぎたツール	説明や名前が大きく重複するツールが2つ以上ある（例：get_user、fetch_user、lookup_user）
スキーマが緩い／欠落	additionalProperties: true、空の {}、required がない、型が指定されていないパラメーター
説明性のないパラメーター名	arg1、data、input、x など。語彙インデックスから認識できず、モデルにとって意味がない
列挙値の欠落	有限の値を取る文字列フィールド（status、region、mode）が自由形式の string のままになっている
冗長なツール出力	ツールが、モデルが各ターンで読み直さなければならない、大きく上限のないデータを返す

指摘した定義ごとに、失敗パターンと根拠（実際のテキスト、長さ、またはスキーマの一部）を記録してください。

Step 4 — 各修正の重要性を説明する

すべての修正について、計画に二重の根拠を記載し、変更が単なる見た目の調整ではないことを顧客に理解してもらいます。

• 検索性のため — 語彙インデックスは名前、説明、パラメーター名、列挙値をトークン化します（構造は除去されます）。一方、セマンティックインデックスは説明の意味を埋め込みます。そのため、arg1 を customer_email に変更すること、["pending","shipped","delivered"] の列挙値を追加すること、トリガーとなる言い回しを追加することは、いずれも語彙アームで検索可能な語句を増やします。また、「何をするか＋いつ使うか」を明確な自然言語で説明すると、セマンティックアームが、ユーザーが完全には同じ言葉で表現しなかった言い換えにも一致できるようになります。ユーザーの言葉で説明されておらず、意味も明確でないツールは候補に現れません。
• モデルによる選択のため — ツールが上位 K 件に入ると、モデルは説明の「使用するタイミング」を読んでツールを選び、スキーマを読んで正しく呼び出します。類似しすぎたツールがあると確信度が分散し、緩いスキーマは不正な呼び出しを招きます。肥大化した説明は、ツール選択でコンテキストウィンドウを「デフォルトで置き換える」設計が簡潔に保とうとしている領域を圧迫します。

Step 5 — 具体的な書き換えを作成する

問題ありと判定された各定義について、変更前 → 変更後を記述します。ルーブリックの書き換え方法と「適切な説明」のテンプレートを使用します。

<1文：その定義が何をするか。> Use when <呼び出すタイミングを1行で記述。>

• 説明 — テンプレートを適用し、キーワードを詰め込まずに、異なる呼び出しのきっかけとなる表現を追加します。
• 名前／パラメーター名 — 字句インデックスでトークン化できる、説明的な用語に変更します。
• 列挙型 — 自由形式の文字列になっている有限フィールドを、明示的な列挙値リストに置き換えます（値はインデックス化され、モデルの選択肢を制約します）。
• スキーマ — additionalProperties: false を設定し、required を追加して、すべてのパラメーターに型を指定します。
• 類似定義 — 統合（1つのツールと列挙型／パラメーター）または、残す定義を区別するために「使用するタイミング」を明確化する案を提示します。
• 冗長な出力 — outputSchema、またはツールがモデルに必要なものだけを返すようにするためのプロジェクション／要約を提案します。

スキルについては、ルーブリックに沿って、検索しやすくなるようdescriptionとtagsも調整します。作成者が付けたラベルとタスクのフレーズをtagsにまとめ、説明にはテンプレートを適用します。抽出されたスキルはここで共通の入力となるため、これを/ratel-decompose-promptと相互参照します。

Step 6 — 優先順位を付ける

修正リストを影響度の高い順に並べます。

1. 類似するツールと内容の薄い説明 — 誤った検索結果や検索結果なしにつながるため、最優先です。
2. 「使用するタイミング」の記載不足と列挙型の不足 — 選択ミスや不正な呼び出しにつながります。
3. 緩いスキーマと説明的でないパラメーター名 — 正確性と検索性に影響します。
4. 冗長な説明と冗長な出力 — コンテキスト効率に影響します。緊急度は低いものの、規模が大きくなると影響が積み重なります。

Step 7 — 計画を作成する

<repo>/.ratel/ratel-tune-definitions.mdに出力します。次のセクションを、この順序で記載します。

1. 概要 — ツール／スキルの調査件数、問題ありと判定された定義の件数、問題の種類別の件数。箇条書きは最大6項目です。
2. 最新ドキュメントの参照情報 — この計画の作成時に参照したRatelのバージョンとドキュメントの情報源。
3. 変更前／変更後の表 — 変更した定義ごとに1行。id、問題の種類、変更前、変更後を記載します。ここが計画の中核です。
4. スキーマの厳格化 — ツールごとのスキーマ差分（additionalProperties、required、列挙型、型）。
5. 類似定義への対処 — 統合または区別を明確化する案。
6. 優先度付き修正リスト — Step 6に従って順序付けし、各項目を1行で記載します。
7. ロードマップに関する注記 — Ratel Cloudの提案エンジン（近日公開）で、将来どの修正を自動化できるかを記載します。

優先度付き修正リストをチャット内に表示し、ファイルのパスをユーザーに伝えます。計画の全文をチャットに貼り付けないでください。

正直なスキップ条件

スキップするケースは2つあります。

1. ツールもスキルも見つからない場合。 Step 1でツールまたはスキルの定義が見つからなかった場合は、そこで終了します。何を検索したかをユーザーに伝え、カタログが通常とは異なる場所にある場合は、場所を教えてもらいます。確認できない定義の調整は行いません。
2. カタログが小規模、またはすでに十分に整備されている場合。 定義が少数しかなく、すでにルーブリックを満たしている（「何をするか」と「使用するタイミング」が明確な説明、厳格なスキーマ、説明的なパラメーター名、重複なし）場合は、その旨を伝えて終了します。小規模で説明の行き届いたカタログでは、このスキルが解決する検索上の問題はほとんど発生しません。確認した内容を列挙して、顧客に十分な確認を行ったことがわかるようにし、カタログが拡大したときに再検討することを提案します。

参考ファイル

• references/definition-rubric.md — 問題の種類ごとの検出基準、書き換え方法、変更前／変更後の例。「適切な説明」のテンプレートに加え、各フィールドを字句インデックスと意味インデックスがどのように処理するかに基づく、パラメーター名と列挙値の命名ガイダンスも記載されています。

読み込み元（複製しないもの）：

• ../ratel-decompose-prompt/references/decomposition-patterns.md — この作業で調整するスキルの、Skillデータモデルとフィールドごとの作成コンテキスト。