巨大なプロンプトを分割してエージェントのトークン浪費を減らす方法

システムプロンプト1つにあらゆるガイドラインやツールを詰め込むモノリシックな構造は、すぐに限界を迎えます。対話が少し長くなるだけでも、エージェントはプロンプトの途中に書いた指示を忘れてしまいます。リクエストごとに数万トークンを重複して送信するため推論コストが高騰し、最初のトークンが表示されるまでに長い時間がかかります。

実務では、agentskills.ioオープン仕様ベースの段階的コンテキスト読み込み構造でこの問題を解決します。必要な瞬間だけに適切なスキルを呼び出し、トークンを節約する方式です。

独立したマークダウンのスキルファイルに分離する基準

モノリシックなシステムプロンプトは、ドメインの境界、ツール実行の権限、実行頻度を基準に分割する必要があります。単一セッションで同時に有効化するスキルを3つ以下に抑えることで、埋め込み類似度検索時にスキル同士が競合する現象を防ぎます。

分離したスキルファイルの先頭には、ハイフンと英字小文字、数字のみを使用した識別子と、動作目的を明記したYAMLフロントマターを記述します。

`yaml

name: backend-api-generator
description: Generates Spring Boot REST API controller and service boilerplate code. Use when the user asks to create API endpoints, build REST controllers, or define DTO mappings for backend services.
when_to_use:

User requests new REST API endpoint creation
User provides database schema and asks for controller layer implementation
Do NOT use for: database migration SQL, frontend component generation
allowed-tools:
read_file
write_file
list_directory
effort: medium

段階的な読み込み構造を作るプロセスはシンプルです。

エージェントの初期化時に、ディレクトリ内のすべてのスキルのYAMLフロントマターメタデータ（1スキルあたり約100トークン）のみをプロンプトに読み込みます。
ユーザーからのリクエストが入ると、スキルの説明文と意味的類似性を比較し、必要なスキルの本文のみを動的に呼び出します。
実行段階で、本文の指示に従って必要な補助スクリプトを実行し、結果の値のみをコンテキストに含めます。

15,000〜30,000トークンを常時占有していたモノリシック構造をSKILL.mdの遅延読み込み構造に変更すると、初期トークンのオーバーヘッドが90%以上削減されます。Anthropicの内部テスト資料によると、p95の遅延時間を12%から40%まで短縮し、対話あたりの平均トークン消費量を29.6%削減できます。

コンテキストの汚染を防ぐ内部の制約事項

複数のスキルが連鎖的に読み込まれる際、前のスキルの指示がセッションに残って次の作業を歪めてしまう現象が頻発します。高リスクな検査やログが多く残る作業では、YAMLフロントマターに下位コンテキスト分岐（context: fork）の設定を追加して、プロセスレベルで隔離する必要があります。

`yaml

name: security-vulnerability-auditor
description: Audits backend source code for OWASP top 10 security flaws. Use when auditing code security or checking for SQL injection vulnerabilities.
context: fork
model: claude-sonnet-4-20250514
effort: high

入出力データ契約（Data Contract）を明確に定義する作業も欠かせません。

YAMLメタデータに引数構造体と許可されたツールのリスト（allowed-tools）を宣言し、任意のBash実行や無分別なネットワーク呼び出しを防ぎます。
本文内にマークダウンのラッピングがない純粋なJSON形式の出力スキーマ規則を明記します。
対話セッションには最終成果物のみを返すよう、指示を制限します。

`markdown

Output Schema Contract

All responses must strictly adhere to the following JSON structure without markdown wrapping:
{
"status": "SUCCESS" | "FAILED",
"generated_files": [
{
"path": "string",
"content": "string"
}
],
"error_message": "string | null"
}

子プロセスとして隔離すれば、ツール呼び出しのログがメインセッションにあふれ出す事態を防ぐことができます。メインの対話セッションがクリーンに保たれるため、サブエージェント間でデータをやり取りする際のエラー発生確率も下がります。

無限ループを遮断する防御コードの設計

要件が曖昧であったりツール呼び出しのエラーが繰り返されたりすると、エージェントは無限再試行ループに陥ります。わずか数分で数十ドルのAPI費用が消えていく瞬間です。スキルファイルの本体に段階的な静的検証チェックリスト（Verification Checklist）を仕込んでおけば、エージェントが作業を完了する前に自ら検証を実行します。

`markdown

Execution & Self-Testing Protocol

Before declaring the task finished, you MUST sequentially execute the following verification checklist:

[Pre-check] Verify that all required input parameters are present. If mandatory arguments are missing, STOP immediately and ask the developer for input.
[Generation] Write the requested implementation code.
[Syntax Verification] Check the written code for missing imports, unresolved symbols, and syntax errors.
[Self-Correction] If a syntax error is identified, attempt correction ONCE. Do not re-run the file write tool more than twice for the same error.

物理的にループを断ち切るサーキットブレーカー（Circuit Breaker）の書き方も簡単です。

スキルの先頭に最大ツール呼び出し数（MAXIMUM_TOOL_CALL_LIMIT: 3）を明記します。
同じエラーコードが2回連続で発生した場合、追加のツール呼び出しを停止する制約条件を記述します。
停止条件に引っかかったら直ちに実行を止め、通知のフォーマットを出力するよう指示します。

`markdown
[SKILL EXECUTION HALTED]
Skill Name: backend-api-generator
Failure Reason: [Brief error description]
Attempts Made: [Number of retries]
Suggested Action: [Action required by backend developer]

ファイルの削除やDBのドロップといった危険な作業には、disable-model-invocation: trueオプションを設定しておく方が安全です。エージェントが勝手に呼び出せないようにブロックし、開発者が直接スラッシュコマンド（/skill-name）を入力したときのみ実行されるよう制限します。

チーム共有リポジトリのバージョン管理とデプロイ

チームメンバーと一緒にスキルを作成する際は、agentskills.io標準のディレクトリ構造に従うことで、マークダウンファイルの競合に悩まされずに済みます。上位フォルダの中に、本文、CLIスクリプト、参照ドキュメント、静的テンプレートのアセットを明確に分けて配置します。

ディレクトリおよびファイルパス	役割	作成指針
skills/api-generator/SKILL.md	必須のエントリポイント文書	YAMLフロントマターとコア手順の指示を含む（500行以内）
skills/api-generator/scripts/	実行可能コードフォルダ	エージェントが必要に応じて呼び出すPython/BashのCLIスクリプトの配置場所
skills/api-generator/references/	補助参照ドキュメントフォルダ	大規模API仕様、DBスキーマ、スタイルガイド文書を収載
skills/api-generator/assets/	静的リソーステンプレートフォルダ	生成コードのボイラープレート、設定ファイルの見本を保存

スキルの品質を検証する際は、promptfoo評価フレームワークを活用します。

promptfooconfig.yamlファイルに、テスト対象のSKILL.mdのパスとLLMモデルを指定します。
意図の合致やJSONフォーマットの遵守有無を検証するテストケースを記述します。
ターミナルで npx promptfoo@latest eval コマンドを実行し、指示の遵守率を測定します。

`yaml
description: "Backend Agent Skills Validation Suite"
prompts:

"file://skills/api-generator/SKILL.md"
providers:
id: "anthropic:messages:claude-3-5-sonnet-20241022"
tests:
description: "Test automatic skill activation for REST API generation query"
vars:
user_query: "Create a Spring Boot REST Controller for User Management."
assert:
- type: icontains
  value: "backend-api-generator"
- type: javascript
  value: "output.includes('@RestController') && output.includes('ResponseEntity')"

デプロイ時は、短命なブランチを使用するトランクベース開発戦略とGitタグ（v1.2.0）を組み合わせます。プロダクション環境でエージェントが予期せぬ動作をした場合、 git checkout tags/v1.1.0 -b hotfix/rollback コマンドで以前のタグ時点へ即座にロールバックできます。

巨大なプロンプトを分割してエージェントのトークン浪費を減らす方法

独立したマークダウンのスキルファイルに分離する基準

分離したスキルファイルの先頭には、ハイフンと英字小文字、数字のみを使用した識別子と、動作目的を明記したYAMLフロントマターを記述します。

`yaml

User requests new REST API endpoint creation
User provides database schema and asks for controller layer implementation
Do NOT use for: database migration SQL, frontend component generation
allowed-tools:
read_file
write_file
list_directory
effort: medium

段階的な読み込み構造を作るプロセスはシンプルです。

エージェントの初期化時に、ディレクトリ内のすべてのスキルのYAMLフロントマターメタデータ（1スキルあたり約100トークン）のみをプロンプトに読み込みます。
ユーザーからのリクエストが入ると、スキルの説明文と意味的類似性を比較し、必要なスキルの本文のみを動的に呼び出します。
実行段階で、本文の指示に従って必要な補助スクリプトを実行し、結果の値のみをコンテキストに含めます。

コンテキストの汚染を防ぐ内部の制約事項

`yaml

name: security-vulnerability-auditor
description: Audits backend source code for OWASP top 10 security flaws. Use when auditing code security or checking for SQL injection vulnerabilities.
context: fork
model: claude-sonnet-4-20250514
effort: high

入出力データ契約（Data Contract）を明確に定義する作業も欠かせません。

YAMLメタデータに引数構造体と許可されたツールのリスト（allowed-tools）を宣言し、任意のBash実行や無分別なネットワーク呼び出しを防ぎます。
本文内にマークダウンのラッピングがない純粋なJSON形式の出力スキーマ規則を明記します。
対話セッションには最終成果物のみを返すよう、指示を制限します。

`markdown

Output Schema Contract

無限ループを遮断する防御コードの設計

`markdown

Execution & Self-Testing Protocol

Before declaring the task finished, you MUST sequentially execute the following verification checklist:

[Pre-check] Verify that all required input parameters are present. If mandatory arguments are missing, STOP immediately and ask the developer for input.
[Generation] Write the requested implementation code.
[Syntax Verification] Check the written code for missing imports, unresolved symbols, and syntax errors.
[Self-Correction] If a syntax error is identified, attempt correction ONCE. Do not re-run the file write tool more than twice for the same error.

物理的にループを断ち切るサーキットブレーカー（Circuit Breaker）の書き方も簡単です。

スキルの先頭に最大ツール呼び出し数（MAXIMUM_TOOL_CALL_LIMIT: 3）を明記します。
同じエラーコードが2回連続で発生した場合、追加のツール呼び出しを停止する制約条件を記述します。
停止条件に引っかかったら直ちに実行を止め、通知のフォーマットを出力するよう指示します。

チーム共有リポジトリのバージョン管理とデプロイ

ディレクトリおよびファイルパス	役割	作成指針
skills/api-generator/SKILL.md	必須のエントリポイント文書	YAMLフロントマターとコア手順の指示を含む（500行以内）
skills/api-generator/scripts/	実行可能コードフォルダ	エージェントが必要に応じて呼び出すPython/BashのCLIスクリプトの配置場所
skills/api-generator/references/	補助参照ドキュメントフォルダ	大規模API仕様、DBスキーマ、スタイルガイド文書を収載
skills/api-generator/assets/	静的リソーステンプレートフォルダ	生成コードのボイラープレート、設定ファイルの見本を保存

スキルの品質を検証する際は、promptfoo評価フレームワークを活用します。

promptfooconfig.yamlファイルに、テスト対象のSKILL.mdのパスとLLMモデルを指定します。
意図の合致やJSONフォーマットの遵守有無を検証するテストケースを記述します。
ターミナルで npx promptfoo@latest eval コマンドを実行し、指示の遵守率を測定します。

`yaml
description: "Backend Agent Skills Validation Suite"
prompts:

"file://skills/api-generator/SKILL.md"
providers:
id: "anthropic:messages:claude-3-5-sonnet-20241022"
tests:
description: "Test automatic skill activation for REST API generation query"
vars:
user_query: "Create a Spring Boot REST Controller for User Management."
assert:
- type: icontains
  value: "backend-api-generator"
- type: javascript
  value: "output.includes('@RestController') && output.includes('ResponseEntity')"

巨大なプロンプトを分割してエージェントのトークン浪費を減らす方法

관련 영상

▲ コミュニティセッション：スキルの作成と公開方法

巨大なプロンプトを分割してエージェントのトークン浪費を減らす方法

独立したマークダウンのスキルファイルに分離する基準

`yaml

コンテキストの汚染を防ぐ内部の制約事項

`yaml

name: security-vulnerability-auditor
description: Audits backend source code for OWASP top 10 security flaws. Use when auditing code security or checking for SQL injection vulnerabilities.
context: fork
model: claude-sonnet-4-20250514
effort: high

Output Schema Contract

無限ループを遮断する防御コードの設計

Execution & Self-Testing Protocol

チーム共有リポジトリのバージョン管理とデプロイ

커뮤니티의 다른 글

사내 시스템에 llm api 붙일 때 마주하는 현실적인 한계와 대응법

레거시 백엔드에 GPT-6 Astra 붙일 때 예산 승인과 보안 통과를 먼저 끝내는 법이 있습니다

에이전트끼리 대화하다 6천만 원 청구서가 나오는 이유

사내 RAG 벡터 검색에 Okta 권한 필터를 직접 거는 방법

브라우저 에이전트에게 내 구글 계정을 통째로 넘기면 안 되는 이유

Apple Won the AI Race

댓글 (0)

巨大なプロンプトを分割してエージェントのトークン浪費を減らす方法

独立したマークダウンのスキルファイルに分離する基準

`yaml

コンテキストの汚染を防ぐ内部の制約事項

`yaml

name: security-vulnerability-auditor
description: Audits backend source code for OWASP top 10 security flaws. Use when auditing code security or checking for SQL injection vulnerabilities.
context: fork
model: claude-sonnet-4-20250514
effort: high

Output Schema Contract

無限ループを遮断する防御コードの設計

Execution & Self-Testing Protocol

チーム共有リポジトリのバージョン管理とデプロイ

巨大なプロンプトを分割してエージェントのトークン浪費を減らす方法

独立したマークダウンのスキルファイルに分離する基準

`yaml

コンテキストの汚染を防ぐ内部の制約事項

`yaml

name: security-vulnerability-auditordescription: Audits backend source code for OWASP top 10 security flaws. Use when auditing code security or checking for SQL injection vulnerabilities.context: forkmodel: claude-sonnet-4-20250514effort: high

Output Schema Contract

無限ループを遮断する防御コードの設計

Execution & Self-Testing Protocol

チーム共有リポジトリのバージョン管理とデプロイ

커뮤니티의 다른 글

사내 시스템에 llm api 붙일 때 마주하는 현실적인 한계와 대응법

레거시 백엔드에 GPT-6 Astra 붙일 때 예산 승인과 보안 통과를 먼저 끝내는 법이 있습니다

에이전트끼리 대화하다 6천만 원 청구서가 나오는 이유

사내 RAG 벡터 검색에 Okta 권한 필터를 직접 거는 방법

브라우저 에이전트에게 내 구글 계정을 통째로 넘기면 안 되는 이유

Apple Won the AI Race

댓글 (0)

巨大なプロンプトを分割してエージェントのトークン浪費を減らす方法

独立したマークダウンのスキルファイルに分離する基準

`yaml

コンテキストの汚染を防ぐ内部の制約事項

`yaml

name: security-vulnerability-auditordescription: Audits backend source code for OWASP top 10 security flaws. Use when auditing code security or checking for SQL injection vulnerabilities.context: forkmodel: claude-sonnet-4-20250514effort: high

Output Schema Contract

無限ループを遮断する防御コードの設計

Execution & Self-Testing Protocol

チーム共有リポジトリのバージョン管理とデプロイ

name: security-vulnerability-auditor
description: Audits backend source code for OWASP top 10 security flaws. Use when auditing code security or checking for SQL injection vulnerabilities.
context: fork
model: claude-sonnet-4-20250514
effort: high

name: security-vulnerability-auditor
description: Audits backend source code for OWASP top 10 security flaws. Use when auditing code security or checking for SQL injection vulnerabilities.
context: fork
model: claude-sonnet-4-20250514
effort: high