SKILLOfficialautomation

prompt-review

プラグイン: synthflow
ソース: GitHub で見る ↗

説明

AIボイスエージェント（音声で自動応答するAI）のプロンプト（指示文）を検査し、以下の問題がないか確認します。特にSynthflow Single-Promptを対象とします： - 矛盾や不整合 - 文脈の欠落 - 不安全なツール・動作 - 対応の段階的エスカレーション（問題の段階的な引き継ぎ）における欠陥 - コンプライアンス（規制対応）上のリスク - 機能低下や劣化のリスク次のような場合に使用：ユーザーがプロンプトを導入前に検査・監査・検証・改善・比較することを依頼した場合

原文を表示

Review AI voice-agent prompts, especially Synthflow Single-Prompt, for contradictions, missing context, unsafe tool/action behavior, escalation gaps, compliance risk, and regression risk. Use this when the user asks to review, audit, validate, improve, or compare a prompt before deployment.

ユースケース

AIボイスエージェントのプロンプトを検査する
導入前にプロンプトを監査・検証する
プロンプトの矛盾や欠落を検出する
コンプライアンスリスクを確認する
エスカレーション欠陥を改善する

本文（日本語訳）

プロンプトレビュースキル

目的

AIエージェントのプロンプト（指示文）を、テスト・本番環境へのデプロイ・編集の前に確認します。プロンプトが信頼性があり、具体的で、安全であり、利用可能なツール・アクション（機能）と一致しており、実際の顧客対応に適しているかどうかに焦点を当てます。

特に以下の場合に有用です：Synthflowの音声エージェント、シングルプロンプトエージェント、フローデザイナーのノードプロンプト、転送フロー、エスカレーション（問題の段階的引き上げ）ロジック、サポート・営業・適格性判定・予約エージェント、そして通話動作を制御するあらゆるプロンプト。

MCPを使用したプロンプトの取得

Synthflowワークスペースに格納されているプロンプトの場合、Synthflow MCPツールで取得します：get_agentで現在のプロンプトと設定を、get_agent_actions／get_actionでプロンプトが従う必要があるアクション説明を、list_agent_versions／get_agent_version_diffで編集時の回帰リスク（変更による副作用）を比較する際に使用します。Synthflowの機能の実装を確認するには、search_docsで公式ドキュメントを検索するか、ワークスペースツールがまだ接続されていない場合はsynthflow-docsサーバーのsearchDocsツールで検索します。

コアレビュー原則

優れたプロンプトは、背景情報がない人間のオペレーターにも理解できます。

「別の人が読むテスト」（OpenAIが推奨する確認方法）：プロンプトを同僚に読み聞かせてください。同僚がエージェントの役割を平易な言葉で言い直せなければ、言語モデルも確実には実行できません。

背景情報ゼロで18歳が同じやり方を2回実行できる明確さを目指してください。曖昧な性格描写より、具体的な行動指示を優先します。

❌ 悪い例：「親切で専門的であること。」
✅ 良い例：「1ターンで1～2文。1回に1つの質問だけ。発信者が価格について質問したら、承認された価格範囲を提示し、コンサルテーション予約を希望するか尋ねること。」

曖昧な動詞を、具体的でテスト可能な行動に置き換えます：

❌ 曖昧	✅ 具体的
「発信者に専門的に対応する」	「1文／ターン、相手の調子に合わせ、俗語なし」
「適切なバッテリーを見つけるのを手伝う」	「年式／メーカー／車種／グレードを質問、在庫ある2商品をSKU・価格・保証付きで提示」
「顧客を確認する」	「名前・電話・注文参照番号を収集、各項目を読み返し、『合っていますか、はい或いはいいえ？』と質問」
「親切であること」	（削除 — 実行不可能）

背景・動作・出力構造

Synthflowのプロンプトは、以下の3つのセクションにこの順序で、見出し付きで分けて構成すべきです：

セクション	内容
背景	エージェントの身分、企業、状況、店舗・アカウントのコンテキスト、方針、役割、目標、発信者の文脈、変数、顧客固有の制限
動作	条件分岐ロジック、フロー、「Xの場合Yを実行」、ツール・アクショントリガー（起動条件）、予約・転送・エスカレーション・フォールバック・通話終了ルール、反論・エラー対応
出力	文の長さ、書式、言語、数字・日付・金額の音声表現 — 書式設定のみ

報告すべき典型的な配置ミス：出力セクション内の条件ルール（「商用発信者の場合は転送」）、最上部の「重大ルール」ブロック（3つすべてを混在）。フローの「出力」がツール呼び出しである場合、それは動作セクションに属します。

注記 — 決定的なステップバイステップフロー： 多くのエンタープライズ顧客は「ステップ1、2、7」形式のプロンプトを作成します。分け方は同じですが、出力は書式設定・スタイルのみに縮小します。構造変更を強制するのではなく、この仮定を述べてください。

機械的チェックを最初に実施

これらは客観的で自動化できるほどです。失敗があれば報告してください。

ツール数予算：1エージェントあたり≤20のツール呼び出し。
トークン長：18万トークン未満で合格 · 18～20万で警告 · 20万超で不合格、リリース停止。
変数・キャッシュ規律：固定コンテンツが先；変数は名前のみで参照し、本文内に波括弧を使わない；末尾の専用ブロックで解決。本文内の早期の{vars}インライン参照はプロンプトキャッシング（中程度の副作用）を破壊。
ルール配置：太い「重大ルール～必読」ブロックなし；各ルールは制御する動作の隣に配置；最も重大な2～3項目の繰り返しだけは最後に可。
物理的に不可能な指示：言語モデルに時計がない、ターン間でカウントできない、ターン間で「考える」ことができない、「知識ベースを使う」よう指示すべきではない（Synthflowが自動で並行実行）、トーン採用も指示すべきではない（トーンは音声指示に属し、システムプロンプトではない）。

詳細と修正表：**references/mechanical-checks.md**を参照。

レビュー範囲

これらの分類すべてについてプロンプトをレビューしてください。分類ごとの詳細チェックリストは**references/review-checklists.md**にあります — 結果を検討する際に確認してください。

矛盾・重複指示 — プロンプト全体で両立できない指示。
ビジネスコンテキスト不足・役割境界不明 — エージェントは安全で一貫した業務遂行に十分な情報を持っていますか？
ツール・アクション・転送・知識指示 — トリガー、正確な名前、引数・列挙値、戻り値・空・エラー処理、兄弟アクション（同レベル）の区別、書き込み前の確認。プロンプトとSynthflow UI のアクション説明が一致している必要があります。 ツール・説明が提供されていない場合、レビューを利用可能なツールコンテキストが必要とマークし、不完全と判定してください — 推測で補わないでください。アクション説明の作成ルール：**references/action-descriptions.md**を参照。
転送・エスカレーション・フォールバック・通話終了 — すべてのパスにトリガーと安全な確認ポイントが必要。「適切なときに通話を終了」を明確な閾値に置き換えてください。
コンプライアンス・安全・顧客固有リスク — 規制対象の助言、機密データ、同意、保証、AI身分開示。長い禁止事項リストより、3～5個の強力な運用ガードレールを優先。
回帰リスク（編集版を比較する場合） — 削除されたコンテキスト・トリガー・ガードレール、変更されたしきい値、出力セクションに移動した動作、弱化した例、キャッシング性能を損なう変数変更。

重大度レベル

重大 — 不安全な動作、コンプライアンス露出、無許可のデータ収集、誤った転送、でたらめなツール呼び出し、本番環境障害。（例：カード番号を収集、許可されていない規制対象助言、コアワークフローの非存在ツール、確認なしに予約、矛盾したコアワークフロー指示、失敗した重大ツールのフォールバック不在、完了前に通話終了可能、20万超トークン）
高 — 一般的なシナリオで矛盾か失敗の可能性。（営業時間不足、曖昧なトリガー、不明確な転送パス、未定義の必須フィールド、プロンプト・説明の矛盾、反論処理不足、空結果のリカバリなし）
中 — 動作するが信頼性・保守性・ユーザー体験に問題。（曖昧指示、重複ルール、長いトーン説明、配置ミス、出力内の動作、音声書式設定不足、早期インライン{vars}、物理的に不可能な指示）
低 — 軽微な調整。

レビュー方法

エージェント類型を特定（シングルプロンプト、フローノード、転送ノード、ツール指示、知識ベース重視、予約、適格性判定、サポート、営業、受付、内部QA）。不明な場合は仮定を述べます。
意図されたワークフローを平易な英語で抽出。できない場合は、コンテキスト不足として報告。
背景・動作・出力・ガードレール・変数・例・ツール説明にコンテンツをマッピング。配置ミスを報告。
機械的チェックを実施（上記）。
具体性確認 — 曖昧な指示ごと：エージェントは2通りの実行ができますか？トリガー、成功条件、失敗パスがありますか？具体的な動作に書き直す。
ツール・アクション整合性確認（利用可能なツールとUI説明と照合）。プロンプト vs 説明の矛盾を報告。説明なしは不完全。
転送・通話終了ゲート確認。
業界別コンプライアンス・安全確認；業界不明な場合は一般サポートガードレール適用し、業界コンプライアンスが不足と報告。
例確認 — 標準パス、エッジケース、エラーリカバリ；指示と矛盾する例を報告。
回帰リスク確認（旧・新バージョン提供時）；シミュレーション推奨。

出力形式

**references/output-template.md**の構造を使用してレビューを作成します（エグゼクティブサマリ → 結果 → 不足情報 → 回帰リスク → 推奨テスト → 改善プロンプト案・任意）。該ファイルには採点ルーブリックと具体例も含まれます。

結果は実行可能に — すべての結果に具体的な推奨を含め、「これをもっと明確に」ではなく。

特別ルール

ビジネスロジックを推測しない — 推測による価格設定、方針、法的要件、転送先、ツール厳禁。不足情報を報告し、安全なプレースホルダを提供。
過度に書き直さない — デフォルトはレビュー、書き直しではない。ユーザーが要望した場合、または修正が小規模・局所的で方針推測が不要な場合のみ書き直す。
意図を保存 — ビジネス目標、エージェント身分、トーン、ワークフロー、ツール名、コンプライアンス制約、有効な例は変えない。
小さくテスト可能な変更を優先 — 1回に1つの動作；本番プロンプトデプロイ前にシミュレーション・テスト通話を推奨。

最終確認

レビューが完全なのは、以下に答える場合のみです：(1)実通話で何が悪くなるか、(2)プロンプトに基づく理由、(3)プロンプトの変更方法、(4)デプロイ前のテスト内容。

改善提案は最大5個。最終レポート後、ユーザーに変更の適用を希望するかどうか確認してください。

原文（English）を表示

Prompt Review Skill

Purpose

Review an AI agent prompt before it is tested, deployed, or edited in production. Focus on whether the prompt is reliable, specific, safe, aligned with available tools/actions, and suitable for real customer conversations.

Especially useful for Synthflow voice agents, Single-Prompt agents, Flow Designer node prompts, transfer flows, escalation logic, support/sales/qualification/booking agents, and any prompt that controls call behavior.

Getting the material over MCP

When the prompt lives in a Synthflow workspace rather than in the conversation, pull it with the Synthflow MCP tools: get_agent for the live prompt and settings, get_agent_actions / get_action for the action descriptions the prompt must agree with, and list_agent_versions / get_agent_version_diff when comparing an edit for regression risk. To check how a Synthflow feature actually works, search the official docs with search_docs, or with the searchDocs tool on the synthflow-docs server if the workspace tools aren't connected yet.

Core Review Philosophy

A good prompt is understandable by a human operator with no hidden context.

The "another human" test (OpenAI's recommended check): read the prompt aloud to a teammate. If they can't restate what the agent should do in plain English, the LLM won't reliably do it either.

Write so an 18-year-old with zero context could execute it the same way twice. Prefer concrete behavioral instructions over vague personality instructions.

Bad: Be helpful and professional.
Better: Use one or two sentences per turn. Ask one question at a time. If the caller asks about pricing, give the approved price range and ask whether they want to book a consultation.

Replace vague verbs with specific, testable behavior:

❌ Vague	✅ Specific
"Handle the caller professionally"	"One sentence per turn, mirror their tone, no slang"
"Help them find the right battery"	"Ask year/make/model/trim, then present 2 in-stock SKUs with price + warranty"
"Verify the customer"	"Collect name, phone, order ref. Read each back. Ask 'is that correct, yes or no?'"
"Be helpful"	(delete — not actionable)

Background / Behavior / Output structure

A Synthflow prompt should split cleanly into three sections, in this order, with headers:

Section	Contains
Background	Who the agent is, company, situation, store/account context, policies, role, goal, caller context, variables, customer-specific restrictions
Behavior	Conditional logic, flows, "if X then Y", tool/action triggers, booking/transfer/escalation/fallback/end-call rules, objection and error handling
Output	Sentence length, format, language, spoken forms for numbers/dates/money — formatting only

Common misplacements to flag: conditional rules inside Output ("if commercial caller, transfer"); a "Critical Rules" block at the top mixing all three. If a flow's "output" is a tool call, that lives in Behavior, not Output.

Caveat — deterministic step-by-step flows: many enterprise customers write "step 1, 2, 7" prompts. The split still applies, but Output collapses to formatting/styling only. State this assumption rather than forcing a restructure.

Run the mechanical checks first

These are objective and near-automatable. Flag any failure.

Tool budget: ≤ 20 tool calls per agent.
Token length: < 180k pass · 180k–200k warning · > 200k fail, block release.
Variable / cache discipline: fixed content first; reference variables by name only, no curly braces in the body; resolve them in a trailing block. Early inline {vars} break prompt caching (Medium regression).
Rules placement: no fat "CRITICAL RULES — READ FIRST" block; put each rule next to the behavior it governs; repeating only the 2–3 most critical at the end is fine.
Physically-impossible instructions: the LLM has no clock, can't count across turns, can't "think" between turns, and shouldn't be told to "use the knowledge base" (it's a parallel process Synthflow runs automatically) or to adopt a tone (tone lives in speech instructions, not the system prompt).

Full detail and the fix-it table: references/mechanical-checks.md.

Review scope

Review every prompt for these categories. Detailed checklists per category are in references/review-checklists.md — read it when working through findings.

Contradictions / duplicated instructions — instructions that can't both be true, across the whole prompt.
Missing business context / unclear role boundaries — does the agent know enough to do the job safely and consistently?
Tool, action, transfer, knowledge instructions — trigger, exact name, arguments/enums, return/empty/error handling, sibling disambiguation, confirmation before writes. Prompt and the Synthflow UI action-description must agree. If tools/descriptions aren't provided, mark the review Needs available-tool context and incomplete — do not invent them. Action-description authoring rules: see references/action-descriptions.md.
Transfer / escalation / fallback / call-ending — every such path needs a trigger and a safe confirmation point. Replace "end the call when appropriate" with a hard gate.
Compliance, safety, customer-specific risk — regulated advice, sensitive data, consent, guarantees, AI-identity disclosure. Prefer 3–5 strong operational guardrails over long negative lists.
Regression risk (when comparing an edit) — removed context/triggers/guardrails, changed thresholds, behavior moved into Output, weakened examples, variable changes that hurt caching.

Severity levels

Critical — unsafe behavior, compliance exposure, unauthorized data collection, wrong transfers, hallucinated tool calls, production-breaking. (e.g. collects card numbers; regulated advice when disallowed; non-existent tool in core workflow; books without confirmation; contradictory core-workflow instructions; no fallback for a failed critical tool; can end call before completion; > 200k tokens.)
High — likely inconsistent or fails in common scenarios. (missing business hours for booking; ambiguous trigger; unclear transfer path; undefined required fields; prompt/description conflict; missing objection handling; no recovery for empty results.)
Medium — works but reliability/maintainability/UX issues. (vague instructions; duplicated rules; long tone descriptions; misplaced rules; behavior in Output; missing spoken-formatting; early inline {vars}; physically-impossible instruction.)
Low — minor polish.

Review method

Identify the agent type (Single-Prompt, Flow node, transfer node, tool instruction, KB-heavy, booking, qualification, support, sales, receptionist, internal QA). State assumptions if unclear.
Extract the intended workflow in plain English. If you can't, flag missing context.
Map content into Background / Behavior / Output / Guardrails / Variables / Examples / Tool descriptions. Flag misplacements.
Run the mechanical checks (above).
Check specificity — for each vague instruction: could the agent do it two ways? Is there a trigger, a success condition, a failure path? Rewrite into concrete behavior.
Check tool/action alignment against available tools and their UI descriptions. Flag prompt-vs-description conflicts. Incomplete without descriptions.
Check transfer and end-call gates.
Check compliance and safety for the industry; if unknown, apply general support guardrails and flag industry compliance as missing.
Check examples — happy path, edge case, error recovery; flag examples that contradict instructions.
Check regression risk if old and new versions are provided; recommend simulations.

Output format

Produce the review using the structure in references/output-template.md (executive summary → findings → missing information → regression risks → recommended tests → optional improved prompt). That file also contains the scoring rubric and a worked example finding.

Keep findings actionable — every finding includes a concrete recommendation, not "make this clearer."

Special rules

Do not invent business logic — no invented pricing, policies, legal requirements, transfer targets, or tools. Flag missing info and give a safe placeholder.
Do not over-rewrite — default is review, not rewrite. Only rewrite if the user asks, or the fix is small and local and doesn't require inventing policy.
Preserve intent — business goal, agent identity, tone, workflow, tool names, compliance constraints, still-valid examples.
Prefer small, testable changes — one behavior at a time; recommend simulations/test calls before deploying production prompts.

Final reminder

A review is complete only when it answers: (1) what could go wrong in a real call, (2) why, based on the prompt, (3) how the prompt should change, (4) what to test before deployment.

Give a maximum of 5 improvement suggestions. After the final report, ask the user whether they want you to apply the changes.

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。