AgentSkillsCN

claude-agent-sdk

专注于使用 Claude Agent SDK(@anthropic-ai/claude-agent-sdk)以及直接 Anthropic SDK(@anthropic-ai/sdk)来实现代理集成的技能。 支持 query() API、Hooks 系统、权限控制、Electron 集成、流式处理,以及 Direct SDK 模式。 锚点: • Claude Agent SDK 官方文档 / 适用场景:SDK API、Hooks、权限 / 目的:遵循官方规范进行开发 • Anthropic SDK(@anthropic-ai/sdk)/ 适用场景:直接调用 SDK / 目的:实现简洁的主进程集成 • Electron IPC 最佳实践 / 适用场景:主进程与渲染进程间通信 / 目的:确保安全的进程间通信 • TypeScript 手册 / 适用场景:类型定义、泛型 / 目的:实现类型安全的 SDK 集成 触发条件: 当您使用 Claude Agent SDK 实现代理功能、进行 query() API 的流式处理、部署 Hooks 系统、集成 Electron,或设计权限控制、MCP 集成、Direct SDK 集成时,可使用此技能。 claude-agent-sdk、query API、PreToolUse、PostToolUse、PermissionRequest、Electron IPC、MCP、流式处理、权限控制、@anthropic-ai/sdk、Direct SDK

SKILL.md
--- frontmatter
name: claude-agent-sdk
description: |
  Claude Agent SDK(@anthropic-ai/claude-agent-sdk)および直接Anthropic SDK(@anthropic-ai/sdk)を使用したエージェント統合の実装を専門とするスキル。
  query() API、Hooksシステム、Permission Control、Electron統合、ストリーミング処理、Direct SDKパターンを支援します。

  Anchors:
  • Claude Agent SDK Official Docs / 適用: SDK API、Hooks、Permissions / 目的: 公式パターンに準拠した実装
  • Anthropic SDK (@anthropic-ai/sdk) / 適用: Direct SDK呼び出し / 目的: シンプルなMain Process統合
  • Electron IPC Best Practices / 適用: Main-Renderer間通信 / 目的: セキュアなプロセス間通信
  • TypeScript Handbook / 適用: 型定義、ジェネリクス / 目的: 型安全なSDK統合

  Trigger:
  Claude Agent SDKを使用したエージェント機能実装、query() APIストリーミング処理、Hooksシステム実装、Electron統合、Permission Control設計、MCP統合、Direct SDK統合を行う場合に使用。
  claude-agent-sdk, query API, PreToolUse, PostToolUse, PermissionRequest, Electron IPC, MCP, ストリーミング, 権限制御, @anthropic-ai/sdk, Direct SDK

allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep

Claude Agent SDK

概要

Claude Agent SDK(@anthropic-ai/claude-agent-sdk)を使用したエージェント統合の実装を専門とするスキル。query() API、Hooksシステム、Permission Control、Electron統合、ストリーミング処理を支援します。

対象言語: TypeScript のみ

最新情報取得

SDK情報は頻繁に更新されるため、実装前に最新情報を確認してください。

bash
# 最新情報を取得
node .claude/skills/claude-agent-sdk/scripts/fetch-latest-info.mjs

# npmパッケージ情報のみ
node .claude/skills/claude-agent-sdk/scripts/fetch-latest-info.mjs --category npm

詳細なURL一覧は references/official-urls.md を参照してください。

ワークフロー

Phase 1: 要件の明確化と設計方針の決定

目的: エージェント統合の要件を理解し、適切なパターンを選定する

アクション:

  1. 使用するツール(Read, Edit, Bash等)を特定
  2. Permission Control戦略を決定
  3. references/query-api.md で基礎パターンを確認
  4. references/permission-control.md で権限設計を確認

Task: agents/analyze-agent-requirements.md を参照

Phase 2: SDK統合の実装

目的: query() APIとHooksを実装し、エージェント機能を構築する

アクション:

  1. assets/agent-handler-template.ts を参照してIPCハンドラを実装
  2. references/hooks-system.md でHooksパターンを確認
  3. references/electron-ipc.md でElectron統合パターンを確認
  4. ストリーミング処理とエラーハンドリングを実装

Task: agents/implement-agent-integration.md を参照

Phase 3: 検証と記録

目的: 成果物の品質を確認し、ナレッジを記録する

アクション:

  1. scripts/validate-agent-setup.mjs で設定の検証
  2. Permission Controlのテスト
  3. 実装パターンのドキュメント化

Task: agents/validate-agent-setup.md を参照

Task仕様ナビ

Task概要対応する Phaseリソース
query() API基本実装ストリーミングメッセージ処理の基本Phase 1, 2query-api.md, agent-handler-template.ts
Hooks実装PreToolUse/PostToolUse/PermissionPhase 2hooks-system.md
Hooks FactorycreateHooks, セキュリティチェックPhase 2hooks-system.md(TASK-3-1-B)
Permission Control設計権限ルールの設計と実装Phase 1, 2permission-control.md
Electron IPC統合Main-Renderer間のAgent通信Phase 2electron-ipc.md
エラーハンドリングAbortSignal、タイムアウト、リトライPhase 2error-handling.md, hooks-system.md
リトライ機構Exponential Backoff, Jitter, エラー分類Phase 2error-handling.md, retry-patterns.md
MCP統合MCPサーバーとの連携Phase 2, 3mcp-integration.md
セキュリティ設計サンドボックス、ホスティングPhase 2, 3security-sandboxing.md

パターン選択ガイド

claude-agent-sdk vs 直接SDK使用

要件claude-agent-sdk直接SDK (@anthropic-ai/sdk)
Hooks (PreToolUse等)✅ 必要❌ 不要
Permission Control✅ 必要❌ 不要
ストリーミングUI✅ 複雑⚪ シンプル
Main Process専用⚪ 可能✅ 推奨
バッチ処理⚪ 可能✅ 推奨

推奨:

  • 対話型エージェント@anthropic-ai/claude-agent-sdk
  • バックグラウンド処理/バッチ@anthropic-ai/sdk 直接使用

Direct Anthropic SDK Pattern

Main Processでシンプルなクエリを実行する場合のパターン。

typescript
import Anthropic from "@anthropic-ai/sdk";
import { safeStorage } from "electron";
import Store from "electron-store";

// APIキー管理(safeStorage + 環境変数フォールバック)
async function getApiKey(): Promise<string> {
  const store = new Store<{ anthropic_api_key?: string }>();
  const encrypted = store.get("anthropic_api_key");

  if (encrypted && safeStorage.isEncryptionAvailable()) {
    return safeStorage.decryptString(Buffer.from(encrypted, "base64"));
  }

  const envKey = process.env.ANTHROPIC_API_KEY;
  if (envKey) return envKey;

  throw new Error("API key not configured");
}

// 直接SDK呼び出し
async function executeQuery(
  prompt: string,
  systemPrompt?: string,
  timeout = 30000,
): Promise<string> {
  const client = new Anthropic({ apiKey: await getApiKey() });

  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), timeout);

  try {
    const response = await client.messages.create(
      {
        model: "claude-sonnet-4-20250514",
        max_tokens: 8192,
        ...(systemPrompt ? { system: systemPrompt } : {}),
        messages: [{ role: "user", content: prompt }],
      },
      { signal: controller.signal },
    );

    const textContent = response.content.find((b) => b.type === "text");
    return textContent?.type === "text" ? textContent.text : "";
  } finally {
    clearTimeout(timeoutId);
  }
}

📖 実装参照: apps/desktop/src/main/slide/agent-client.ts

SkillExecutor Pattern

フェーズベースのスキル実行パターン。進捗コールバック、キャンセル機能を含む。

typescript
interface SkillExecutor {
  execute(
    phase: SkillPhase,
    projectPath: string,
  ): Promise<SkillExecutionResult>;
  cancel(): void;
  onProgress(callback: (progress: number) => void): void;
  isExecuting(): boolean;
}

// スキルフェーズマッピング
const skillMap: Record<SkillPhase, string> = {
  hearing: "hearing-facilitator",
  structure: "structure-designer",
  html: "html-generator",
  modifier: "slide-modifier",
};

📖 実装参照: apps/desktop/src/main/slide/skill-executor.ts

ベストプラクティス

すべきこと

  • Permission Rulesで適切な権限制御を設計する
  • PreToolUseフックで危険なコマンドをブロックする
  • AbortSignalを使用してタイムアウト処理を実装する
  • IPCチャネル名を一貫した命名規則で設計する
  • ストリーミングメッセージを適切にUI更新に反映する
  • エラー発生時のフォールバック処理を実装する

避けるべきこと

  • permissionMode: 'auto' を本番環境で使用する
  • Hookなしで危険なツール(Bash等)を許可する
  • Main ProcessでUIロジックを処理する
  • ストリーミング中のエラーを無視する
  • APIキーをRenderer Processで扱う
  • signal.abortedのチェックを省略する

クイックリファレンス

パッケージインストール

bash
pnpm add @anthropic-ai/claude-agent-sdk

基本使用例

typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

const conversation = query({
  prompt: "Hello, Claude!",
  options: {
    tools: ["Read", "Edit"],
    permissionMode: "ask",
  },
});

for await (const message of conversation.stream()) {
  console.log(message);
}

Hook実装例

typescript
const options = {
  hooks: {
    PreToolUse: async (input, toolUseID, { signal }) => {
      if (input.toolName === "Bash" && input.args.command?.includes("rm -rf")) {
        return {
          proceed: false,
          message: "危険なコマンドは許可されていません",
        };
      }
      return { proceed: true };
    },
  },
};

リソース参照

責務別ドキュメント

bash
# query() API、SDKMessage型、ストリーミング
cat .claude/skills/claude-agent-sdk/references/query-api.md

# Hooksシステム(全イベント、実装パターン)
cat .claude/skills/claude-agent-sdk/references/hooks-system.md

# Permission Control(4層システム、ルール)
cat .claude/skills/claude-agent-sdk/references/permission-control.md

# Electron IPC統合
cat .claude/skills/claude-agent-sdk/references/electron-ipc.md

# エラーハンドリング(AbortSignal、タイムアウト)
cat .claude/skills/claude-agent-sdk/references/error-handling.md

# リトライパターン(Exponential Backoff, Jitter, エラー分類)
cat .claude/skills/claude-agent-sdk/references/retry-patterns.md

# MCP統合
cat .claude/skills/claude-agent-sdk/references/mcp-integration.md

# セキュリティとサンドボックス
cat .claude/skills/claude-agent-sdk/references/security-sandboxing.md

# 公式URL一覧
cat .claude/skills/claude-agent-sdk/references/official-urls.md

テンプレート参照

bash
cat .claude/skills/claude-agent-sdk/assets/agent-handler-template.ts
cat .claude/skills/claude-agent-sdk/assets/use-agent-hook-template.ts

スクリプト実行

bash
# 最新情報取得
node .claude/skills/claude-agent-sdk/scripts/fetch-latest-info.mjs --help

# 設定検証
node .claude/skills/claude-agent-sdk/scripts/validate-agent-setup.mjs --help

関連ドキュメント

ドキュメントパス説明
Agent SDKインターフェース仕様.claude/skills/aiworkflow-requirements/references/interfaces-agent-sdk.md統合システム設計仕様(型定義、IPC)
実装ガイドdocs/30-workflows/claude-code-integration/outputs/phase-12/implementation-guide.md概念的・技術的実装ガイド

AGENT-005実装成果物

ドキュメントパス説明
要件定義docs/30-workflows/claude-code-integration/outputs/phase-1/受け入れ基準、スコープ
設計docs/30-workflows/claude-code-integration/outputs/phase-2/アーキテクチャ、型定義
テスト仕様docs/30-workflows/claude-code-integration/outputs/phase-4/テストケース設計
実装サマリーdocs/30-workflows/claude-code-integration/outputs/phase-5/implementation-summary.md実装概要
品質検証レポートdocs/30-workflows/claude-code-integration/outputs/phase-9/セキュリティチェック
最終レビューdocs/30-workflows/claude-code-integration/outputs/phase-10/リリースチェックリスト
手動テスト結果docs/30-workflows/claude-code-integration/outputs/phase-11/手動検証結果
実装ガイドdocs/30-workflows/claude-code-integration/outputs/phase-12/implementation-guide.md概念・技術詳細

Slide Agent SDK統合実装成果物(Direct SDK Pattern参照)

ドキュメントパス説明
実装ガイドdocs/30-workflows/slide-agent-sdk-integration/outputs/phase-12/implementation-guide.mdDirect SDKパターン詳細
CHANGELOGエントリdocs/30-workflows/slide-agent-sdk-integration/outputs/phase-12/changelog-entry.mdリリースノート
システム仕様.claude/skills/aiworkflow-requirements/references/interfaces-agent-sdk.mdSDK統合システム仕様(更新済み)

実装ファイル

ファイルパス説明
型定義packages/shared/src/types/agent-execution.tsAgent実行関連型
HooksFactoryapps/desktop/src/main/services/agent/HooksFactory.tsSDK Hooks生成
PermissionRulesapps/desktop/src/main/services/agent/PermissionRules.ts権限ルール定義
AgentExecutorapps/desktop/src/main/services/agent/AgentExecutor.tsSDK query()統合
ExecutionManagerapps/desktop/src/main/services/agent/ExecutionManager.ts複数実行管理
IPCハンドラーapps/desktop/src/main/ipc/agentHandlers.tsIPC通信処理

Slide SDK統合実装ファイル(Direct SDK Pattern)

ファイルパス説明
AgentClientapps/desktop/src/main/slide/agent-client.tsDirect SDK呼び出し、シングルトン
SkillExecutorapps/desktop/src/main/slide/skill-executor.tsフェーズマッピング、進捗コールバック
型定義packages/shared/src/types/slide.tsSkillPhase, SkillExecutionResult

TASK-SKILL-RETRY-001 リトライ機構実装成果物

ドキュメントパス説明
実装ガイド(概念)docs/30-workflows/skillexecutor-retry-mechanism/outputs/phase-12/implementation-guide-part1.md中学生レベル概念説明
実装ガイド(技術)docs/30-workflows/skillexecutor-retry-mechanism/outputs/phase-12/implementation-guide-part2.md型定義・API・使用例
システム仕様.claude/skills/aiworkflow-requirements/references/interfaces-agent-sdk-executor.mdRetryConfig, isRetryableError
エラー仕様.claude/skills/aiworkflow-requirements/references/error-handling.mdリトライ戦略セクション

TASK-SKILL-RETRY-001 実装ファイル

ファイルパス説明
SkillExecutorapps/desktop/src/main/services/skill/SkillExecutor.tsexecuteWithRetry, isRetryableError, backoff
テストapps/desktop/src/main/services/skill/__tests__/SkillExecutor.retry.test.ts72テストケース(9カテゴリ)

TASK-3-1-B Hooks実装成果物

ドキュメントパス説明
実装ガイドdocs/30-workflows/task-3-1-b-hooks/outputs/phase-12/implementation-guide.mdcreateHooks, エラーハンドリング
テスト仕様apps/desktop/src/main/services/skill/__tests__/hooks.test.tsPreToolUse/PostToolUseテスト
エラーテストapps/desktop/src/main/services/skill/__tests__/error.test.tscategorizeError/isRetryable
システム仕様.claude/skills/aiworkflow-requirements/references/interfaces-agent-sdk.md型定義、メソッドシグネチャ

TASK-3-1-B実装ファイル

ファイルパス説明
SkillExecutorapps/desktop/src/main/services/skill/SkillExecutor.tscreateHooks, categorizeError, isRetryable

TASK-3-1-E 権限永続化成果物

ドキュメントパス説明
実装ガイドdocs/guides/permission-store.mdPermissionStore API、IPC連携
システム仕様.claude/skills/aiworkflow-requirements/references/security-skill-execution.mdデータスキーマ、ストレージパス
設定UI仕様.claude/skills/aiworkflow-requirements/references/ui-ux-settings.mdPermissionSettings UI

TASK-3-1-E 実装ファイル

ファイルパス説明
PermissionStoreapps/desktop/src/main/services/skill/PermissionStore.ts権限永続化ストア(electron-store)
permission-handlersapps/desktop/src/main/ipc/permission-handlers.tsIPC handlers(getAllowedTools等)
PermissionSettingsapps/desktop/src/renderer/components/settings/PermissionSettings/設定UI

TASK-IMP-permission-history-001 Permission History Tracking

区分ファイル
タスク仕様書docs/30-workflows/TASK-IMP-permission-history-001/
実装ガイドoutputs/phase-12/implementation-guide.md
システム仕様(状態管理)arch-state-management.md(permissionHistorySlice)
システム仕様(UI)ui-ux-settings.md(Permission History Panel)
システム仕様(履歴)interfaces-agent-sdk-history.md
実装ファイルpermissionHistorySlice.ts, permissionHistory.ts
UIコンポーネントPermissionHistoryPanel.tsx, PermissionHistoryItem.tsx, PermissionHistoryFilter.tsx
テストpermissionHistory.test.ts, permissionHistorySlice.test.ts, PermissionHistoryPanel.test.tsx

Key patterns from this task:

  • Cross-Slice access: (get() as unknown as PermissionHistorySlice).addHistoryEntry()
  • Security: safeArgsSnapshot() for argument sanitization (max 200 chars)
  • Virtual scroll: @tanstack/react-virtual for 1000-entry performance

TASK-9C スキル改善・自動修正機能(Skill Improvement & Auto-fix)

区分ファイル
タスク仕様書docs/30-workflows/TASK-9C-skill-improver/
実装ガイドoutputs/phase-12/implementation-guide.md
システム仕様interfaces-agent-sdk-skill.md(IPC 5チャネル追加)、arch-electron-services.md
実装ファイルSkillAnalyzer.ts, SkillImprover.ts, PromptOptimizer.ts
ユーティリティutils/fileUtils.ts, utils/sdkUtils.ts
テストSkillAnalyzer.test.ts, SkillImprover.test.ts, PromptOptimizer.test.ts(83件)

Key patterns from this task:

  • Graceful SDK fallback: tryAgentSdkWithFallback()でSDKエラー時にフォールバック
  • DI Pattern: queryFnパラメータでSDK呼び出しを注入可能に
  • Backup strategy: 改善前にバックアップを自動作成
  • Analysis categories: static, ai, combined分析モード

変更履歴

VersionDateChanges
2.9.02026-02-03TASK-9Cスキル改善・自動修正機能成果物追加(SkillAnalyzer, SkillImprover, PromptOptimizer、83テスト、Graceful fallbackパターン)
2.8.02026-02-01TASK-IMP-permission-history-001 Permission History Tracking成果物追加(Cross-Slice access, safeArgsSnapshot, Virtual scroll)
2.7.02026-01-31retry-patterns.mdリファレンス新規作成、error-handling.mdリトライセクション最適化(outdated値修正、cross-reference追加)
2.6.02026-01-31TASK-SKILL-RETRY-001リトライ機構パターン追加(RetryConfig, isRetryableError, Exponential Backoff with Jitter)
2.5.02026-01-26TASK-3-1-E権限永続化パターン追加(PermissionStore API、rememberChoice連携、データスキーマ)
2.4.02026-01-25TASK-3-1-B Hooks実装パターン追加(createHooks, categorizeError, isRetryable, セキュリティチェック関数)
2.3.02026-01-17Direct SDK Pattern追加、Slide SDK統合実装参照追加、パターン選択ガイド追加
2.2.02026-01-12AGENT-005実装成果物・実装ファイル参照追加、パス修正
2.1.02026-01-08関連ドキュメントセクション追加、aiworkflow連携
2.0.02026-01-08責務ベースに再構成、最新情報取得フロー追加
1.0.02026-01-08初期バージョン作成