Skill: glitch-rabin/swarma (version 1.0.0)

--- name: swarma description: "Agent teams that run growth experiments and build their own playbook. GROWS loop: generate hypothesis, run experiment, observe signal, weigh verdict, stack playbook. 18 pre-built squads covering the full AARRR funnel. Your agents stop guessing and start learning." version: 0.2.0 license: MIT compatibility: Python 3.11+, pip, terminal access metadata: repository: https://github.com/glitch-rabin/swarma website: https://swarma.dev hook: "a swarm runs 50 experiments while a human team runs 2" keywords: [growth experiments, A/B testing, agent teams, swarm intelligence, AARRR funnel, playbook, learning agents, experiment loop, strategy evolution, self-improving] hermes: tags: [experiments, learning, growth, agents, teams, swarms, pirate-funnels, AARRR, playbook, self-improving, A/B-testing] category: productivity requires_toolsets: [terminal] required_environment_variables: - name: OPENROUTER_API_KEY prompt: "OpenRouter API key for LLM calls" help: https://openrouter.ai/keys required_for: running agent cycles --- # swarma -- growth experiment loop for agent teams ## When to Use This Skill Use swarma when the user wants to: - Run growth experiments (hooks, landing pages, outreach, pricing, activation, retention) - Build agent teams that **learn and improve** through A/B testing, not just execute once - Get a validated playbook of what actually works for their specific audience/product - Test ideas at scale (50+ experiments/week instead of 2-5) - Replace "we tried that, it didn't work" with logged, analyzed, searchable experiment data **Trigger phrases**: "test what works", "optimize my funnel", "find the best hooks", "run experiments", "A/B test", "what's working", "build a playbook", "growth experiments", "improve conversion" **Do NOT use when**: user wants workflow automation (use n8n/Make), conversation memory (use honcho), or one-shot agent pipelines (use CrewAI/AutoGen). swarma is specifically for experiment loops that improve over time. --- ## Quick Reference ### Commands at a Glance | Command | What it does | When to use | |---------|-------------|-------------| | `swarma init` | Create instance + starter team | First-time setup | | `swarma cycle <team>` | Run one experiment cycle | Testing, manual runs | | `swarma cycle <team> --topic "..."` | Run cycle with a specific topic | Ad-hoc experiments | | `swarma team create <name> --from-goal "..."` | Generate team from a goal | Starting a new experiment area | | `swarma team show <name>` | Inspect a team's config | Reviewing what was generated | | `swarma team list` | Show all teams | Overview | | `swarma status` | Costs, recent runs, experiments | Health check | | `swarma metric log <team> <agent> <value>` | Log external metric | Feeding real-world data | | `swarma metric import <team> <csv>` | Bulk import metrics | Batch data ingestion | | `swarma metric show <team>` | View logged metrics | Reviewing performance | | `swarma serve --port 8282` | Start REST API | External integrations | | `swarma serve --mcp` | Start MCP server | Claude Code / Hermes integration | | `swarma run` | Start scheduled engine | Continuous operation | | `swarma expert list` | Browse reasoning lenses | Exploring expert frameworks | ### Decision: Which Squad Template? | User wants to improve... | Use this squad | AARRR stage | |--------------------------|---------------|-------------| | Opening lines / hooks | `hook-lab` | Acquisition | | Landing page copy | `landing-lab` | Acquisition | | SEO rankings | `seo-engine` | Acquisition | | Cold outreach response rates | `cold-outbound` | Acquisition | | Multi-platform content | `channel-mix` | Acquisition | | Signup-to-value onboarding | `activation-flow` | Activation | | Pricing and packaging | `pricing-lab` | Revenue | | Churn and retention | `retention-squad` | Retention | | Viral loops and referrals | `referral-engine` | Referral | | Market positioning | `competitive-intel` | -- | | Short-form video pipeline | `faceless-factory` | Acquisition | | Ad creative testing | `ad-creative-lab` | Acquisition | | UGC content simulation | `ugc-factory` | Acquisition | | Programmatic SEO | `programmatic-seo` | Acquisition | | Newsletter growth | `newsletter-engine` | Retention | | Paid + organic loops | `acquisition-squad` | Acquisition | | Community-led growth | `community-engine` | Retention | | AI commerce optimization | `agentic-storefront` | Revenue | ### Decision: Generate vs Template? | Situation | Approach | |-----------|----------| | User has a specific, well-defined goal | `swarma team create --from-goal` (let AI design the team) | | Goal matches an existing squad template | Copy template, then customize | | User wants to experiment broadly | Start with `hook-lab` (most general) | | User doesn't know where to start | Ask about their funnel bottleneck, then pick | --- ## The GROWS Loop (Core Concept) Every experiment cycle follows five steps: ``` Generate Run Observe Weigh Stack hypothesis --> experiment --> signal --> verdict --> playbook ^ | └──────────────────────────────────────────────────┘ ``` | Step | What happens | Where in code | |------|-------------|---------------| | **G -- Generate** | Agent reads `strategy.md`, proposes a hypothesis | `core/cycle.py` | | **R -- Run** | Agent executes with hypothesis active, produces output | `flow/executor.py` | | **O -- Observe** | Separate cheap LLM scores output (1-10, forced decimals) | `core/agent.py` | | **W -- Weigh** | After 5 cycles, compare average vs baseline. >20% = keep/discard | `core/experiment.py` | | **S -- Stack** | Validated patterns written to `strategy.md` + playbook | `core/agent.py` | **Key numbers:** - Verdict threshold: 20% improvement to keep, 20% decline to discard - Default `min_sample_size`: 5 cycles before verdict - Scoring: 1-10 scale with forced decimals (7.3, not 7) --- ## Setup Guide ### Platform: Claude Code / Claude Desktop ```bash pip install swarma swarma init ``` Add to `.mcp.json`: ```json { "mcpServers": { "swarma": { "command": "swarma", "args": ["serve", "--mcp"], "env": { "OPENROUTER_API_KEY": "sk-or-..." } } } } ``` **Important**: `OPENROUTER_API_KEY` must be in the MCP `env` block. The instance `.env` is not inherited by subprocesses. ### Platform: Hermes (via terminal) Hermes has terminal access -- it can run swarma CLI commands directly. No MCP required. ```bash pip install swarma swarma init ``` Then tell Hermes: *"run `swarma cycle hook-lab --topic 'AI agents are overhyped'`"* Hermes reads terminal output and acts on results. For structured access, add MCP: ```yaml # hermes config.yaml mcp_servers: swarma: transport: stdio command: swarma args: ["serve", "--mcp"] env: OPENROUTER_API_KEY: "sk-or-..." ``` ### Platform: OpenClaw ```bash pip install swarma swarma init ``` Configure as MCP tool or use terminal access depending on your OpenClaw setup. ### Platform: CLI (standalone) ```bash pip install swarma swarma init # creates instance + starter team swarma cycle starter --topic "why do startups fail?" # run one cycle swarma status # check costs, runs, experiments ``` ### From source ```bash git clone https://github.com/glitch-rabin/swarma.git cd swarma && pip install -e . swarma init ``` ### Environment setup After `swarma init`, add your API key: ```bash echo "OPENROUTER_API_KEY=sk-or-..." >> ~/.swarma/instances/default/.env ``` Get a key at [openrouter.ai/keys](https://openrouter.ai/keys). Optional (for cross-team knowledge): ```bash # Only needed when running 3+ teams echo "QMD_ENDPOINT=http://localhost:8181/mcp" >> ~/.swarma/instances/default/.env ``` --- ## Onboarding Flow When a user wants to set up swarma, follow this sequence. The team generator is the fastest path -- don't make users configure agents manually. ### Step 1: Understand the goal Ask: - "What do you want to improve?" (conversion, engagement, outreach response rate, SEO rankings, etc.) - "Who is your audience?" (B2B SaaS users, crypto community, enterprise buyers, etc.) - "What does success look like?" (more signups, higher CTR, better reply rates, etc.) ### Step 2: Install ```bash pip install swarma swarma init --yes ``` ### Step 3: Generate the team This is the key step. Use the team generator instead of picking templates. ```bash 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 ``` The generator: 1. Designs the team (2-5 agents with specific roles) 2. Picks models that fit each role 3. Writes agent instructions and experiment patterns 4. Creates a first experiment hypothesis ready to run Review what it generated: ```bash swarma team show growth-lab ``` ### Step 4: Run the first cycle ```bash swarma cycle growth-lab ``` Expected output: ``` 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 ``` ### Step 5: Run more cycles and review ```bash swarma cycle growth-lab # run another cycle swarma cycle growth-lab --topic "specific angle" # with a topic swarma status # check progress ``` After 5 cycles, the experiment engine issues its first verdict. The strategy file evolves automatically. --- ## Day-to-Day Usage ### Running experiments ```bash # Single cycle swarma cycle hook-lab # With a specific topic swarma cycle hook-lab --topic "AI agents are commoditizing" # Continuous (teams with cron schedules run automatically) swarma run # Continuous with API server swarma run --port 8282 ``` ### Feeding real metrics LLM self-eval is a starting proxy. For production, feed back real-world signals: ```bash # Log a single metric swarma metric log hook-lab copywriter 4.2 --metric ctr_pct # Attach to a specific experiment swarma metric log hook-lab copywriter 127 --metric impressions --exp 3 # Add a note swarma metric log hook-lab copywriter 5.1 --metric ctr_pct --note "from linkedin analytics" # Bulk import from CSV swarma metric import hook-lab metrics.csv # View logged metrics swarma metric show hook-lab ``` CSV format: `agent,value,metric_name,note` ```csv copywriter,4.2,ctr_pct,week 1 copywriter,5.1,ctr_pct,week 2 researcher,7.8,relevance_score, ``` ### Using squad templates ```bash # Copy a template to your instance cp -r "$(python -c "import swarma; print(swarma.__path__[0])")/examples/hook-lab" \ ~/.swarma/instances/default/teams/hook-lab # Or if you cloned the repo cp -r examples/hook-lab ~/.swarma/instances/default/teams/hook-lab # Run it swarma cycle hook-lab --topic "why most startups fail" ``` ### Checking status ```bash swarma status ``` Shows: all teams, recent runs, costs (today + this month), pending plans, queue stats. --- ## MCP Tools Reference When connected via MCP, these 16 tools are available: | Tool | Description | Parameters | |------|-------------|------------| | `swarma_health` | Check if swarma is running | -- | | `swarma_list_teams` | List all configured teams | -- | | `swarma_get_team` | Get team details (agents, flow, schedule) | `team_id` | | `swarma_list_agents` | List agents in a team | `team_id` | | `swarma_run_agent` | Run a single agent with optional context | `team_id`, `agent_id`, `context?` | | `swarma_run_cycle` | Run a full cycle for a team | `team_id`, `topic?` | | `swarma_status` | Instance status (costs, runs, experiments) | -- | | `swarma_costs` | Cost breakdown (today, this month) | -- | | `swarma_list_plans` | Show pending experiment plans | `team_id?` | | `swarma_approve_plan` | Approve a pending experiment plan | `plan_id` | | `swarma_reject_plan` | Reject a pending plan | `plan_id`, `reason?` | | `swarma_get_outputs` | Recent outputs from agents | `team_id?`, `agent_id?`, `limit?` | | `swarma_list_tools` | List available agent tools | -- | | `swarma_list_experts` | Browse expert reasoning lenses | -- | | `swarma_get_expert` | Get expert details by ID | `expert_id` | | `swarma_generate_team` | Generate a new team from a goal | `name`, `goal`, `context?`, `budget?` | ### Common MCP Workflows **"What's been happening?"** 1. `swarma_status` -- overview 2. `swarma_get_outputs` -- recent agent outputs 3. `swarma_list_plans` -- pending experiments **"Run an experiment"** 1. `swarma_run_cycle` with team_id and optional topic 2. `swarma_get_outputs` to review results **"Start a new experiment area"** 1. `swarma_generate_team` with goal and context 2. `swarma_get_team` to review what was generated 3. `swarma_run_cycle` to kick it off **"What's working?"** 1. `swarma_get_outputs` for recent results 2. Read the team's `strategy.md` for validated patterns --- ## Team Configuration Reference A team is a folder. No code required. ``` teams/my-squad/ ├── team.yaml # goal, flow, schedule, budget ├── program.md # team context and constraints └── agents/ ├── researcher.yaml ├── writer.yaml └── strategy.md # pre-seeded growth knowledge (evolves automatically) ``` ### team.yaml ```yaml name: my-squad goal: find what works. flow: "researcher -> writer" # sequential # flow: "researcher -> [writer, analyst]" # parallel schedule: "0 8 * * 1-5" # optional: weekdays at 8am budget: 30 # optional: monthly budget in $ ``` ### agent.yaml ```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 # optional: override default routing metric: name: content_quality target: 8.0 experiment_config: min_sample_size: 5 auto_propose: true ``` ### strategy.md (evolves automatically) Starts with seed knowledge, grows with every validated experiment: ```markdown ### Validated Patterns **Specificity wins** - Hooks with specific numbers outperform vague claims by 2-3x on saves - "47% of startups" > "most startups" ### Anti-patterns (Discarded) - Generic inspirational openings: -23% vs baseline. Discard. ### Patterns to Test - [ ] First-person confession vs third-person case study - [ ] Time-anchored ("In 2024...") vs timeless hooks ``` ### Flow DSL ```yaml # Sequential: a runs, output passes to b flow: "researcher -> writer" # Parallel: a runs, then b and c run concurrently flow: "researcher -> [writer, analyst]" # Mixed: sequential then parallel then sequential flow: "researcher -> [writer, analyst] -> judge" ``` --- ## Cross-Team Knowledge (QMD) By default, each team learns individually via its own `strategy.md`. To share knowledge across teams, wire in QMD: ```yaml # ~/.swarma/instances/default/config.yaml knowledge: engine: qmd qmd_endpoint: http://localhost:8181/mcp ``` With QMD: team A discovers loss framing beats gain framing, team B sees that pattern in its next cycle. Anti-patterns are shared too. **You don't need QMD** until running 3+ teams. Most users start without it. --- ## Troubleshooting | Problem | Cause | Fix | |---------|-------|-----| | "No API key found" | Missing `OPENROUTER_API_KEY` | Add to `~/.swarma/instances/default/.env` | | MCP subprocess can't find key | Instance `.env` not inherited | Pass key in MCP config `env` block | | "No teams found" | Empty instance | Run `swarma init` or copy a squad template | | Experiments not issuing verdicts | Not enough cycles | Need `min_sample_size` (default 5) completed cycles | | Strategy file not evolving | No verdict yet | Run more cycles, check `swarma status` | | `swarma cycle` shows $0.000000 cost | Model returned empty | Check API key validity, try `swarma cycle starter` | | QMD not connecting | QMD not running | Start with `qmd serve` before swarma | | Results.tsv empty | No cycles completed | Run at least one cycle first | --- ## Verification After setup, verify everything works: ```bash # 1. Run a cycle swarma cycle starter --topic "test run" # Expected: table showing agent outputs + costs # 2. Check status swarma status # Expected: teams listed, recent run shown, costs displayed # 3. Check a real squad (if installed) swarma team show hook-lab # Expected: team config with agents, flow, metrics ``` If all three pass, the GROWS loop is operational. --- ## What swarma Is Not | swarma is not... | Use this instead | The difference | |-------------------|-----------------|----------------| | **memory** | honcho | swarma doesn't remember conversations. it runs experiment loops. | | **workflow automation** | n8n, Make, Zapier | those connect apps. swarma runs hypotheses and learns from results. | | **a prompt library** | agency-agents | swarma teaches agents what works through feedback. templates go in, playbooks come out. | | **agent orchestration** | CrewAI, AutoGen, LangGraph | those run pipelines. swarma adds the GROWS loop that makes pipelines improve. | | **a hosted service** | -- | self-hosted. your data stays on your machine. |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)