swarma -- エージェントチーム向け成長実験ループ

このスキルを使用する場合

ユーザーが以下を希望する場合にswarmaを使用してください:

• 成長実験を実行する(フック、ランディングページ、アウトリーチ、価格設定、アクティベーション、リテンション)
• A/Bテストを通じて学習と改善を続けるエージェントチームを構築する(単に1回実行するだけではなく)
• 特定のオーディエンス/プロダクトに対して実際に機能することの検証済みプレイブックを取得する
• 規模での実験をテストする(週2〜5回ではなく、50回以上の実験)
• 「試したけど機能しなかった」を記録・分析・検索可能な実験データに置き換える

トリガーフレーズ: 「何が機能するかテストしたい」「ファネルを最適化したい」「最高のフックを見つけたい」「実験を実行したい」「A/Bテストしたい」「何が機能しているか」「プレイブックを構築したい」「成長実験」「コンバージョンを改善したい」

使用しないでください: ユーザーがワークフロー自動化(n8n/Makeを使用)、会話メモリ(honcho を使用)、またはワンショットエージェントパイプライン(CrewAI/AutoGenを使用)を希望する場合。swarmaは特に時間をかけて改善する実験ループ向けです。

---

クイックリファレンス

コマンド一覧

コマンド	動作	使用時機
swarma init	インスタンス+スターターチームを作成	初回セットアップ
swarma cycle <team>	1つの実験サイクルを実行	テスト、手動実行
swarma cycle <team> --topic "..."	特定のトピックでサイクルを実行	アドホック実験
swarma team create <name> --from-goal "..."	ゴールからチームを生成	新しい実験領域を開始
swarma team show <name>	チームの設定を確認	生成されたもの内容を確認
swarma team list	すべてのチームを表示	概要確認
swarma status	コスト、最近の実行、実験を表示	ヘルスチェック
swarma metric log <team> <agent> <value>	外部メトリクスを記録	実世界データをフィード
swarma metric import <team> <csv>	メトリクスを一括インポート	バッチデータ取得
swarma metric show <team>	記録されたメトリクスを表示	パフォーマンスを確認
swarma serve --port 8282	REST APIを起動	外部統合
swarma serve --mcp	MCPサーバーを起動	Claude Code / Hermes統合
swarma run	スケジュール実行エンジンを開始	継続的な運用
swarma expert list	推論レンズを参照	エキスパートフレームワークを探索

判断: どのスクワッドテンプレートを選ぶ?

ユーザーが改善したい項目	このスクワッドを使用	AARRRステージ
オープニングラインフック	hook-lab	獲得(Acquisition)
ランディングページコピー	landing-lab	獲得
SEOランキング	seo-engine	獲得
コールドアウトリーチ応答率	cold-outbound	獲得
マルチプラットフォームコンテンツ	channel-mix	獲得
サインアップ〜バリュー提供のオンボーディング	activation-flow	アクティベーション(Activation)
価格設定とパッケージング	pricing-lab	収益化(Revenue)
チャーンとリテンション	retention-squad	リテンション(Retention)
ウイルスループと紹介	referral-engine	紹介(Referral)
市場ポジショニング	competitive-intel	--
ショートフォームビデオパイプライン	faceless-factory	獲得
広告クリエイティブテスト	ad-creative-lab	獲得
UGCコンテンツシミュレーション	ugc-factory	獲得
プログラマティックSEO	programmatic-seo	獲得
ニュースレター成長	newsletter-engine	リテンション
有料 + オーガニックループ	acquisition-squad	獲得
コミュニティ主導成長	community-engine	リテンション
AIコマース最適化	agentic-storefront	収益化

判断: 生成 vs テンプレート?

状況	アプローチ
ユーザーが具体的で明確なゴールを持っている	swarma team create --from-goal (AIにチームを設計させる)
ゴールが既存のスクワッドテンプレートに合致	テンプレートをコピーしてカスタマイズ
ユーザーが幅広く実験したい	hook-lab で開始(最も一般的)
ユーザーがどこから始めたらよいかわからない	ファネルボトルネックについて質問し、選択

---

GROWSループ(コアコンセプト)

すべての実験サイクルは5つのステップに従います:

  仮説生成     実験実行    信号観測      判定評価   プレイブック積み重ね
 hypothesis --> experiment --> signal --> verdict --> playbook
     ^                                                  |
     └──────────────────────────────────────────────────┘

ステップ	動作	コード内の場所
G -- 仮説生成	エージェントが strategy.md を読み、仮説を提案	core/cycle.py
R -- 実験実行	エージェントが仮説をアクティブにして実行、出力を生成	flow/executor.py
O -- 信号観測	別のLLMが出力をスコア(1-10、小数点強制)	core/agent.py
W -- 判定評価	5サイクル後、平均 vs ベースラインを比較。20%以上 = 保持/廃棄	core/experiment.py
S -- プレイブック積み重ね	検証済みパターンを strategy.md + プレイブックに記述	core/agent.py

主要数値:

• 判定閾値: 保持は20%改善以上、廃棄は20%以上の低下
• デフォルト min_sample_size: 判定前に5サイクル完了が必要
• スコアリング: 1-10スケール、小数点強制(7ではなく7.3)

---

セットアップガイド

プラットフォーム: Claude Code / Claude Desktop

pip install swarma
swarma init

.mcp.json に追加:

{
  "mcpServers": {
    "swarma": {
      "command": "swarma",
      "args": ["serve", "--mcp"],
      "env": { "OPENROUTER_API_KEY": "sk-or-..." }
    }
  }
}

重要: OPENROUTER_API_KEY はMCP の env ブロック内に必須です。インスタンスの .env はサブプロセスに継承されません。

プラットフォーム: Hermes(ターミナル経由)

Hermesはターミナルアクセスを持つため、swarma CLIコマンドを直接実行できます。MCPは不要です。

pip install swarma
swarma init

その後、Hermesに以下を伝えます: "run swarma cycle hook-lab --topic 'AI agents are overhyped'"

Hermesはターミナル出力を読み取り、結果に応じて動作します。構造化されたアクセスのためにMCPを追加します:

# hermes config.yaml
mcp_servers:
  swarma:
    transport: stdio
    command: swarma
    args: ["serve", "--mcp"]
    env:
      OPENROUTER_API_KEY: "sk-or-..."

プラットフォーム: OpenClaw

pip install swarma
swarma init

OpenClawのセットアップに応じて、MCPツールまたはターミナルアクセスとして設定します。

プラットフォーム: CLI(スタンドアロン)

pip install swarma
swarma init                                        # インスタンス+スターターチームを作成
swarma cycle starter --topic "why do startups fail?"   # 1つのサイクルを実行
swarma status                                      # コスト、実行、実験を確認

ソースからのインストール

git clone https://github.com/glitch-rabin/swarma.git
cd swarma && pip install -e .
swarma init

環境セットアップ

swarma init 後、APIキーを追加します:

echo "OPENROUTER_API_KEY=sk-or-..." >> ~/.swarma/instances/default/.env

キーは openrouter.ai/keys から取得します。

オプション(チーム間知識共有用):

# 3つ以上のチームを実行する場合のみ必要
echo "QMD_ENDPOINT=http://localhost:8181/mcp" >> ~/.swarma/instances/default/.env

---

オンボーディングフロー

ユーザーがswarmaをセットアップしたい場合、このシーケンスに従ってください。チームジェネレーターが最速パスです。ユーザーにエージェントを手動で設定させないでください。

ステップ1: ゴールを理解する

以下を質問します:

• 「何を改善したいですか?」(コンバージョン、エンゲージメント、アウトリーチ応答率、SEOランキングなど)
• 「オーディエンスは誰ですか?」(B2B SaaSユーザー、暗号コミュニティ、エンタープライズバイヤーなど)
• 「成功の定義は?」(より多くのサインアップ、より高いCTR、より良い返信率など)

ステップ2: インストール

pip install swarma
swarma init --yes

ステップ3: チームを生成

これが重要なステップです。テンプレートを選ぶのではなく、チームジェネレーターを使用します。

swarma team create growth-lab \
  --from-goal "optimize landing page conversion for our B2B SaaS" \
  --context "developer tools company, 500 free users, 2% conversion to paid" \
  --budget 30

ジェネレーターは:

1. チームを設計します(特定の役割を持つ2〜5個のエージェント)
2. 各役割に適したモデルを選択します
3. エージェントの指示と実験パターンを記述します
4. 実行する準備ができた最初の実験仮説を作成します

生成されたものを確認します:

swarma team show growth-lab

ステップ4: 最初のサイクルを実行

swarma cycle growth-lab

予想される出力:

Running cycle: growth-lab
  flow: researcher -> copywriter -> judge
  agents: ['researcher', 'copywriter', 'judge']

                              Cycle: growth-lab
  Agent      Model              Cost       Output Preview
  researcher sonar-pro          $0.000384  **Topic:** 52% of executives...
  copywriter qwen3.5-plus-02-15 $0.000746  [A] We sent 4,382 cold emails...
  judge      mistral-nemo       $0.000416  **Hook Variations:** A: "Did...

  duration: 43.9s | total cost: $0.001546 | agents: 3

ステップ5: さらにサイクルを実行してレビュー

swarma cycle growth-lab                    # 別のサイクルを実行
swarma cycle growth-lab --topic "specific angle"  # トピック付き
swarma status                              # 進捗を確認

5サイクル後、実験エンジンが最初の判定を発行します。ストラテジーファイルは自動的に進化します。

---

日常的な使用方法

実験を実行する

# 単一サイクル
swarma cycle hook-lab

# 特定のトピック付き
swarma cycle hook-lab --topic "AI agents are commoditizing"

# 継続的(クロンスケジュール付きチームは自動実行)
swarma run

# APIサーバー付き継続的
swarma run --port 8282

実メトリクスをフィードする

LLM自己評価は開始プロキシです。本番環境では、実世界の信号をフィードバックします:

# 単一メトリクスを記録
swarma metric log hook-lab copywriter 4.2 --metric ctr_pct

# 特定の実験にアタッチ
swarma metric log hook-lab copywriter 127 --metric impressions --exp 3

# メモを追加
swarma metric log hook-lab copywriter 5.1 --metric ctr_pct --note "from linkedin analytics"

# CSVから一括インポート
swarma metric import hook-lab metrics.csv

# 記録されたメトリクスを表示
swarma metric show hook-lab

CSV形式: agent,value,metric_name,note

copywriter,4.2,ctr_pct,week 1
copywriter,5.1,ctr_pct,week 2
researcher,7.8,relevance_score,

スクワッドテンプレートを使用する

# テンプレートをインスタンスにコピー
cp -r "$(python -c "import swarma; print(swarma.__path__[0])")/examples/hook-lab" \
  ~/.swarma/instances/default/teams/hook-lab

# またはリポジトリをクローンした場合
cp -r examples/hook-lab ~/.swarma/instances/default/teams/hook-lab

# 実行
swarma cycle hook-lab --topic "why most startups fail"

ステータスを確認する

swarma status

表示: すべてのチーム、最近の実行、コスト(今日 + 今月)、保留中の計画、キュー統計。

---

MCPツールリファレンス

MCP経由で接続すると、これら16のツールが利用可能です:

ツール	説明	パラメータ
swarma_health	swarmaが実行中かを確認	--
swarma_list_teams	すべての設定済みチームを一覧表示	--
swarma_get_team	チーム詳細(エージェント、フロー、スケジュール)を取得	team_id
swarma_list_agents	チーム内のエージェントを一覧表示	team_id
swarma_run_agent	オプションコンテキスト付きで単一エージェントを実行	team_id, agent_id, context?
swarma_run_cycle	チームの完全なサイクルを実行	team_id, topic?
swarma_status	インスタンスステータス(コスト、実行、実験)	--
swarma_costs	コスト内訳(今日、今月)	--
swarma_list_plans	保留中の実験計画を表示	team_id?
swarma_approve_plan	保留中の実験計画を承認	plan_id
swarma_reject_plan	保留中の計画を却下	plan_id, reason?
swarma_get_outputs	エージェントからの最近の出力	team_id?, agent_id?, limit?
swarma_list_tools	利用可能なエージェントツールを一覧表示	--
swarma_list_experts	エキスパート推論レンズを参照	--
swarma_get_expert	IDでエキスパート詳細を取得	expert_id
swarma_generate_team	ゴールから新しいチームを生成	name, goal, context?, budget?

一般的なMCPワークフロー

「何が起きているか?」

1. swarma_status -- 概要
2. swarma_get_outputs -- 最近のエージェント出力
3. swarma_list_plans -- 保留中の実験

「実験を実行する」

1. swarma_run_cycle でteam_idとオプショントピック付き
2. swarma_get_outputs で結果をレビュー

「新しい実験領域を開始する」

1. swarma_generate_team でゴールとコンテキスト付き
2. swarma_get_team で生成されたものをレビュー
3. swarma_run_cycle でキック

「何が機能しているか?」

1. swarma_get_outputs で最近の結果
2. チームの strategy.md を読んで検証済みパターンを確認

---

チーム設定リファレンス

チームはフォルダです。コードは不要です。

teams/my-squad/
├── team.yaml          # ゴール、フロー、スケジュール、予算
├── program.md         # チームコンテキストと制約
└── agents/
    ├── researcher.yaml
    ├── writer.yaml
    └── strategy.md    # 事前シード成長知識(自動的に進化)

team.yaml

name: my-squad
goal: find what works.
flow: "researcher -> writer"        # 順序的
# flow: "researcher -> [writer, analyst]"  # 並列
schedule: "0 8 * * 1-5"            # オプション: 平日午前8時
budget: 30                          # オプション: 月額予算(ドル)

agent.yaml

id: writer
name: Writer
instructions: |
  turn research into a post. max 200 words.
  hook in the first line. practitioner voice.
model: qwen/qwen3.5-plus-02-15     # オプション: デフォルトルーティングをオーバーライド
metric:
  name: content_quality
  target: 8.0
experiment_config:
  min_sample_size: 5
  auto_propose: true

strategy.md (自動的に進化)

シード知識で開始し、検証済みの実験ごとに成長:

### 検証済みパターン

**具体性が勝つ**
- 具体的な数字を含むフックは漠然とした主張よりも保存で2〜3倍優れている
- 「スタートアップの47%」 > 「ほとんどのスタートアップ」

### アンチパターン(廃棄済み)
- ジェネリック感動的なオープニング: ベースラインから-23%。廃棄。

### テスト対象パターン
- [ ] 一人称告白 vs 第三者ケーススタディ
- [ ] 時間アンカー(「2024年では...」) vs タイムレスフック

フローDSL

# 順序的: aが実行、出力がbに渡される
flow: "researcher -> writer"

# 並列: aが実行、その後bとcが同時実行
flow: "researcher -> [writer, analyst]"

# 混合: 順序的その後並列その後順序的
flow: "researcher -> [writer, analyst] -> judge"

---

チーム間知識(QMD)

デフォルトでは、各チームは独自の strategy.md を通じて個別に学習します。チーム間で知識を共有するには、QMDをワイヤします:

# ~/.swarma/instances/default/config.yaml
knowledge:
  engine: qmd
  qmd_endpoint: http://localhost:8181/mcp

QMD使用時: チームAが損失フレーミングが利益フレーミングに勝つことを発見、チームBはその次のサイクルでそのパターンを見る。アンチパターンも共有されます。

3つ以上のチームを実行するまでQMDは不要です。 ほとんどのユーザーはそれなしで開始します。

---

トラブルシューティング

問題	原因	解決策
「APIキーが見つかりません」	欠落している OPENROUTER_API_KEY	~/.swarma/instances/default/.env に追加
MCPサブプロセスがキーを見つけられない	インスタンス .env が継承されない	MCP設定 env ブロックでキーを渡す
「チームが見つかりません」	空のインスタンス	swarma init を実行またはスクワッドテンプレートをコピー
実験が判定を発行しない	サイクル不足	min_sample_size (デフォルト5)の完了サイクルが必要
ストラテジーファイルが進化しない	まだ判定なし	さらにサイクルを実行、swarma status を確認
swarma cycle が$0.000000コストを表示	モデルが空を返した	APIキーの有効性を確認、swarma cycle starter を試す
QMDが接続しない	QMDが実行中でない	swarma前に qmd serve で開始
Results.tsv が空	サイクル完了なし	最初に少なくとも1つのサイクルを実行

---

検証

セットアップ後、すべてが機能することを確認します:

# 1. サイクルを実行
swarma cycle starter --topic "test run"
# 予想: エージェント出力+コストを表示するテーブル

# 2. ステータスを確認
swarma status
# 予想: チームがリストされ、最近の実行が表示、コストが表示される

# 3. 実際のスクワッドを確認(インストール済みの場合)
swarma team show hook-lab
# 予想: エージェント、フロー、メトリクス付きチーム設定

3つすべてパスした場合、GROWSループは運用可能です。

---

swarmaが何でないか

swarmaでない...	代わりに使用	違い
メモリ	honcho	swarmaは会話を記憶しません。実験ループを実行します。
ワークフロー自動化	n8n、Make、Zapier	それらはアプリを接続します。swarmaは仮説を実行し、結果から学習します。
プロンプトライブラリ	agency-agents	swarmaはフィードバックを通じてエージェントに何が機能するかを教えます。テンプレートが入力、プレイブックが出力。
エージェントオーケストレーション	CrewAI、AutoGen、LangGraph	それらはパイプラインを実行します。swarmaはパイプラインを改善させるGROWSループを追加します。
ホスト型サービス	--	セルフホスト型。データはマシンに留まります。