agent-builder

Agent Builder - Claude SDK と CLI のエキスパート

トリガー：

• 「エージェントを構築」「エージェントを作成」「エージェント SDK」「Claude SDK」
• 「ヘッドレスモード」「プログラムによる実行」「CLI コマンド」
• 「claude -p」「プログラムからクエリを実行」
• 「カスタムツール」「MCP サーバー」「SDK MCP」
• 「Claude Code API」「エージェントのオプション」

---

Claude Code のヘッドレスモードを優先する

このスキルの対象は、Claude Code のヘッドレスモードと Agent SDK です。Anthropic API を直接使う方法ではありません。

Preferred: Claude Code CLI headless mode (claude -p)
Preferred: Claude Agent SDK (wraps Claude Code CLI)
Avoid:     Raw Anthropic API (anthropic.Anthropic())
Avoid:     Direct API calls with API keys

重要な理由：

• Agent SDK は Claude Code CLI をラップしており、Anthropic API を直接使用しません
• 認証には既存の ~/.claude/ 設定が使われるため、API キーは不要です
• すべての設定、MCP サーバー、構成は Claude Code の設定を引き継ぎます
• Claude Code の完全なエージェントループ、ツール、コンテキスト管理を利用できます

ルール： コードで anthropic.Anthropic()、anthropic.messages.create() を使う場合や、ANTHROPIC_API_KEY が必要な場合は、誤った方法です。代わりに claude -p または claude_agent_sdk を使用してください。

---

主な機能

1. Claude Agent SDK Python - カスタムツールやフックを備えた、プログラムによるエージェントの作成（Claude Code CLI をラップ）
2. ヘッドレス／プリントモード - CLI、スクリプト、CI/CD から Claude Code を実行（claude -p）
3. CLI リファレンス - すべてのコマンド、フラグ、設定オプション

すべて Claude Code の既存の ~/.claude/ 認証を使用するため、API キーは不要です。

---

ドキュメントの参照先

• Agent SDK: https://github.com/anthropics/claude-agent-sdk-python
• ヘッドレスモード: https://code.claude.com/docs/en/headless
• CLI リファレンス: https://code.claude.com/docs/en/cli-reference

---

ワークフロー

1. 要件を把握する - どのような種類のエージェント／自動化が必要ですか？
2. 依存関係を確認する - Python のバージョン、パッケージ、Claude Code のインストール状況を確認します
3. 最新のドキュメントを参照する - 詳細が不明な場合は、関連するドキュメントを取得します
4. 確実に構築する - 適切なエラー処理を備えた、本番環境向けのコードを作成します
5. すぐにテストする - 実装を実行して検証します

---

リファレンスファイル

現在のタスクに関連するリファレンスファイルのみを読み込みます。

タスク	読み込むファイル
Anthropic API の直接利用と Claude Code SDK のパターンを区別する	references/api-vs-sdk.md
Agent SDK を使った Python エージェントの作成（インストール、クエリ、クライアント、ツール、フック、エラー）	references/sdk-python.md
ヘッドレス claude -p モードの使用（基本、JSON スキーマ、ストリーミング、ツールの承認、セッション、システムプロンプト）	references/headless-cli.md
CLI コマンド、フラグの表、動的サブエージェント、権限ルールの構文	references/cli-reference.md
ユースケースのテンプレート：CI/CD パイプライン、コードレビュー、カスタム分析ツール、データベースクエリエージェント	references/use-cases.md
Agent SDK と CLI／ヘッドレスモードのベストプラクティス	references/best-practices.md
エージェントの完全なエンドツーエンドの例（ツール＋フック＋クライアント）	references/example-agent.md
作成する成果物の出力形式に関する規約	references/output-format.md

---

セキュリティ

• 本番環境では --dangerously-skip-permissions を使用しないでください
• カスタムツールで入力を検証してください
• 権限ルールを使って、破壊的なコマンドをブロックしてください
• --max-budget-usd で予算の上限を設定してください
• 機密性の高い操作にはフックを実装してください
• 自動化の前に、許可されたツールを確認してください

---

簡易判断フロー

必要な操作

• 単発のクエリを実行する → claude -p "query"
• カスタムエージェントを構築する → ClaudeSDKClient を使った Agent SDK
• カスタムツールを追加する → @tool デコレーターを使った SDK MCP サーバー
• 実行を制御する → HookMatcher を使ったフック
• 応答をストリーミングする → --output-format stream-json
• 構造化データを取得する → --json-schema
• 会話を続ける → --continue または --resume
• CI/CD で実行する → --allowedTools を指定した claude -p
• アプリに統合する → query() または ClaudeSDKClient を使った Python SDK

---

ドキュメントを取得するタイミング

次の場合は、最新のドキュメントを取得してください。

• API のシグネチャやパラメーターが不明な場合
• 新機能やフラグについて言及されている場合
• エラーメッセージに未知の設定が記載されている場合
• 複雑なフックや MCP サーバーを実装する場合
• ユーザーから特定の機能について質問された場合

WebFetch ツールを使用して、ソース URL から最新のドキュメントを取得してください。

---

実装チェックリスト

コードを書く前に：

• 確認： Claude Code のヘッドレスモード（claude -p または claude_agent_sdk）を使用していること。生の Anthropic API は使用しないでください
• 確認： コードに API キーが含まれていないこと。認証は ~/.claude/ の設定から行います
• Python のバージョンを確認する（3.10 以降）
• Claude Code CLI のインストールを確認する（which claude）
• uv pip list で必要なパッケージを確認する
• 具体的なユースケースを把握する
• SDK と CLI のどちらのアプローチが必要か判断する

コードを書いた後に：

• 確認： コードが claude_agent_sdk または claude -p を使用していること。anthropic.Anthropic() は使用しないでください
• 確認： コードに ANTHROPIC_API_KEY や api_key= パラメーターが含まれていないこと
• すべての SDK 例外に対するエラー処理を追加する
• Claude Code の実際のインストール環境でテストする
• ツールの権限とセキュリティを検証する
• 適切な制限（ターン数、予算）を設定する
• カスタムツールとその用途を文書化する

---

スキルの呼び出し

このスキルでは、以下を提供します。

• Agent SDK の完全な実装ガイダンス
• ヘッドレス／CLI コマンドの構築
• MCP サーバーを使用したカスタムツールの作成
• 制御フローのためのフックの実装
• セキュリティのベストプラクティス
• 必要に応じた最新ドキュメントの取得

エージェントの構築、ヘッドレスコマンドの実行、または CLI の使用方法について、具体的な質問をしてください。

---

制限事項

• Agent SDK は Python 専用です（Python 3.10 以降）。ここでは JavaScript やその他の言語のバインディングは扱いません。
• SDK またはヘッドレスモードを使用する前に、Claude Code CLI がインストールされ、~/.claude/ を通じて認証されている必要があります。
• このスキルでは生の Anthropic API の使用（anthropic.Anthropic()）は扱いません。詳細は Anthropic API のドキュメントを参照してください。
• SDK を通じて起動したエージェントプロセスは、デフォルトで一時的なものです。セッションを永続化するには、明示的に --resume を指定するか、セッション ID を取得する必要があります。
• このスキルの MCP サーバーのパターンでは stdio トランスポートを使用します。HTTP ベースの MCP トランスポートには、このスキルでは扱わない別途の設定が必要です。