agent-orchestrator

Agent Orchestrator

概要

エコシステム内のすべてのエージェントをオーケストレーションするメタスキルです。スキルを自動スキャンし、能力に基づいてマッチングし、複数のスキルにまたがるワークフローを調整して、レジストリを管理します。

このスキルを使用する場合

• ユーザーがローカルのスキル一覧や、複数の能力を必要とするタスクの調整計画を求めている場合。
• 指示を実行したりエージェントを起動したりせずに、候補を明示的に比較する必要がある場合。

このスキルを使用しない場合

• タスクがエージェントオーケストレーターと無関係な場合
• よりシンプルで具体的なツールでリクエストに対応できる場合
• ユーザーが専門知識を必要としない汎用的な支援を求めている場合

仕組み

スキルのエコシステム全体における、意思決定と調整の中核レイヤーとして機能するメタスキルです。自動スキャンを行い、関連するエージェントを特定して、複雑なタスクのために複数のスキルをオーケストレーションします。

原則：要求に応じた検出とレビュー可能な計画

• 要求された範囲のみをスキャンします。このスキルがすべてのリクエストを横取りしてはなりません。
• 新しいスキルは、roots と深度制限の範囲内で、次回の明示的なスキャン時に検出されます。
• 削除されたスキルはレジストリから自動的に除外されます。
• スキャンは明示的に実行してください。マッチャーがスキャンを自動的に開始することはありません。

---

要求に応じた検出のワークフロー

このツールが求められた場合にのみ、以下の手順を実行してください。スコアはローカルなヒューリスティックであり、安全性、互換性、認可を証明するものではありません。計画はスキルを実行しません。委任、メッセージ送信、公開にはユーザーの認可が必要です。 スクリプトは自身のインストール先を基準にファイルを特定しますが、以下のコマンドは agent-orchestrator の親ディレクトリが現在のディレクトリであることを前提としています。別の場所から実行する場合は、スクリプトの絶対パスを使用してください。

依存関係

Python 3.10+ を使用し、レビュー済みの仮想環境に scripts/requirements.txt をインストールしてください。パーサーには PyYAML が必要です。以下のコマンドはメタデータの一覧を作成して計画を生成するだけで、スキルは実行しません。

ステップ 1：自動検出（スキャン）

python agent-orchestrator/scripts/scan_registry.py

SHA-256 ハッシュのキャッシュを使って、変更されたファイルを再処理します。所要時間はツリーのサイズによって異なり、100ms 以内で完了する保証はありません。 検出されたすべてのスキルの概要を JSON で返します。

ステップ 2：スキルのマッチング

python agent-orchestrator/scripts/match_skills.py "<solicitacao do usuario>"

関連度順に並べたスキルを JSON で返します。結果は次のように解釈してください。

結果	アクション
matched: 0	ヒューリスティックのしきい値を超える候補はありません。関連するスキルが存在しないことを示すものではありません。
matched: 1	候補は1つです。選択する前に、対象範囲、ファイル、依存関係、認可を確認してください。
matched: 2+	候補は複数です。タスクで調整が求められている場合に限り、計画を提案してください。

ステップ 3：オーケストレーション（Matched >= 2 の場合）

python agent-orchestrator/scripts/orchestrate.py --skills skill1,skill2 --query "<solicitacao>"

実行計画を返します。計画にはパターン、ステップの順序、スキル間のデータフローが含まれます。

クイックスタート（ショートカット）

シンプルなクエリでは、ステップ 1 と 2 を続けて実行できます。

python agent-orchestrator/scripts/scan_registry.py && python agent-orchestrator/scripts/match_skills.py "<solicitacao>"

---

スキルレジストリ

実行前に、AGENT_ORCHESTRATOR_DATA_DIR を、スキルのインストール先の外部にある、認可済みのプライベートディレクトリの絶対パスに設定してください。レジストリ、ハッシュ、プロジェクトの割り当て情報はこのディレクトリに保存されます。共有ディレクトリやシンボリックリンクを含むツリーは使用しないでください。再利用する前に内容を確認してください。

export AGENT_ORCHESTRATOR_DATA_DIR="<diretorio-absoluto-autorizado>"

マッチャーを実行する前に、スキャンを明示的に実行してください。読み取りエラー、無効な JSON、レジストリの欠落は、スキルが存在しないことを意味しません。名前が同じでも、異なるパスはインベントリにそれぞれ残ります。名前が曖昧な場合は選択を中止してください。スキャナーの深度制限により、インベントリが不完全になることがあります。

検索場所

スキャナーは以下の場所で SKILL.md を検索します。

1. .claude/skills/*/（Claude Code に登録されたスキル）
2. */（トップレベルにあるスタンドアロンのスキル）
3. 深さ 3 までのサブフォルダー（一部のみをカバー）

スキルごとのメタデータ

レジストリの各エントリーには以下が含まれます。

フィールド	説明
name	スキル名（YAML フロントマターから取得）
description	説明全文（トリガーを含む）
location	ディレクトリの絶対パス
skill_md	SKILL.md の絶対パス
registered	.claude/skills/ にあるかどうか（true/false）。ホストによって読み込まれた証拠ではありません
capabilities	能力タグ（自動抽出＋明示指定）
triggers	description から抽出された有効化キーワード
language	主な言語（python/nodejs/bash/none）
status	active / incomplete / missing

レジストリコマンド

## Scan Rapido (Usa Cache De Hashes)

python agent-orchestrator/scripts/scan_registry.py

## Tabela De Status Detalhada

python agent-orchestrator/scripts/scan_registry.py --status

## Re-Scan Completo (Ignora Cache)

python agent-orchestrator/scripts/scan_registry.py --force

---

マッチングアルゴリズム

各リクエストに対し、マッチャーは以下を使ってスキルをスコアリングします。

条件	点数	例
クエリ内のスキル名	+15	"use web-scraper" -> web-scraper
完全一致するトリガーキーワード	+10	"scrape" -> web-scraper
能力カテゴリ	+5	data-extraction -> web-scraper
単語の重複	+1	クエリ内の単語が description に含まれる
プロジェクトブースト	+20	アクティブなプロジェクトに割り当てられたスキル

最小しきい値：5 点です。これを下回るスキルは無視されます。

プロジェクトとのマッチング

python agent-orchestrator/scripts/match_skills.py --project meu-projeto "query aqui"

プロジェクトに割り当てられたスキルには、自動的に +20 のブーストが付与されます。

---

オーケストレーションパターン

複数のスキルが関連する場合、オーケストレーターはパターンを分類します。

1. シーケンシャルパイプライン

あるスキルの出力が次のスキルへの入力となる連鎖を形成します。

用途： 「生成側」（data-extraction、government-data）と「利用側」（messaging、social-media）のスキルを組み合わせる場合。

例： web-scraper が価格を収集 -> whatsapp-cloud-api がアラートを送信

user_query -> web-scraper -> whatsapp-cloud-api -> result

2. 並列実行

スキルがリクエストの異なる側面について、独立して作業します。

用途： すべてのスキルの役割が同じ（すべて生成側、またはすべて利用側）場合。

例： instagram が投稿を公開 + whatsapp が通知を送信（どちらも同じコンテンツを受け取る）

user_query -> [instagram, whatsapp-cloud-api] -> aggregated_result

3. 主担当 + サポート

1 つの主要なスキルが処理を主導し、他のスキルが補助データを提供します。

用途： 1 つのスキルのスコアが他より大幅に高い（2 倍以上）場合。

例： whatsapp-cloud-api がメッセージを送信（主担当）+ web-scraper がデータを提供（サポート）

user_query -> whatsapp-cloud-api (primary) + web-scraper (support) -> result

詳細は orchestration-patterns.md を参照してください。

---

プロジェクト管理

プロジェクトにスキルを割り当てると、関連性のブーストと永続的なコンテキストを利用できます。

プロジェクトファイル

$AGENT_ORCHESTRATOR_DATA_DIR/projects.json

操作

プロジェクトを作成： projects.json の projects 配列にエントリーを追加します。

{"projects": [{
  "name": "nome-do-projeto",
  "created_at": "2026-02-25T12:00:00",
  "skills": ["web-scraper", "whatsapp-cloud-api"],
  "description": "Descricao do projeto"
}]}

プロジェクトにスキルを追加： プロジェクトの skills 配列を更新します。

プロジェクトからスキルを削除： skills 配列から削除します。

プロジェクトのスキルを確認： projects.json を読み込み、割り当てられたスキルを一覧表示します。

---

新しいスキルの追加

エコシステムに新しいスキルを追加するには、以下の手順を行います。

1. skills root: の配下の任意の場所にフォルダーを作成します
2. YAML フロントマターを含む SKILL.md を作成します。

---
name: minha-nova-skill
description: "Descricao com keywords de ativacao..."
---

## Documentacao Da Skill

3. 部分的なインベントリを更新するため、明示的にスキャンを実行します。

オプションとして、Claude Code のネイティブな検出を有効にするには： 4. SKILL.md を .claude/skills/<nome>/SKILL.md にコピーします

明示的な能力タグ（任意）

より正確なマッチングのため、フロントマターに追加します。

capabilities: [data-extraction, web-automation]

---

すべてのスキルのステータスを確認

python agent-orchestrator/scripts/scan_registry.py --status

ステータスの解釈

ステータス	意味
active	name と description が存在します。レビュー、安全性、運用上の完全性を意味するものではありません
incomplete	SKILL.md は存在しますが、name または description が不足しています
missing	ディレクトリは存在しますが、SKILL.md がありません

---

エコシステムの現在のスキル

スキル	機能	ステータス
web-scraper	data-extraction, web-automation	active
junta-leiloeiros	government-data, data-extraction	active
whatsapp-cloud-api	messaging, api-integration	active
instagram	social-media, api-integration	partial

エコシステムの元の状態を示す参考表です。スキャナーは現在のインベントリを出力しますが、この表は変更しません。名前が AAS へのインストールを保証するものではありません。

ベストプラクティス

• プロジェクトと要件について、明確で具体的なコンテキストを提示してください
• 本番コードに適用する前に、提案をすべて確認してください
• 包括的な分析を行うには、他の補完的なスキルと組み合わせてください

よくある落とし穴

• このスキルを、専門領域外のタスクに使用する
• 特定のコンテキストを理解せずに推奨事項を適用する
• 正確な分析に必要なプロジェクトのコンテキストを十分に提示しない

関連スキル

• multi-advisor - 分析を強化する補完的なスキル
• task-intelligence - 分析を強化する補完的なスキル

制限事項

• タスクが上記の説明された範囲に明確に該当する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。