Claude Codeのatomic-agentsプラグインでフレームワーク流にエージェントを組む

atomic-agentsプラグインはClaudeに何を覚えさせるのか

atomic-agentsプラグインは、PythonのAtomic Agentsフレームワークでコードを書くときの作法をClaude Codeに持たせるプラグインです。Claudeがatomic_agentsのimportを見つけると、スキーマ、エージェント、ツール、コンテキストプロバイダー、プロンプト、プロバイダー設定の決まりごとを必要な分だけ読み込みます。ドキュメントを貼り付ける手間はありません。

Atomic Agents本体は、InstructorとPydanticの上に作られた軽量フレームワークです。エージェントもツールもコンテキストプロバイダーも、単一目的で再利用できる部品として扱います。入出力はすべてスキーマで型付けされるため、LLMの出力が崩れにくい設計です。

プラグイン側は2.2.0で、中身はスキル7本とサブエージェント2本です。

プラグインの動作要件は、Python 3.12以上、Atomic Agents 2.7以上、Instructor 1.14以上、Pydantic 2です。Python 3.12を求めるのは、フレームワークがPEP 695のジェネリクスを使うためです。

入れ方は3通りある

導入経路は、READMEが挙げる3つから選びます。Claude Marketplaceのページにも、このプラグインのClaude Code向け導入ボタンがあります。

READMEが「推奨」とするのはこの経路です。リポジトリのmainへの更新が、/plugin marketplace updateで届きます。

/plugin marketplace add eigenwise/atomic-agents
/plugin install atomic-agents@eigenwise
/reload-plugins

もう1つはAnthropicのコミュニティマーケットプレイスです。READMEによれば、掲載承認後はこちらからも入れられます。コミュニティ側は申請フォーム経由の登録制で、プルリクエストは自動で閉じられる運用です。

/plugin marketplace add anthropics/claude-plugins-community
/plugin install atomic-agents@claude-community

3つ目は、リポジトリ単位で全員に入れさせる書き方です。.claude/settings.jsonに次を書くと、フォルダを初めて信頼したメンバーに導入が促されます。例えば次のような形になります(READMEの記載に沿った形です)。

{
  "extraKnownMarketplaces": {
    "eigenwise": {
      "source": { "source": "github", "repo": "eigenwise/atomic-agents" }
    }
  },
  "enabledPlugins": {
    "atomic-agents@eigenwise": true
  }
}

ここで注意したいのは、enabledPluginsに書くだけでは各メンバーのマシンにプラグインがダウンロードされない点です。Claude Codeの公式ドキュメントによると、プロジェクトスコープの設定は有効化の記録であり、各自がclaude plugin install <name>@<marketplace> --scope projectを1回実行する必要があります。導入経路の使い分けはclaude plugin installの導入経路を選ぶ記事に、プラグインの仕組みの全体像はプラグインとマーケットプレイスのガイドにあります。

導入後、プラグインのスキルは/プラグイン名:スキル名の形で呼び出します。このプラグインなら/atomic-agents:new-appです。同名のスキルがユーザーやプロジェクト側にあっても、プラグインのスキルは名前空間で分かれるため両方が読み込まれます。

new-appで動く雛形を1つ作る

白紙から始めるなら、new-appが最短です。このスキルはモデルの自動起動が切られており、利用者が明示的に呼んだときだけ動きます。

/atomic-agents:new-app support-bot

最初に4つの質問がまとめて出ます。省いたものは引数や会話から補われます。

1. プロジェクト名(ディレクトリ名はケバブケース、パッケージ名はスネークケースに正規化)
2. LLMプロバイダー(OpenAI、Anthropic、Groq、Ollama、Gemini、OpenRouter、MiniMax。既定はOpenAI)
3. エージェントの種類(一言で。システムプロンプトとスキーマの初期形を決める)
4. パッケージ管理(既定はuv、pip + venvも可)

レイアウトやPythonのバージョン、依存関係は聞かれません。スキルが決めます。そのうえで計画を短く示し、了承を待ってから作成に入ります。

生成されるのはpyproject.toml、.env.example、.gitignore、README.md、AGENTS.md、CLAUDE.md、そして__init__.pyと、REPL付きのmain.pyを持つパッケージです。

特に便利なのがAGENTS.mdとCLAUDE.mdの組です。CLAUDE.mdの中身は@AGENTS.mdの1行だけで、Claude Codeは同じファイルを重複なしで読めます。AGENTS.mdにはフレームワークの規約が入ります。

• AtomicAgent[InputSchema, OutputSchema]の型パラメータは実行時情報を持つので、正確に書く
• LLMクライアントはInstructorでラップしてからAgentConfig.clientに渡す
• BaseIOSchemaのサブクラスには空でないdocstringと、各フィールドのField(..., description=...)が要る
• temperatureやmax_tokensはAgentConfig.model_api_parametersに入れる

プロバイダーごとの癖は、AGENTS.mdに1行ずつ書き添えられます。

生成後は、スキルが依存関係を入れて、APIキー無しでimportが通るかを確かめます。キーは.env.exampleをコピーして入れ、uv run python -m <パッケージ名>.mainでREPLを動かす流れです。.env自体はコミットしない、グローバルにインストールしない、というのがスキルの制約に書かれています。

雛形のAGENTS.mdは、そのままAtomic Agents以外のツール(CursorやCodexなど)にも効きます。AGENTS.mdとCLAUDE.mdの統合運用と同じ考え方を、フレームワークの規約で先に実践した形です。

create-*スキルで部品を1つずつ足す

雛形ができたら、部品を足していきます。ここで効くのがcreate-*の4本です。起動のきっかけは「エージェントを追加して」「ツールを作って」のような普通の依頼文で、スラッシュコマンドを打たなくても働きます。

流れは4本とも共通です。

create-atomic-agentの実装段階では、スキーマの組を先に決め、SystemPromptGeneratorをbackground(誰か)、steps(どう進めるか)、output_instructions(出力の決まり)の3区分で書きます。完成形は次のようになります。例として示された形に沿ったもので、Claudeの実出力そのものではありません。

agent = AtomicAgent[MyInput, MyOutput](
    config=AgentConfig(
        client=client,
        model=model,
        history=ChatHistory(),  # 単発の変換なら省く
        system_prompt_generator=SystemPromptGenerator(
            background=["You are a concise research assistant."],
            steps=[
                "Read the question carefully.",
                "Produce the answer in the required schema.",
            ],
            output_instructions=["Reply under 100 words."],
        ),
        model_api_parameters={"temperature": 0.2},
    )
)

スキーマの担当はcreate-atomic-schema、外部APIを包む担当はcreate-atomic-tool、プロンプトへ実行時の情報を差し込む担当はcreate-atomic-context-providerです。エージェントの依頼に答える途中で、カスタムスキーマが要ると分かれば、create-atomic-agentがcreate-atomic-schemaへ話を渡します。依頼を1回で全部頼まず、部品ごとに区切って頼むほうが、各スキルの確認項目が活きます。

create-atomic-agentのスキルは、動かない原因になりやすい点も先に挙げています。

• Anthropicでmax_tokensが無いと、すべての呼び出しが拒否される
• Geminiでassistant_role="model"を忘れると、毎ターン役割が食い違う
• Groq・Ollama・MiniMaxでMode.TOOLSを使うと、ツールの形式が受け付けられない
• AgentConfig.modeとInstructorファクトリのmodeがずれる
• 長時間動くサービスでChatHistoryが際限なく伸びる

frameworkスキルは必要な参照だけを読み込む

frameworkスキルの本体は、フレームワークの概念表と、ごく小さな最小エージェントの例、そして参照ファイルへの振り分け表です。スキーマ、エージェント、ツール、コンテキストプロバイダー、プロンプト、オーケストレーション、メモリー、フック、プロバイダー、プロジェクト構成、テストの11本が、作業に応じて1本ずつ読み込まれます。

これは、プラグインを入れてもコンテキストが膨らみにくい作りです。スキルの説明文だけが常に見え、本文は必要になって初めて読まれます。READMEは、各スキルをSKILL.mdとreferences/の組にして、参照を1段の深さに保つと説明しています。実際にどれだけコンテキストを使うかは、claude plugin detailsでプラグインのコンテキスト消費を測る記事の手順で手元の環境ごとに測れます。スキルの書式そのものはSkillsのSKILL.mdの書き方にまとまっています。

このスキルが採用を勧める方針は、次の6つです。

• スキーマを契約として先に設計する
• システムプロンプトは3区分で書く
• プロバイダーのクライアントは必ずInstructorでラップする
• プロバイダー固有の設定はmodel_api_parametersに置く
• エラーと再試行はフック(parse:error、completion:error、completion:last_attempt)で扱い、run()をtry/exceptで包まない
• ツールは成功時に出力スキーマを返し、ありがちな失敗は型付きの結果にする

特に最後の方針は、素のPythonの感覚と食い違いやすい点です。例外で握りつぶさず、スキーマの記述を直す方向へ進む、というのが一貫した考え方です。

既存コードにはexplorerとreviewerを当てる

コードベースがすでに大きいときは、2本のサブエージェントの出番です。どちらもモデルはsonnet、ツールはGlob・Grep・LS・Read・NotebookRead・TodoWriteで、書き込みはできません。読み取りが多い作業を別のコンテキストへ逃がし、結果の要約だけを親に返す設計です。

atomic-explorerは「このプロジェクトの仕組みを教えて」のような依頼で働きます。pyproject.tomlで構成を見たあと、AtomicAgent[、BaseTool[、BaseDynamicContextProvider、SystemPromptGeneratorといった目印をgrepして、エージェント、スキーマ、ツール、コンテキストプロバイダー、オーケストレーションをファイル:行つきの地図にして返します。小さなプロジェクトでは、親スレッドで直接読むほうが早いとframeworkスキル自身が書いています。

atomic-reviewerは、コミットやPRの前に使います。確認項目は、スキーマ、エージェント、ツール、コンテキストプロバイダー、プロンプト、オーケストレーション、セキュリティ、フック、よくあるAPIの誤用、テストの10区分です。信頼度が75を超えた指摘だけを報告し、セキュリティは50から報告します。指摘には必ず直し方が付きます。

このレビュー役には、設計上の癖が2つあります。

• モデル名の存在や、model_api_parametersのキーが有効かには触れない。モデル知識が古い可能性があり、誤検出の最大の原因だったためです。v2.1.0では、現行世代のモデル名をエラー扱いする不具合も直されています
• 埋め込み、画像生成、音声、モデレーションに生のSDKクライアントを使っても指摘しない。AgentConfig.clientに渡すクライアントだけが、Instructorラップの対象です

つまり、一般的なPythonの作法やアルゴリズムの批評はしません。汎用のレビューを置き換えるのではなく、フレームワーク固有の観点を足す役です。サブエージェントの定義や権限の詳しい扱いはサブエージェントのガイドを参照してください。

つまずいたらtroubleshootに症状を貼る

エラーのトレースバックを貼ると、troubleshootスキルが働きます。症状の表に、フレームワークが実際に出すメッセージが並んでいます。

直したら必ず再実行して確かめる、一致する症状が無ければ該当する参照ファイルを読んで推論する、という手順がスキルに書かれています。コードが壊れている最中はtroubleshoot、壊れていないコードの点検はatomic-reviewerという切り分けです。

3つの層に役割を分けている

このプラグインの設計は、知識を置く場所を3つに分けている点が読みどころです。

1. スキルは、必要になったときだけ読み込む知識です。フレームワークの作法や手順を持ちます
2. サブエージェントは、読み取りが重い作業を隔離します。探索とレビューが該当します
3. 雛形のAGENTS.mdは、プロジェクトに常駐する規約です。プラグインを入れていない人やツールにも効きます

READMEはこの分け方を、Anthropicが自社のプラグインで採っている「参照スキルとサブエージェントの併用」と同じ型だと位置づけています。変更履歴を見ると、この形は最初からではありません。v1.0.0では4本のサブエージェントと3本のスラッシュコマンドがありました。v2.0.0で大半をスキルに寄せ、サブエージェントは探索とレビューの2本に絞っています。「成果物を親のスレッドで直しながら進めたいもの」はサブエージェントに向かない、という理由が変更履歴に残っています。

自分のチームのプラグインにも、この線引きは参考になります。ほとんどの知識は読み込み式のスキルにして、サブエージェントは、中間の読み込みが親を汚す作業に限る方向です。プラグイン直下のsettings.jsonで既定のエージェントを配る方法は、プラグインのsettings.jsonの記事で扱っています。なお、同様に「エージェント・スキル・フックを一式で配る」構成の実例として、everything-claude-codeの構成も比較対象になります。

どの場面で使うか

プラグインの価値が出るのは、Atomic Agentsのコードを書き続けるときです。数回の試し書きなら、frameworkスキルが自動で働くだけで十分です。新規に立ち上げるならnew-app、部品が増えてきたらcreate-*、既存の資産を読み解くならatomic-explorer、コミット前にatomic-reviewer、動かないときにtroubleshootという順で、場面と役割が1対1で対応します。

PythonでAIエージェントを組むためのフレームワークは複数ありますが、このプラグインが扱うのはAtomic Agents専用です。別のフレームワークのコードには、atomic_agentsのimportが無いので働きません。

まとめ

atomic-agentsプラグインを入れる意味は、フレームワークの作法を「毎回貼る文書」から「必要なときに読まれる知識」に変えることにあります。入れたら、まず/atomic-agents:new-appで雛形を作り、生成されたAGENTS.mdにチームの規約を1行ずつ足していくのが、立ち上がりの早い進め方です。レビューを任せる前に、モデル名の検証は対象外という癖だけ頭に入れておくと、指摘の読み方で迷いません。