ratel-decompose-prompt

/ratel-decompose-prompt — 巨大なシステムプロンプトを、簡潔なコアと取得可能なスキルに分割する

数千トークンに膨れ上がったシステムプロンプトは、あらゆるターンであらゆる役割を担うためのコストを支払っています。その大半は、ほとんどの時間は使われません。ユーザーが配送について尋ねている間も返金手続きがコンテキストに入り、ユーザーがフォームを編集中も SQL 生成の手引きが読み込まれています。Ratel のスキル機能は、まさにこの問題を解決するためにあります。手順を取得可能なプレイブックにすれば、必要なターンでのみコンテキストに入ります。このスキルは、巨大なプロンプトを、小さく安定したコアと、抽出したスキルをまとめる SkillCatalog に変えるための解決策です。

成果物は、<repo>/.ratel/ratel-decompose-prompt.md に作成する Markdown 形式の計画書です。提案する簡潔なコアプロンプト、スキルの一覧表、および Ratel 管理のスキルフォルダーにそのまま配置できる、スキルごとの SKILL 定義を含みます。この計画はお客様が実装できるものであり、このスキルがプロンプトを直接書き換えることはありません。

このスキルは、/ratel-assessment の「プロンプトの分解」ディメンションから案内される解決策です。次のスキルと組み合わせて使います。

• /ratel-tune-definitions — 抽出する各スキルには、取得可能な description と tags が必要です。分解によってスキルを作成し、tune-definitions で表現を洗練させることで、search_capabilities が実際にそのスキルを見つけられるようにします。抽出したスキルに対して、このスキルの後に実行してください。
• /ratel-assessment — 過剰に詰め込まれたプロンプトを特定し、ここへ案内する最初の監査です。

方針

ルールは3つです。どれか1つでも破ると、肥大化を取り除かずに移動させるか、プロンプトの安定した契約を損ない、エージェントの信頼性を低下させることになります。

1. コアプロンプトにはすべてのターンで維持すべき内容を残し、状況に応じた内容はスキルにします。 安定した役割、安全ルール、出力形式の契約はコアに残します。モデルがそれらを欠くことがあってはなりません。繰り返し使う手順、タスク固有のプレイブック、少数例は状況に応じた内容であり、スキルに含めます。各セクションについて、「無関係なターンでこれがないと、エージェントは安全性を損なうか、契約に違反するか」と問いかけてください。そうであればコアに残します。そうでなければ、スキルの候補です。
2. スキルは自己完結しており、取得する価値がなければなりません。 抽出したスキルは、周囲のプロンプトコンテキストがない状態で get_skill_content を介して読み込まれます。あるセクションが他の3つのセクションと結び付いていなければ意味をなさないなら、それは4つではなく1つのスキルです。単独では成り立たない断片に、まとまった手順を分割してはいけません。
3. 取得可能性は後付けではなく、設計上の制約です。 検出されないスキルはカタログの無駄であり、エージェントの振る舞いに穴を作ります。抽出する各スキルには、そのスキルが必要となるターンの自然言語の意図に合致する description と tags が必要です。呼び出し条件を書けないのであれば、おそらくその内容はコアに含めるか、スキルにする必要がありません。

ワークフロー

ステップ 1 — システムプロンプトを特定して規模を測る

システムプロンプトをすべて見つけ、ターンごとのコストを見積もります。プロンプトはインライン文字列、テンプレートファイル、プロンプト管理サービス、エージェントごとの定数に隠れていることがあります。

# Manifests (drives stack + where prompts tend to live)
test -f package.json && jq -r '.dependencies // {}, .devDependencies // {} | keys[]' package.json | sort -u
test -f pyproject.toml && head -200 pyproject.toml

# System-prompt surfaces
grep -rEn 'system:|role:\s*["'\'']system|systemPrompt|SYSTEM_PROMPT|system_prompt|instructions:|messages\.create|ChatPromptTemplate|SystemMessage' \
  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.py' --include='*.md' --include='*.txt' \
  | head -100

# Prompt files by convention
find . -type f \( -name '*.prompt' -o -name '*prompt*.md' -o -name '*prompt*.txt' \) -not -path '*/node_modules/*' | head -50

見つかったプロンプトごとに、トークン数の目安（おおよそ文字数 ÷ 4、または wc -c ÷ 4）を見積もります。最も大きいプロンプトと、すべてのターンで読み込まれるもの／特定の経路でのみ読み込まれるものを記録してください。システムプロンプトが見つからない場合は、正直にスキップする手順を使ってください。

ステップ 2 — 最新の Ratel ドキュメントを取得する

Ratel の更新は速いため、skills API や Skill データモデルを記憶だけで説明せず、実行時に次の順序で最新の情報を取得してください。

1. Context7（推奨） — ローカル MCP サーバーである Ratel Local 経由（search_capabilities を呼び出して Context7 の resolve-library-id / get-library-docs ツールを探し、その後 invoke_tool を呼び出す）、または直接設定した Context7 MCP 経由で取得します。ratel-ai/ratel を解決し、SDK と skills のドキュメントを取得します。
2. docs.ratel.sh（代替手段） — WebFetch で https://docs.ratel.sh/llms.txt（ページマップ）、続いて https://docs.ratel.sh/llms-full.txt（全文）を取得するか、特定のページ https://docs.ratel.sh/docs/core/agent-skills、https://docs.ratel.sh/docs/core/sdks/typescript、https://docs.ratel.sh/docs/core/sdks/python を取得します。
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 を確認します。

次の 3 点を記録してください。現在リリースされているバージョン、SkillCatalog ／ Skill ／ searchCapabilitiesTool ／ getSkillContentTool の API 形式、そして Skill データモデルのフィールドです。取得したドキュメントの内容が references/decomposition-patterns.md のパターンと異なる場合は、ドキュメントを優先し、計画内でファイルの更新が必要であることを示してください。

ステップ 3 — 分解の境界を特定する

プロンプトを読み、役割ごとにセクションに分けます。探すべき境界と、それぞれの分類先は次のとおりです。

セクションの種類	分類	理由
安定した役割／ペルソナ	コアに残す	毎ターン維持する必要があり、コストが低く、エージェントを定義するため
安全性／拒否／ポリシーのルール	コアに残す	これがないと正確性／安全性が損なわれるため
出力形式の契約（スキーマ、トーン、構造）	コアに残す	モデルはすべての応答でこれに従う必要があるため
繰り返し実行する複数ステップの手順	スキルに切り出す	状況依存で、大きく、該当するターンでのみ必要なため
タスク固有のプレイブック（返金フロー、SQL 生成、トリアージ）	スキルに切り出す	それぞれが独立した 1 つのスキルであるため
Few-shot の例	スキルに切り出す	サイズが大きいため。該当するタスクの例を、そのタスクのスキルに含めます
ツール使用のドキュメント／ツールごとの使い方	スキルに切り出す（またはツールに合致したときに表示されるよう、ツール自体の説明に組み込む — /ratel-tune-definitions を参照）	ツールに合致したときに、そのツールとともに表示されるため

セクションの一覧を作成します。各セクションについて、おおよそのトークン数、分類先、切り出し候補の場合は、そのセクションが担うタスクを 1 行で記述します。全項目の一覧と、変更前／変更後の例については、references/decomposition-patterns.md を参照してください。

Step 4 — 抽出した各スキルをデータモデルに照らして定義する

抽出候補ごとに、Ratel Skill のデータモデル全体を指定します。検索対象としてインデックス化されるのは name、description、tags のみです。そのため、検索可能性を担うのはこれらのフィールドです。body、tools、metadata はインデックス化されません。

• id — refund-flow のような、安定したスラッグです。
• name — 人が理解しやすい短いラベルです。インデックス化されます。
• description — 対象となる会話ターンの自然言語でのトリガーを明記した、複数のフレーズからなる説明です。インデックス化されます。主な検索対象となります。
• tags — 作成者が付けたラベル（「billing」、「support」）と、ユーザーが実際に入力するタスクのフレーズ（「返金を依頼する」、「顧客が返金を希望している」）の両方を含めます。インデックス化されます。簡潔な意図を示すプロンプトは、ここで照合されます。
• tools — スキルの本文が呼び出すツールの ID です。型付きの依存関係エッジです。スキルが一致すると、search_capabilities がツールのバケットにこれらのツールを表示します。インデックス化されません。
• metadata — プッシュパスのランキングやブーストに使うプロジェクトコンテキストです。例：{"stacks": ["react"]}。インデックス化されません。
• body — プロンプトのセクションから取り出し、単独で機能するようにした、実際のプレイブックのテキストです。get_skill_content を介して必要に応じて読み込まれるディスパッチペイロードです。インデックス化されません。

Ratel のハイブリッド検索に合わせた各フィールドの作成方法については、references/decomposition-patterns.md を参照してください。語彙検索では説明的な名前、タグ、正確なトリガー語句が評価され、意味検索では言い換えや意図が照合されます。そのため、明確で複数のフレーズからなる説明が、両方の検索に役立ちます。description と tags の作業は、/ratel-tune-definitions と相互にリンクしてください。

Step 5 — 簡潔なコアプロンプトを作成する

コアに残すセクションを新しいコアプロンプトにまとめます。含めるのは役割、安全性とポリシー、出力の契約のみです。加えて、エージェントが利用可能なスキルを持ち、手順が必要なターンではそれらを取得する必要があることを示す短い案内を含めます。新しいコアのトークン量を見積もり、元のものからの削減量も示します。

Step 6 — 登録の接続方法を示す

抽出したスキルの登録方法と、機能ツール（search_capabilities、get_skill_content）の接続方法を、TS と Python の両方のコード形式で示します（取得した API に合わせて調整してください）。

TypeScript（@ratel-ai/sdk）：

import { SkillCatalog, Skill, searchCapabilitiesTool, getSkillContentTool } from "@ratel-ai/sdk";

const skillCatalog = new SkillCatalog();
skillCatalog.register(new Skill({
  id: "refund-flow",
  name: "Refund flow",
  description: "Process a customer refund end to end. Use when the user wants money back, disputes a charge, or asks to cancel and refund an order.",
  tags: ["billing", "support", "issue a refund", "customer wants money back"],
  tools: ["lookup_order", "issue_refund"],
  metadata: { stacks: ["node"] },
  body: "/* the refund playbook lifted from the old prompt, made self-contained */",
}));

// Skills are ranked alongside tools; pass the skill catalog into the capability tools.
const tools = {
  search_capabilities: searchCapabilitiesTool(toolCatalog, skillCatalog),
  get_skill_content: getSkillContentTool(skillCatalog),
  // invoke_tool: invokeToolTool(toolCatalog),
};

Python（ratel-ai）：

from ratel_ai import SkillCatalog, Skill, search_capabilities_tool, get_skill_content_tool

skill_catalog = SkillCatalog()
skill_catalog.register(Skill(
    id="refund-flow",
    name="Refund flow",
    description="Process a customer refund end to end. Use when the user wants money back, disputes a charge, or asks to cancel and refund an order.",
    tags=["billing", "support", "issue a refund", "customer wants money back"],
    tools=["lookup_order", "issue_refund"],
    metadata={"stacks": ["python"]},
    body="""...refund playbook, self-contained...""",
))

tools = {
    "search_capabilities": search_capabilities_tool(tool_catalog, skill_catalog),
    "get_skill_content": get_skill_content_tool(skill_catalog),
}

計画では、次の 2 つの提示メカニズムに留意してください。

• PULL — search_capabilities がランク付けされたスキルのバケットをツールとともに返します。エージェントはツールに関連する作業を行う際にスキルを取得し、get_skill_content でその本文を読み込みます。ツールを使用する手順から抽出したスキルでは、これがデフォルトです。
• PUSH — UserPromptSubmit のプリロードフックが、明確な勝者となるスキルをツールを使わない意図プロンプトに挿入します。これは実験的な機能で、明確な勝者ルールによって制御されます。曖昧さのない意図に明確に対応するスキルに限って推奨し、プッシュパスのブーストには metadata を活用してください。

スキルは Ratel が管理するフォルダー（デフォルトでは ~/.ratel/skills/）に格納されます。顧客が抽出したスキルの書き込み先を明記してください。

Step 7 — 計画を作成する

<repo>/.ratel/ratel-decompose-prompt.md に出力します。セクションの順序は次のとおりです。

1. 概要 — 元のプロンプトの場所とトークン量、提案するコアのトークン量、抽出したスキルの数、各ターンで期待できる削減量。箇条書きは最大6つです。
2. 最新ドキュメントの参照先 — この計画の作成に使用した Ratel のバージョンとドキュメントの参照先。
3. 提案する簡潔なコアプロンプト — 書き換え後のコア全文。そのまま貼り付けられる状態にします。
4. スキル一覧 — スキル ID、名前、ソースのセクション、抽出したトークン量、提示モード（PULL/PUSH）を含む表。
5. スキルごとの SKILL 定義 — 各スキルについて、すべてのデータモデルフィールドを記入します。
6. 登録の配線 — 顧客のスタックとスキルフォルダーの場所に合わせた TS/Python のスニペット。
7. 次のステップ — 抽出したスキルの説明とタグを検索向けに調整するため、/ratel-tune-definitions を案内します。

一覧表はチャット内に表示し、ファイルのパスをユーザーに伝えてください。計画の本文全体をチャットに貼り付けないでください。

正直なスキップ方法

次の2つの場合はスキップします。

1. システムプロンプトが見つからない場合。 ステップ1でシステムプロンプトまたは指示プロンプトが見つからなければ、そこで停止します。何を検索したかをユーザーに伝え、通常とは異なる場所にプロンプトがある場合は、その場所を示すよう依頼してください。確認できないプロンプトの分解内容を作り上げないでください。
2. プロンプトがすでに短い、または適切に分割されている場合。 プロンプトが小さい（おおよそ800トークン未満）か、薄いコアと外部化された手順にすでにきれいに分割されている場合は、その旨を伝えて停止します。簡潔なプロンプトを分解すると、各ターンの削減効果がないまま、検索のオーバーヘッドと維持が必要なカタログが増えます。プロンプトが大きくなったら再検討するよう伝えてください。

参照ファイル

• references/decomposition-patterns.md — 一般的なプロンプトのセクションと、コアに残すかスキルとして抽出するかの対応表、分解前後の例、Ratel のハイブリッド検索に基づく Skill 作成のフィールドごとのガイダンスを掲載しています。

参照元（内容を複製しない）：

• ../ratel-tune-definitions/references/definition-rubric.md — 抽出したスキルの説明とタグの評価基準です。