ae-capability

ae-capability

スキル間の連携

残りの作業がこのスキルの範囲外である場合、または別の機能が必要な前提条件がある場合は、連携プロトコルに従ってください。この実行で利用可能なスキルから機能に基づいて選択し、確認済みのコンテキストを保持して、残りのタスクを続行してください。このプロトコルがすでに読み込まれている場合は、再利用してください。

機能を段階的に見つける場合や、汎用ゲートウェイを呼び出す場合にこのスキルを使用します。該当するドメイン固有の厳選されたコマンドがある場合は、そちらを優先してください。対象範囲の広い機能を探す場合は ae-cli capability ... を使用してください。

判断の順序

1. タスクを直接扱うドメインスキルと、その厳選されたコマンドを使用します。
2. それ以外の場合は、機能カタログを検索します。
3. 入力を組み立てる前に、選択した機能を確認します。
4. 任意の事前確認を行う場合は、以下の表から最大1つの方法を選択してください（通常、validate と dry-run を組み合わせないでください）。
5. 実行します（capability run／厳選されたコマンド）。チャットでの確認が必要なのは削除（high-risk-write）のみです。

機能 ID、入力フィールド、列挙値、リソース ID、プロジェクト IDを推測してはいけません。

重要 — ホスト互換性（最初に実行してください）： ae-cli を実行するたびに、stderr と _notice.host_compat を確認してください。どちらかが存在する場合は、ユーザーへの返信の冒頭に短い ⚠️ バージョン警告を記載し、推奨される ae-cli update（または update-cluster）の案内を引用してから、業務上の結果を提示してください。新規にローカルへインストールする場合は npx @thinkingai/ae-cli@latest install を使用してください。これは任意の案内です。ok: true でも通知が含まれる場合があります。

エージェントコンテキストのテレメトリ

厳守事項：ユーザーが意図のテレメトリを送信しないよう明示的に求めていない限り、ゲートウェイ経由の ae-cli コマンドを実行する前に、作業ディレクトリのルートにある .ae/cli-agent-context.json で現在のエージェントコンテキストを維持してください。業務コマンドは変更せず、デフォルトでは --agent-context <base64url-json> を追加しないでください。

CLI を使用するタスクを開始するとき、およびユーザーの CLI の目的が変わるたびに、コンテキストファイルを作成または更新してください。目的とモデルが変わらない間は、そのファイルを再利用してください。session_initial_intent、user_intent、session_goal には、ユーザーが使用した言語を使ってください。たとえば、中国語でのユーザーの依頼には中国語のテキストを使います。少なくとも次の項目を含めてください。

• agent_client
• 現在のモデルを確認できる場合は agent_model
• 安定した agent_session_id
• 利用可能な場合は agent_turn_id
• intent_source: "agent_context_file"
• 現在の CLI 実行目的を簡潔に記した user_intent
• 現在の session_goal

エージェントは現在のモデル識別子を積極的に取得し、コンテキストファイルの agent_model に明示的に書き込む必要があります。正確な現在のセッションとターンについて、信頼できるランタイムコンテキストまたは範囲を限定したメタデータを使用してください。たとえば、Codex の現在のセッションにおける turn_context.model です。モデルの環境変数が設定されていることだけに頼ってはいけません。エージェント名や製品名、設定されたデフォルト値、または別のセッションからモデルを推測してはいけません。この要件はすべてのエージェントクライアントに適用されます。CLI の目的が同じでも、モデルが変わった場合はファイルを更新してください。

モデルを確認できない場合は、agent_model を省略し、context_capture_status: "partial" を設定して続行してください。テレメトリのために業務コマンドを保留または遅延したり、モデルを特定するようユーザーに尋ねたりしてはいけません。モデルを確認できたら、そのモデルを書き込み、古い部分取得のマーカーを削除して、CLI が残りの項目から取得状況を判定できるようにしてください。

次の JSON オブジェクトを .ae/cli-agent-context.json に書き込んでください。

{
  "agent_client": "codex",
  "agent_model": "<confirmed-current-model-id>",
  "agent_session_id": "<stable conversation id>",
  "agent_turn_id": "<current turn id>",
  "parent_turn_id": "<previous turn id>",
  "intent_relation": "initial|follow_up|correction|verification",
  "intent_revision": "1",
  "intent_source": "agent_context_file",
  "session_initial_intent": "<first user request for this conversation>",
  "user_intent": "<current CLI-triggering user intent>",
  "session_goal": "<current summarized session goal>"
}

このファイルを更新するときは、次のローカルテンプレートを使用してください。実行前に、すべてのプレースホルダーを確認済みのコンテキストに置き換えてください。確認済みのモデルは、任意の環境変数から読み取らず、明示的に書き込んでください。モデルが不明な場合は、その項目を省略し、前述の部分取得ステータスを追加してください。

mkdir -p .ae
node -e 'const fs = require("fs"); const payload = {
  agent_client: "codex",
  agent_model: "<confirmed-current-model-id>",
  agent_session_id: process.env.CODEX_THREAD_ID || process.env.CODEX_SESSION_ID,
  agent_turn_id: "<current-turn-id>",
  parent_turn_id: "<previous-turn-id>",
  intent_relation: "initial",
  intent_revision: "1",
  intent_source: "agent_context_file",
  session_initial_intent: "<first user request for this conversation>",
  user_intent: "<current CLI-triggering user intent>",
  session_goal: "<current summarized session goal>"
}; Object.keys(payload).forEach((key) => payload[key] == null || payload[key] === "" ? delete payload[key] : undefined); fs.writeFileSync(".ae/cli-agent-context.json", JSON.stringify(payload, null, 2));'
ae-cli ...

フィールドの値が不明な場合は、推測せずにそのフィールドを省略してください。コンテキストファイル全体を省略してはいけません。会話中は agent_session_id を一定に保ち、ユーザーの訂正によって CLI の目的が変わった場合は intent_revision を増加または更新してください。長い会話の生テキストではなく、タスクを簡潔にまとめた user_intent を優先してください。プライバシー上の懸念がある場合は、ユーザーのテキストをそのまま送る代わりに、user_intent_hash と大まかな目的の要約を送信してください。

ゲートウェイコマンドの実行後に、意図のテレメトリが送信されたか尋ねられた場合は、コマンドの実行前に .ae/cli-agent-context.json が存在し、user_intent または user_intent_hash が含まれていたことを確認してください。ランタイムのみのコンテキストは部分的な代替手段にすぎず、この厳守事項を満たしません。

代替手段の優先順位は次のとおりです：.ta/cli-agent-context.json / .ae/cli-agent-context.json ＞ 書き込みができない隔離環境またはローカルデバッグでの --agent-context ＞ 従来の TA_CLI_* 変数 ＞ ランタイム環境の自動検出。

分析クエリのフィードバック

分析フィードバックのトリガー：分析データクエリが完了し、最終的なビジネス分析の回答を提示した後に限り、分析が期待に沿っていたかをユーザーの言語で一度だけ尋ねます。個々の CLI 呼び出し、中間ステップ、探索、メタデータの確認、アセットのガバナンスや書き込み、設定、ヘルプ、無関係な質問、クエリの送信、エクスポートの実行中、クエリの失敗後には尋ねないでください。明示的なフィードバックがない場合、送信や新たなフィードバックイベントの作成は行いません。完了した分析について明確なユーザーフィードバックがある場合は、型付き送信コントラクトを確認するために ae-cli analysis feedback submit --help を使用するか、analysis.feedback.submit を見つけて確認してください。評価対象の agent_session_id と既存の分析ターン ID を target_turn_ids として再利用し、現在のフィードバックターンは区別してください。ユーザーの元のフィードバックと、検証可能な簡潔なルートの要約だけを保持してください。分析の回答をアップロードしたり、沈黙、追加質問、新しい要件から評価を推測したりしないでください。分析ルートで使用されたモデルは、リンクされた元の CLI 呼び出しイベントから取得してください。フィードバックの収集が、その後のビジネス業務を妨げてはなりません。

オンデマンドの事前チェック（いずれか1つを選択）

基本方針：validate = パラメーターを修正する、dry-run = 実行準備が整っていることを確認する。 絶対ルール：同じ最終入力に対して、デフォルトで validate と dry-run の両方を実行しないでください。 dry-run にはパラメーター検証が含まれています。

状況	呼び出すもの	その後
単純／使い慣れた入力（一般的な read、少数のスカラー項目）	どちらも不要 — 事前チェックを省略	直接 run
複雑な qp／ネストされた payload／共有マップで、引き続き構造を調整中	--validate／capability validate のみ（修正中は繰り返し実行してもかまいません）	valid=true の後、直接 run — 下記に該当する場合を除き、dry-run は省略
リスク／output_mode／supports_cancel の確認が必要な場合、または high-risk-write の削除ゲート	--dry-run／capability dry-run のみ（最終入力に対して一度だけ）	その後、確認（削除）／run。同じ最終ペイロードに対して、先に validate を実行しないでください
まれな例外：validate を何度も繰り返した後、削除の確認も必要な場合	入力作成中に validate → 最終入力に対して dry-run を1回	その後、チャットで確認 → run --yes

validate → dry-run → run を通常の手順として扱わないでください。この手順の組み合わせが認められるのは、最終行に記載されたまれな例外の場合のみです。

スキルのリファレンス

デフォルトでは、新しい機能ごとに独立したスキルリファレンスを作成しないでください。search → inspect →（必要に応じて validate または dry-run）→ run を使用してください。カタログの description、risk、および inspect の input_schema がコントラクトとなります。

次のいずれかに該当する場合に限り、独立したリファレンスを作成または維持してください：L2 の厳格な基準、近接する機能との混同が起きやすい、high-risk-write の削除ワークフロー、または複数ステップのオーケストレーション。ドメインスキルでは、概要マトリクス（例：analysis_gateway_assets.md）に1行の要約をインラインで記載してもかまいません。capability-command-admission §10 を参照してください。

コマンド

# List company-level summaries, or the capabilities available in one project.
ae-cli capability list --domain <domain> [--project-id <id>]

# Search capability IDs and descriptions. All terms must match.
ae-cli capability search "<terms>" --domain <domain> [--project-id <id>]

# Read input_schema, risk, auth, output, and dry-run support.
ae-cli capability inspect <capability-id> [--project-id <id>]

# Optional — fix params only (gateway /validate). Curated: global --validate.
ae-cli capability validate <capability-id> --input '<json-object>'
ae-cli metadata data-table sql-write --project-id 1 ... --validate

# Optional — confirm ready to run (gateway /dry-run). Curated: global --dry-run.
ae-cli capability dry-run <capability-id> --input '<json-object>'
ae-cli metadata data-table sql-write --project-id 1 ... --dry-run

# Execute (after inspect; add at most one pre-check when needed).
ae-cli capability run <capability-id> --input '<json-object>'

--input では、次を指定できます：

• インライン JSON オブジェクト。
• JSON ファイルのパス。
• @<path>。
• 標準入力から JSON を読み込む -。

inspect、validate、dry-run、run では、機能の名前空間は <capability-id> から推定されます。ルーティングを上書きする場合に限り、--domain <domain> を使用してください。list、search、inspect では、会社の License／Feature の可視性を確認する場合は --project-id を省略してください。プロジェクトの所属情報、プロジェクトの Feature、ユーザー権限によるフィルタリングも含める場合は指定してください。

validate と dry-run の比較

	validate / --validate	dry-run / --dry-run
目的	複雑なペイロードの作成中に入力形式を確認します	実行前の確認（パラメーター＋リスク／出力／キャンセル）
業務データを変更しますか？	いいえ	いいえ
主な成功フィールド	valid、capability_id、normalized_input	dry_run、capability_id、risk、output_mode、supports_cancel、normalized_input
こちらを優先する場面	ネストされた payload / qp / 複数フィールドの JSON を調整するとき	最終入力。リスク／出力の仕様または削除確認ゲートが必要なとき
典型的な失敗の焦点	フィールドの欠落／無効、型の不一致、不正な qp 構造	同じパラメーターエラーに加え、実際の実行に向けた準備状況の通知
厳選コマンド	ゲートウェイ経由の厳選コマンドでグローバル --validate を使用	グローバル --dry-run

サーバーはどちらのエンドポイントでも、呼び出し元の認証を求める場合があります。どちらも機能の業務ハンドラーを実行しません。1回の呼び出しで --validate と --dry-run を併用しないでください。

複雑な入力： qp / ネストされたペイロードの組み立て中は、--validate のみを使用してください。valid=true になったら、run に進みます。リスク／出力のプレビューや削除確認ゲートが必要な場合は、validate ではなく dry-run を使用してください。両方は使用しません。

例（パラメーターのリスクのみ — dry-run の重ね掛けなし）：

ae-cli metadata data-table sql-write ... --validate   # iterate until valid
ae-cli metadata data-table sql-write ...              # execute ordinary write

例（削除ゲート — 最終入力で dry-run のみ）：

ae-cli capability dry-run analysis.folder.delete --input '...'
# stop, ask user, then:
ae-cli capability run analysis.folder.delete --input '...' --yes

リスクレベル（lark-cli に準拠）

risk	意味	run の前にチャットで確認が必要ですか？	--yes を指定しない場合、CLI で [y/N] が表示されますか？
read	クエリ／一覧／調査	いいえ	いいえ
write	作成、更新、共有などの通常の書き込み	いいえ	いいえ
high-risk-write	リソースの削除または除去	はい	はい

create、update、delete などの従来の値は、この3段階モデルに正規化されます（delete → high-risk-write、create / update → write）。

安全性

• list、search、inspect、validate、dry-run は、業務上の変更を実行しません。
• ゲートウェイ経由の厳選コマンド：--validate → /validate、--dry-run → /dry-run。併用しないでください。
• 特に指定がない限り、同じ最終入力に validate と dry-run を重ねて適用しないでください（効率化のため）。
• --yes を指定しない場合、capability run は実行前にメタデータを確認します。
• capability run ... --yes の前にチャットで確認が必要なのは、high-risk-write のみです。
• read と通常の write は inspect の後に実行できます。オンデマンドの表に記載されている場合に限り、validate または dry-run を追加してください。
• 削除の実行で --yes を使用するのは、ユーザーがチャットで実行を明示的に許可した後にしてください。
• capability run / 厳選コマンドでグローバル --dry-run を指定すると、execute の代わりにゲートウェイの dry-run エンドポイントを呼び出します。
• capability run / 厳選コマンドでグローバル --validate を指定すると、execute の代わりにゲートウェイの validate エンドポイントを呼び出します。

高リスク確認ワークフロー（エージェント）

inspect に risk=high-risk-write が表示された場合にのみ適用されます。

ユーザーの意図（たとえば「このスペースを削除して」）は、実行の許可ではありません。ユーザーが希望する操作を述べたという理由だけで --yes を渡してはいけません。

1. capability inspect を実行します。複雑な削除入力の場合に限り、作成中に validate を繰り返し実行してもかまいません。最終ペイロードには dry-run を一度だけ使用します（同じ最終 JSON に対する冗長な validate は省略します。dry-run でパラメーターも検証されます）。
2. **同じターン内で停止します。**dry-run と同じターン内に capability run を呼び出してはいけません。
3. チャットで、capability ID、project_id、主要な入力フィールド、risk=high-risk-write を要約します。
4. 実行の確認をユーザーに求めます。そのツールが利用可能な場合は AskUserQuestion を優先します。それ以外の場合はプレーンテキストで尋ね、ユーザーの次のメッセージを待ちます。
5. ユーザーが明示的に許可（たとえば confirm、execute、yes）した後に限り、dry-run と同じ入力で capability run ... --yes を実行します。

risk=write の場合、チャットでの確認は不要です。inspect の後は直接 run を優先します。ペイロードが複雑で形式を修正している場合は --validate のみを使用します。リスクや出力のプレビューが必要な場合に限り --dry-run のみを使用し、習慣的に validate の後に dry-run を実行してはいけません。

最初の削除試行で --yes を渡してはいけません。CLI のターミナルに表示される [y/N] プロンプトは Agent Bash では機能しません。high-risk-write では、チャットでの確認が実際の実行許可です。

出力

• error.type: config を伴う CREDENTIAL_STORE_UNREADABLE は、ローカルでの認証情報の読み取り／復号エラーであり、サーバーによる認証拒否ではありません。認証情報ファイルを保持し、マシン識別子にアクセスできる元の OS ユーザー／ランタイムで再試行してください。自動的にログインしたり、代替トークンをインポートしたり、ログアウトしたりしてはいけません。そのランタイムを利用できない場合は、ローカルエラーを報告してください。
• list は { domain, count, capabilities } を返します。
• search は { domain, query, count, capabilities } を返します。
• inspect、validate、dry-run、run は、標準の ae-cli エンベロープでゲートウェイデータを返します。

例

ae-cli capability search "dashboard list" --domain analysis
ae-cli capability inspect analysis.dashboard.list
ae-cli capability validate metadata.data_table.sql_write --input input.json
ae-cli capability dry-run analysis.folder.delete --input '{"project_id":1,"folder_ids":[1001]}'
ae-cli capability run analysis.dashboard.list --input input.json