agent-skill-orchestrator

agent-skill-orchestrator

目的

ユーザーの要件を分析し、利用可能な最適なリソースを用いて戦略的な実行計画を作成する、インテリジェントなタスク計画・リソース調整エンジンです。このスキルは、自動検出、信頼度スコアリングによるインテリジェントなマッチング、複数の選択肢とフォールバック戦略を含む包括的な計画の生成を行います。

このオーケストレーターは計画アシスタントとして動作し、アプローチを提案しますが、実行前には必ずユーザーに明示的な承認を求めます。検出基盤の上位に位置するインテリジェンス層として、「何があるか」を「どう使うべきか」へと変換します。

使用するタイミング

次の場合にこのスキルを呼び出します。

• 複数の手順やリソースを必要とする複雑なタスクがある場合
• 問題を解決する最善の方法を知りたい場合
• 複数のプラグイン、エージェント、スキル、または MCP 間の連携が必要な場合
• タスクでリソースを最適に活用したい場合
• どのツールやアプローチを使うべきか分からない場合
• 実装前に戦略的な計画が必要な場合
• 複数の解決策を検討したい場合

プラットフォームのサポート

すべての AI CLI プラットフォームで同じように動作します。

• Claude Code (claude)
• GitHub Copilot CLI (gh copilot)
• Gemini CLI (gemini)
• OpenCode (opencode)
• OpenAI Codex (codex)

進捗状況の追跡

各オーケストレーションフェーズの前に進捗状況を表示します。

[██░░░░░░░░░░░░░░░░░░] 15% — Step 0: Discovering Available Resources
[████░░░░░░░░░░░░░░░░] 25% — Step 1: Analyzing User Request
[████████░░░░░░░░░░░░] 45% — Step 2: Intelligent Matching & Scoring
[████████████░░░░░░░░] 65% — Step 3: Generating Execution Plan
[██████████████████░░] 85% — Step 4: Presenting Plan for Approval
[████████████████████] 100% — Step 5: Plan Approved / Execution Ready

ワークフロー

ステップ -1：プロンプトの品質チェック（分析前）

目的： 計画を立てる前に、ユーザーの依頼が明確で適切に構成されていることを確認します。

このステップが重要な理由：

• 曖昧なプロンプト → 不適切なリソースマッチング → 品質の低い計画
• 最適化されたプロンプト → 要件の明確化 → 信頼度の高い計画
• 計画の反復と「計画の改善」サイクルを削減

プロンプトの品質チェック： 計画を立てる前に、正確なリソースマッチングができるだけの具体性がユーザーの依頼にあるかを評価します。依頼が20語未満である、明確な動作動詞や目標を含まない、または文脈のない曖昧な指示（「これ」「それ」など）のみを使っている場合は、まず prompt-engineer を呼び出して内容を改善します。依頼を十分に改善することで、信頼度スコアが20～30％向上し、計画の反復を減らせます。依頼がすでに明確な場合は、そのまま進めます。

計画への影響：

• ✅ 信頼度スコアが20～30％向上
• ✅ より正確なリソースマッチング
• ✅ 成功基準の定義が改善
• ✅ 計画の実行時の曖昧さを低減

---

ステップ 0：利用可能なリソースを検出

目的： インストールされているすべてのリソースの最新の一覧を取得します。

重要な依存関係： このスキルは、最初に agent-skill-discovery を必ず呼び出す必要があります。

アクション：

検出スキルを呼び出して、リソースの完全なカタログを取得します。

# Call agent-skill-discovery skill
resources = invokeSkill("agent-skill-discovery")

期待される出力：

{
  "platform": "Claude Code",
  "plugins": [
    {
      "name": "feature-dev",
      "agents": [
        {
          "name": "code-explorer",
          "description": "Analyzes existing codebase",
          "tools": ["Glob", "Grep", "Read", "Bash"]
        }
      ]
    }
  ],
  "skills": [
    {
      "name": "skill-creator",
      "description": "Creates new skills",
      "triggers": ["create a skill", "new skill"],
      "category": "development"
    }
  ],
  "mcpServers": [
    {
      "name": "claude_ai_Notion",
      "type": "stdio",
      "tools": ["notion-search", "notion-create-pages"]
    }
  ]
}

このステップが重要な理由：

• リソースの利用可否を最新かつ正確に把握できます
• すべてのプラットフォームで動作します（検出機能がプラットフォームを判定します）
• インテリジェントなマッチングに必要な完全なコンテキストを提供します
• 利用できないリソースを推奨することを防ぎます

ステップ 1：ユーザーの依頼を分析

目的： ユーザーのタスクの説明から要件を抽出します。

アクション：

依頼を解析して、以下を抽出します。

• タスクの種類 — 開発、コンテンツ、統合、分析、ドキュメント作成、または計画。動詞から推測します。build/create/implement → 開発、transcribe/summarize/convert → コンテンツ、connect/sync/automate → 統合、review/debug/diagnose → 分析、document/write → ドキュメント作成、design/plan/architect → 計画。
• 必要な機能 — コード生成、ウェブアクセス、ファイル処理、外部連携（サービス名を検出：Notion、Jira、GitHub、Slack、Confluence、browser）。
• キーワード — リソースの説明やトリガーとのマッチングに使う名詞や技術名を抽出します。
• 複雑さ — 単純（ツール1つ、手順1つ）、中程度（2～3手順、一部の連携あり）、複雑（複数フェーズ、手順間の依存関係あり）。

ステップ 2：インテリジェントなマッチングとスコアリング

目的： 発見した各リソースをユーザー要件に照らして評価します。

解析した要件に基づき、発見した各リソースを次の5つの観点で評価します。

観点	重み	評価方法
トリガーフレーズの一致	30%	リソースのトリガーフレーズに、ユーザーのキーワードと一致するものがあるか？
意味的な類似性	25%	リソースの説明がユーザーの目標や分野に合致しているか？
ツールの利用可能性	20%	リソースのツールが必要な機能（ウェブ、ファイル I/O、コード、連携）をカバーしているか？
カテゴリーの関連性	15%	リソースのカテゴリーが検出されたタスクの種類に合っているか？
MCP 連携ボーナス	10%	これは MCP ツールであり、タスクで外部サービスとの連携が必要か？

合計スコアは 0～100 です。40 未満のリソースは除外します。信頼度別に分類します。高（≥80）、中（60～79）、低（40～59）。

ステップ 3：実行計画の生成

目的： 代替案を含む戦略的な実行計画を作成します。

主要な戦略を作成するには、信頼度の高いリソースを論理的な実行順序に並べます。

1. 分析／調査リソースを最初に配置します（タスクで既存の状態を把握する必要がある場合）
2. 実装リソースを中盤に配置します（作成、構築、変換）
3. 検証／レビューリソースを最後に配置します（確認、監査、確証）

代替戦略を作成するには、主要な計画に含まれていない信頼度が中程度のリソースを使用します。代替案は、簡略化した2ステップのアプローチで十分です。

前提条件を抽出します： 計画内の各 MCP リソースについて、「MCP サーバー X を設定する必要があります」を追加します。各プラグインエージェントについて、「プラグイン X をインストールする必要があります」を追加します。

**成功基準を定義します。**タスクの種類に基づいて、次のように定めます。

• 開発 → コードがエラーなくコンパイルされ、テストに合格し、プロジェクトの規約に準拠している
• コンテンツ → 出力形式が要件に一致し、コンテンツが正確かつ完全である
• 連携 → 外部サービスが正常に応答し、データが正しく同期される

ステップ 4：承認用の計画を提示

目的： 包括的な計画を、見やすい Markdown 形式でユーザーに提示します。

出力構造：

## 📊 Discovery Analysis

**Platform:** {detected_platform}
**Task Type:** {requirements.taskType}
**Complexity:** {requirements.complexity}
**External Integrations:** {requirements.externalIntegrations.join(', ') || 'None'}

---

## 🔍 Resources Found ({total_count})

### High Confidence (80-100%)
- **{resource_name}** [{score}%] - {description}
  - **Why selected:** {reasoning}

### Medium Confidence (60-79%)
- **{resource_name}** [{score}%] - {description}

---

## ✅ Recommended Execution Plan

### Option 1: Primary Strategy (Recommended)

**Step {n}:** Use **{resource_name}** to {action}
- **Input:** {input_description}
- **Output:** {expected_output}
- **Tool:** {platform_tool_name}
- **Rationale:** {why_this_resource}

*(Repeat for each step)*

**Expected Outcome:** {final_result_description}
**Estimated Time:** {time_estimate}
**Risk Level:** {low|medium|high}

---

### Option 2: Alternative Strategy

**Step {n}:** Use **{alt_resource_name}** to {action}
- **Input:** {input_description}
- **Output:** {expected_output}
- **Rationale:** {why_this_alternative}

*(Simpler or different approach)*

---

## ⚠️ Prerequisites

Before executing this plan, ensure:

- [ ] {prerequisite_1}
- [ ] {prerequisite_2}
- [ ] {prerequisite_3}

---

## 🎯 Success Criteria

This plan will be successful when:

- [ ] {criterion_1}
- [ ] {criterion_2}
- [ ] {criterion_3}

---

## 💡 Notes

- **Parallel Execution:** Steps {x} and {y} can run in parallel
- **Fallback:** If Step {n} fails, try {alternative}
- **Dependencies:** Step {n+1} requires output from Step {n}

---

**⏸️ Awaiting your approval to proceed...**

ステップ 5：承認を求める

目的： 実行前に、ユーザーから明示的な確認を得ます。

AskUserQuestion を使用します：

AskUserQuestion({
  question: "Which execution plan would you like to proceed with?",
  header: "Plan Approval",
  options: [
    {
      label: "Execute Option 1 (Recommended)",
      description: "Primary strategy with highest confidence resources"
    },
    {
      label: "Execute Option 2 (Alternative)",
      description: "Alternative approach with different resource mix"
    },
    {
      label: "Refine plan",
      description: "Modify requirements or resource selection"
    },
    {
      label: "Cancel",
      description: "Do not execute, return to planning"
    }
  ]
});

応答への対応：

• オプション 1／2 を実行： 選択された計画を進めます（ステップ 6）
• 調整： 追加の質問をし、計画を再生成します
• キャンセル： 実行せずに正常に終了します

ステップ 6：計画を実行（任意）

目的： 承認された計画を、ステップごとに実行します。

実行戦略：

async function executePlan(approvedPlan) {
  const results = [];

  for (const step of approvedPlan) {
    console.log(`\n🔄 Executing Step ${step.number}...`);
    console.log(`   Resource: ${step.resource.name}`);
    console.log(`   Action: ${step.action}`);

    try {
      // Invoke the resource (agent, skill, or MCP tool)
      const result = await invokeResource(step.resource, step.input);

      results.push({
        step: step.number,
        status: 'success',
        output: result
      });

      console.log(`✅ Step ${step.number} completed`);

    } catch (error) {
      console.error(`❌ Step ${step.number} failed: ${error.message}`);

      // Check for fallback
      if (step.fallback) {
        console.log(`🔄 Trying fallback: ${step.fallback.resource.name}`);
        const fallbackResult = await invokeResource(step.fallback.resource, step.input);
        results.push({
          step: step.number,
          status: 'fallback',
          output: fallbackResult
        });
      } else {
        throw error; // No fallback, abort
      }
    }
  }

  return results;
}

async function invokeResource(resource, input) {
  if (resource.type === 'skill') {
    return await invokeSkill(resource.name, input);
  } else if (resource.type === 'agent') {
    return await invokeAgent(resource.name, input);
  } else if (resource.type === 'mcp') {
    return await invokeMCPTool(resource.name, input);
  }
}

進捗報告：

実行中に進捗を表示します。

## 🚀 Execution Progress

✅ Step 1: Completed (feature-dev:code-explorer)
🔄 Step 2: In progress (feature-dev:code-architect)
⏸️ Step 3: Pending (code-review:code-review)

**Current Output:**
{step_output_preview}

重要なルール

絶対にしてはいけないこと：

• ❌ 最初に agent-skill-discovery を呼び出す手順を省略する（ステップ 0 は必須）
• ❌ ユーザーから明示的な承認を得ずに計画を実行する
• ❌ 開示せずにスコアが 40% 未満のリソースを推奨する
• ❌ プラットフォーム固有のロジックをハードコードする（検出時に得たプラットフォーム情報を使用する）
• ❌ 発見結果を確認せずにリソースが利用可能だと仮定する
• ❌ 発見結果が空でも何も伝えずに処理を続ける（ユーザーに知らせる）
• ❌ 異なるプラットフォームのリソースを混在させる（同じプラットフォームに統一する）
• ❌ 計画の生成でユーザーの制約や希望を無視する

必ず行うこと：

• ✅ 計画の作成前にプロンプトの品質を評価する（ステップ -1）— v1.1.0 の新機能
• ✅ 最適な結果を得るため、品質スコアが 50% 未満の場合は prompt-engineer を呼び出す
• ✅ 呼び出しごとに、最新の発見から開始する（ステップ 0）
• ✅ すべての推奨項目について、根拠とともに信頼度スコアを示す
• ✅ 可能であれば、複数の選択肢（オプション 1、オプション 2）を提示する
• ✅ 実行前に前提条件を明確に列挙する
• ✅ 測定可能な成功基準を定義する
• ✅ 実行前に明示的な承認を求める（ステップ 5）
• ✅ 発見結果に含まれる、プラットフォームに適したツール名を使用する
• ✅ リソースが見つからない場合は適切に対処する（代替案を提案するか、中止する）
• ✅ 実行中に進捗を報告する（ステップ 6 に進む場合）
• ✅ 各リソースを選択した理由を説明する

オーケストレーションの原則：

• 発見を最優先： 最新のリソース一覧を確認せずに計画を立てないでください
• 信頼度の透明性： スコアと判断理由を必ず示してください
• 複数の選択肢： 可能な場合は代替案を提示してください
• 承認が必要： 同意なしに自律的に実行しないでください
• 柔軟な縮退： 主な計画が失敗した場合は、代替案を試してください
• プラットフォーム非依存： 5つのすべてのプラットフォームで同じように動作します

使用例

例 1：機能開発

ユーザーのリクエスト：

"Plan how to build a REST API with authentication"

オーケストレーターの出力：

## 📊 Discovery Analysis

**Platform:** Claude Code
**Task Type:** development
**Complexity:** moderate
**External Integrations:** None

---

## 🔍 Resources Found (8)

### High Confidence (80-100%)
- **feature-dev:code-architect** [92%] - Designs feature architectures
  - **Why selected:** Best match for API design patterns
- **feature-dev:code-explorer** [88%] - Analyzes existing codebase
  - **Why selected:** Understands existing auth patterns
- **feature-dev:code-reviewer** [85%] - Reviews code for security
  - **Why selected:** Critical for auth security validation

### Medium Confidence (60-79%)
- **skill-creator** [65%] - Scaffolds code structures
  - Can generate boilerplate auth code

---

## ✅ Recommended Execution Plan

### Option 1: Primary Strategy (Recommended)

**Step 1:** Use **feature-dev:code-explorer** to analyze existing authentication patterns
- **Input:** Codebase context
- **Output:** Analysis of current auth implementation
- **Tool:** Read, Grep, Glob
- **Rationale:** Understand existing patterns before designing (88% match)

**Step 2:** Use **feature-dev:code-architect** to design REST API structure with auth
- **Input:** Analysis results from Step 1
- **Output:** API architecture and auth flow design
- **Tool:** Read, Write, Glob
- **Rationale:** Specialized in API design patterns (92% match)

**Step 3:** Use **skill-creator** to scaffold authentication boilerplate
- **Input:** Architecture design from Step 2
- **Output:** Auth middleware code structure
- **Tool:** Write
- **Rationale:** Generates standard auth patterns (65% match)

**Step 4:** Use **feature-dev:code-reviewer** to validate security
- **Input:** Generated auth code from Step 3
- **Output:** Security audit report
- **Tool:** Read, Grep
- **Rationale:** Critical for auth security review (85% match)

**Expected Outcome:** Secure REST API with JWT authentication, following project conventions
**Estimated Time:** ~45 minutes
**Risk Level:** Low (high confidence resources, well-defined approach)

---

### Option 2: Alternative Strategy

**Step 1:** Use **skill-creator** to scaffold complete API + auth structure
- **Input:** User requirements
- **Output:** Boilerplate API with basic auth
- **Rationale:** Faster but less customized approach

**Step 2:** Use **feature-dev:code-reviewer** to validate implementation
- **Input:** Generated code
- **Output:** Quality and security review
- **Rationale:** Ensure boilerplate meets standards

*(Simpler 2-step approach for rapid prototyping)*

---

## ⚠️ Prerequisites

- [ ] Plugin "feature-dev" must be installed
- [ ] Plugin "code-review" must be installed (for Option 1 Step 4)
- [ ] Skill "skill-creator" must be installed
- [ ] Codebase must be accessible (for pattern analysis)

---

## 🎯 Success Criteria

- [ ] REST API endpoints defined and functional
- [ ] JWT authentication implemented correctly
- [ ] Security review passes with no critical issues
- [ ] Code follows project conventions
- [ ] Tests pass for auth flows

---

## 💡 Notes

- **Parallel Execution:** Steps 3 and 4 can overlap (scaffold while reviewing)
- **Fallback:** If feature-dev:code-architect unavailable, use manual design
- **Dependencies:** Step 2 requires output from Step 1 (pattern analysis)

---

**⏸️ Awaiting your approval to proceed...**

例 2：コンテンツ処理と統合

ユーザーのリクエスト：

"Analyze this meeting recording and create Jira tickets"

発見の分析：

## 📊 Discovery Analysis

**Platform:** GitHub Copilot CLI
**Task Type:** content + integration
**Complexity:** moderate
**External Integrations:** Jira

---

(計画の出力は例 1 と同じ構成です。リソースのスコアリング、主な戦略と代替戦略、前提条件、成功基準、承認プロンプトが含まれます。)

例 3：ウェブ調査とドキュメント作成

ユーザーのリクエスト：

"Research competitor pricing and create a Notion page"

発見の分析：

## 📊 Discovery Analysis

**Platform:** Gemini CLI
**Task Type:** integration + documentation
**Complexity:** moderate
**External Integrations:** Notion, Web

---

(計画の出力は例 1 と同じ構成です。リソースのスコアリング、主な戦略と代替戦略、前提条件、成功基準、承認プロンプトが含まれます。)

例 4：曖昧なプロンプト → 最適化された計画（NEW v1.1.0）

ユーザーのリクエスト（曖昧）：

"help me with API stuff"

発見の分析：

## 📊 Discovery Analysis

**Platform:** Claude Code
**Task Type:** development
**Complexity:** moderate
**External Integrations:** None

---

(計画の出力は例 1 と同じ構成です。リソースのスコアリング、主な戦略と代替戦略、前提条件、成功基準、承認プロンプトが含まれます。)