# Flag Experiment

> Add an experiment-ref rule to a GrowthBook feature flag to run an A/B test through that flag. Use when the user says "run an experiment through this flag", "add an A/B test to flag X", "link experiment Y to this flag", "set up variations on this flag for an experiment", "add an experiment-ref rule", or "wire up this experiment to the flag". For launching a full new experiment end-to-end, use expe…

- **Type:** Skill
- **Install:** `agentstack add skill-growthbook-skills-flag-experiment`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [growthbook](https://agentstack.voostack.com/s/growthbook)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [growthbook](https://github.com/growthbook)
- **Source:** https://github.com/growthbook/skills/tree/main/skills/flag-experiment

## Install

```sh
agentstack add skill-growthbook-skills-flag-experiment
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# flag-experiment

Add an `experiment-ref` rule to a GrowthBook feature flag. This links a flag rule to a separately-managed GrowthBook experiment object — the experiment is the source of truth for variations, metrics, and analysis.

All API calls go through the bundled helper: `${CLAUDE_PLUGIN_ROOT}/scripts/gb-call`. It needs `GB_API_KEY` set in env or written to `~/.config/growthbook/.env` by `/growthbook:setup`.

## Workflow

### Path A — Add an experiment-ref rule

Use this when the user has an existing GrowthBook experiment or wants to launch one through a flag.

**1. Fetch the flag and confirm the experiment exists:**

```bash
gb-call GET /api/v2/features/
```

Capture `valueType` — you'll need it to map variation values correctly.

```bash
gb-call GET /api/v1/experiments/
```

Capture the experiment's `variations` array. Each variation has an `id` (e.g., `var_abc123`) and a `name`. You'll need these to wire up the rule.

If the user doesn't have an experiment yet, route to `experiment-launch` — it handles experiment creation AND flag wiring end-to-end. Importantly, if a flag already exists, `experiment-launch` will detect it (via a 409 on create, then the reuse path) and wire the experiment to the existing flag rather than creating a new one. Tell the user: "experiment-launch will pick up your existing flag — just give it the same flag key."

**2. Map variation values:**

For each experiment variation, confirm what flag value should be served. The flag's `valueType` determines the format:
- `boolean`: typically `"true"` for treatment, `"false"` for control
- `string` / `number` / `json`: ask the user for each variation's value

**3. Build the payload:**

```json
{
  "rule": {
    "type": "experiment-ref",
    "experimentId": "",
    "variations": [
      { "variationId": "", "value": "false" },
      { "variationId": "", "value": "true" }
    ],
    "description": "",
    "enabled": true,
    "allEnvironments": false,
    "environments": [""]
  }
}
```

Variation order in the `variations` array must match the experiment's variation order. If the user omits all `variationId` fields, the server auto-fills them from the experiment — but explicitly providing them is safer and avoids silent mismatches.

**4. Post the rule:**

```bash
echo '' | gb-call POST /api/v2/features//revisions/new/rules -
```

Capture the returned `version`. Hand off to flag-publish.

### Path B — Edit an existing experiment-ref rule's targeting

The server allows patching `enabled`, `condition`, `savedGroups`, `prerequisites`, scope (`allEnvironments`/`environments`), and `description` on an experiment-ref rule. Use flag-targeting for this — it has the full conditions decision tree and the warn-and-confirm guardrails for the sensitive fields.

**Do not edit `experimentId` or `variations` on an experiment-ref rule directly.** The experiment is the source of truth. Changing these fields on the flag rule alone causes silent drift between the flag and the experiment. If the user needs to change the experiment, route to experiment-launch or the GrowthBook UI.

## Guardrails

- **Draft version threading.** If a version number is already in context from a previous write skill in this session, use it explicitly instead of `new`. Fall back to `new` when starting fresh.
- **`variations` order must match the experiment's variation order.** If the order is wrong, variation assignments will be mismatched — the control users will see the treatment value and vice versa. Always confirm variation order by reading the experiment before building the payload.
- **Auto-fill of `variationId` is available but risky.** If all `variationId` fields are omitted, the server fills them from the experiment. Use this only when the experiment has exactly the same number of variations as the values the user specified — otherwise the server may silently mismatch.
- **Editing `experimentId` or `variations` on an existing experiment-ref rule requires warn-and-confirm.** These fields are API-allowed but cause flag/experiment drift. Always surface the risk and require explicit confirmation before patching.
- **Server-rejected patches on experiment-ref rules:** `value`, `coverage`, `controlValue`. These are attributes of the experiment, not the flag rule. Halt early if the user tries to set them.
- **Experiment must be in the same datasource.** If the experiment uses a datasource that doesn't match the org's default, metric lookups may fail. Verify datasource consistency if the user is specifying metrics on an inline rule.
- **One experiment-ref rule per experiment per flag** is the standard convention. Multiple rules pointing at the same experiment create overlapping bucketing and corrupt analysis.

## Endpoints used

- `GET /api/v2/features/:id` — fetch flag state, valueType, and current rules
- `GET /api/v1/experiments/:id` — fetch experiment and its variations
- `POST /api/v2/features/:id/revisions/new/rules` — add the experiment-ref rule

## Handoffs

- `flag-search` — to find a flag ID when you only have a name or description
- `experiment-launch` — to create a new experiment and wire it to a flag end-to-end
- `flag-targeting` — to edit the targeting conditions, scope, or saved groups on an existing experiment-ref rule
- `flag-rules` — to reorder or delete experiment rules
- `experiment-stop` — to stop the experiment; after stopping, use flag-rules to clean up the experiment-ref rule
- `flag-publish` — to publish the draft

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [growthbook](https://github.com/growthbook)
- **Source:** [growthbook/skills](https://github.com/growthbook/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-growthbook-skills-flag-experiment
- Seller: https://agentstack.voostack.com/s/growthbook
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.