Claude Media
Claude Codeのagent-sdk-devプラグインで/new-sdk-appからAgent SDKアプリを作る
Claude CodeAgent SDKチュートリアル

Claude Codeのagent-sdk-devプラグインで/new-sdk-appからAgent SDKアプリを作る

agent-sdk-devプラグインを入れると、/new-sdk-appで言語・用途を選ぶだけでAgent SDKの雛形ができ、検証エージェントが設定と使い方を点検します。導入から検証レポートの読み方までを手順で示します。

読了目安 約9分

agent-sdk-devは、Claude Agent SDKのアプリをTypeScriptまたはPythonで作るためのClaude Codeプラグインです。/new-sdk-appコマンドが雛形を作り、検証用のサブエージェントが「SDKの使い方として正しいか」を点検します。入れるものはこの2点だけで、自作のエージェント本体をこのプラグインが書いてくれるわけではありません。

agent-sdk-devプラグインは何を提供するか

プラグインの中身は、コマンド1つとエージェント2つです。

構成

agent-sdk-devの構成要素

  • /new-sdk-app

    対話形式でプロジェクトを作るコマンドです。言語・プロジェクト名・エージェントの種類・出発点を聞かれます。

  • agent-sdk-verifier-py

    Python版アプリの検証エージェントです。

  • agent-sdk-verifier-ts

    TypeScript版アプリの検証エージェントです。

マーケットプレイスのページでは、提供元はAnthropicで「Anthropic verified」の表示があります。説明文は「新規プロジェクトの足場づくりから、ベストプラクティスに沿っているかの検証まで」を通しで支援する開発キットとしています。READMEのバージョンは1.0.0です。

SDK自体の最小構成はClaude Agent SDK入門にあります。このプラグインは、その最初の一歩を対話で自動化し、書いたあとの点検を足す位置にあります。

インストールして/new-sdk-appを使えるようにする

プラグインはAnthropic公式マーケットプレイス(claude-plugins-official)にあります。マーケットプレイスのページにある「Claude Code」ボタンは、シェル形式のインストールコマンドをコピーします。

claude plugin install agent-sdk-dev@claude-plugins-official

Claude Codeのセッション内からなら、/plugin installでプラグイン詳細のパネルが開き、スコープを選べます。

/plugin install agent-sdk-dev@claude-plugins-official

チームで使うなら、プロジェクトスコープ(--scope project)にすると有効化の設定が.claude/settings.jsonに入ります。ただし、設定をコミットしても各メンバーの端末にプラグインが入るわけではありません。各自が一度claude plugin install agent-sdk-dev@claude-plugins-official --scope projectを実行します。インストール後、開いているセッションでは/reload-pluginsで反映できます。プラグイン全般の仕組みはClaude Codeプラグイン完全ガイドにまとめています。

READMEの「Installation」節は「Claude Codeのリポジトリに含まれており、コマンドとエージェントは自動的に使える」という書き方です。一方、マーケットプレイスのページはインストール導線を持ち、公式のプラグイン導入手順も@claude-plugins-official付きのコマンドです。コマンドが見えないときは、上のインストールが済んでいるかをまず確かめてください。

/new-sdk-appで雛形を作る

引数にプロジェクト名を付けても、付けなくても動きます。

/new-sdk-app customer-support-agent

READMEによると、コマンドは次の項目を順に聞いてきます。

質問選択肢(READMEの記載)
言語選択肢(READMEの記載)TypeScript / Python
プロジェクト名選択肢(READMEの記載)引数で渡していなければ質問される
エージェントの種類選択肢(READMEの記載)コーディング・ビジネス・カスタム
出発点選択肢(READMEの記載)最小構成・基本構成・特定の例
ツール選択肢(READMEの記載)npm / yarn / pnpm、またはpip / poetry

回答が終わると、コマンドは次の作業を進めると書かれています。

手順

/new-sdk-appが進める作業

  1. 1

    最新のSDKを入れる

    SDKの最新版を確認してインストールします。

  2. 2

    ファイルを作る

    必要なプロジェクトファイルと設定、.env.example、.gitignoreを作り、用途に合わせた動く例を置きます。

  3. 3

    型・構文を確認する

    TypeScriptなら型チェック、Pythonなら構文の検証を実行します。

  4. 4

    検証エージェントを呼ぶ

    言語に合うverifierが自動で走ります。

READMEの例では、code-reviewer-agentというプロジェクトを「TypeScript・コーディングエージェント(コードレビュー)・基本構成」で作り、完了後にAPIキーを.envに書いてnpm startで動かす流れです。

echo "ANTHROPIC_API_KEY=your_key_here" > .env
npm start

実際に何が生成されるかは、選択肢とそのときのSDKの版で変わります。生成物の中身はREADMEが列挙していないため、作った直後にgit statusとディレクトリ一覧で目を通してからコミットすると安全です。.envが.gitignoreに入っていることも、このときに確認できます。

検証エージェントは何を点検するか

verifierは、/new-sdk-appの最後に自動で走るほか、あとから頼んでも動きます。

Verify my TypeScript Agent SDK application

READMEが挙げる呼び出し例は「Verify my Python Agent SDK application」「Check if my SDK app follows best practices」などです。

点検項目は両言語で共通する部分が多く、言語固有の項目が加わります。

点検項目Python版TypeScript版
SDKのインストールとバージョンPython版ありTypeScript版あり
環境設定Python版requirements.txt、pyproject.tomlTypeScript版tsconfig.json
SDKの正しい使い方・パターンPython版ありTypeScript版あり
型安全性とimportPython版記載なしTypeScript版あり
エージェントの初期化と設定Python版ありTypeScript版あり
環境とセキュリティ(.env、APIキー)Python版ありTypeScript版あり
エラー処理と機能Python版ありTypeScript版あり
ドキュメントの充実度Python版ありTypeScript版あり

「記載なし」は、READMEの点検項目リストにその項目が出ていないという意味です。Python版が型を一切見ないとは断言できません。

出力は、全体の状態がPASS・PASS WITH WARNINGS・FAILのどれかで示されます。レポートには、機能を妨げる重大な問題、最適でないパターンへの警告、通ったチェックの一覧、SDKドキュメントへの参照つきの推奨事項が入ります。

レポートを読んで直す順番

WARNINGSは「動くが改善余地あり」、FAILは「機能を妨げる問題あり」と読み分けられます。READMEのトラブルシューティングも、警告は機能を止めないが改善点を示す、という位置づけです。

切り分け

検証結果が出たときの切り分け

  1. Q全体の状態はPASSまたはPASS WITH WARNINGSか?
    答えがいいえ(FAIL)

    重大な問題の項目から順に直します。TypeScriptならnpx tsc --noEmit、Pythonならpip show claude-agent-sdkで、SDKが入っているかをまず確かめます。

    答えがはい
  2. Q警告にAPIキーや.envに関するものは無いか?
    答えがある

    デプロイ前に片付けておく項目です。READMEは.envをコミットしないこと、APIキーをコードに直書きしないことを注意点に挙げています。

    答えがはい

それ以外の警告

レポートが示すSDKドキュメントの参照先を読んで、直すかどうかを決めます。

READMEが載せている典型的なつまずきは3つです。

  • TypeScriptの型エラー: 作成直後に出た場合は、SDKが最新版か、tsconfig.jsonがSDKの要件に合っているかを見ます
  • Pythonでclaude_agent_sdkをimportできない: pip install -r requirements.txtを実行したか、仮想環境を有効にしているかを確かめます
  • verifierの警告: 具体的な警告文とドキュメント参照を読みます

既存プロジェクトの定期点検に使う

verifierは新規作成時だけのものではありません。READMEは、既存のSDKアプリを変更したあとと、デプロイの前にも使うよう書いています。この使い方を忘れないために、プロジェクトのCLAUDE.mdに一文置く方法があります。

## Agent SDKアプリの変更後
- SDKに関わるコードを変えたら、ユーザーに完了を伝える前にagent-sdk-verifier-tsを実行する
- FAILが出たら修正して再実行する。PASS WITH WARNINGSは警告の内容を要約して報告する

これは公式READMEにある記述ではなく、運用の一案です。verifierは「頼まれたときに走る」エージェントなので、依頼の文言をCLAUDE.mdに固定しておくと、毎回の指示を省けます。PythonのプロジェクトならエージェントをPython版に置き換えます。

SDKのプラグイン読み込みとは別物

名前が似ているため混同しやすい点があります。agent-sdk-devは、Claude Codeの側に入れて「Agent SDKのアプリを作る・点検する」ための道具です。作ったアプリがプラグインをロードする方法は、Agent SDKプラグインをロードする方法が扱うSDKのpluginsオプションの話で、仕組みが違います。進捗表示のような個別の機能を足す段階では、Agent SDK Todo Trackingで進捗をアプリに表示するのように機能単位の記事を参照するほうが近道です。

よくある質問

検証エージェントはデプロイの代わりになりますか

なりません。READMEが示すのは、SDKの使い方・設定・セキュリティ・ドキュメントの点検であり、本番環境での動作保証ではありません。テストは別に用意します。READMEもベストプラクティスとして、エージェントの機能のテストケースを作ることを挙げています。

作成後にSDKの版が古くなったらどうなりますか

READMEは、/new-sdk-appが最新版を確認してインストールすると説明しています。作成後に版が進んだ場合は、verifierがSDKのインストールとバージョンを点検項目に持っているので、再実行で状態を確認できます。

まとめ

agent-sdk-devの価値は、雛形生成よりも、同じ観点で点検し直せる検証エージェントにあります。新規作成では/new-sdk-appで言語と用途を選び、作成直後のverifierの結果を読む。変更後やデプロイ前には、言語に合うverifierを頼み直す。この2点を運用に入れると、SDKの使い方のずれを早めに拾えます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →