# Flag Search

> Search, list, and audit GrowthBook feature flags. Use when the user asks "what flags do we have", "find flags tagged payments", "list flags in project X", "which flags are stale", "find flags owned by bryce@company.com", "show me all disabled flags in production", "audit our flags", "find flags with no rules", or "what can we clean up". Read-only — for actually removing flags, use flag-cleanup. F…

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

## Install

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

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

## About

# flag-search

Search, list, and audit GrowthBook feature flags. Three jobs share this skill: broad inventory listing, filtered search by criteria, and stale-flag auditing for cleanup candidates.

Read-only — this skill never writes.

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

Pick the path that matches the user's request.

### Path A — Full inventory ("what flags do we have?")

Start with the lightweight key list:

```bash
gb-call GET /api/v2/feature-keys
```

Returns every flag ID as a string array — no pagination, cheapest call. Surface the count and group by prefix if patterns emerge (`checkout-*`, `payments-*`, `infra-*`).

If the user wants details on the full set or a subset, paginate:

```bash
gb-call GET '/api/v2/features?limit=100'
gb-call GET '/api/v2/features?limit=100&offset=100'   # next page
```

100 per page is the cap. Loop with `offset` until the returned count is below 100.

Group output by project if the org uses projects. Flag keys that look like orphaned test/debug entries (`test-`, `temp-`, `debug-`, `delete-me`).

### Path B — Search by criteria

Use the `/api/v2/features` list endpoint with query params to narrow results. Available filters:

```bash
# By project:
gb-call GET '/api/v2/features?projectId='

# By tag (exact match, single tag):
gb-call GET '/api/v2/features?tag='
```

For filters not supported by the API (owner, environment state, value type), fetch the full set and filter client-side from the response fields.

Common searches:

| Request | Approach |
| --- | --- |
| "Flags owned by X" | Fetch all, filter on `owner.email` |
| "Boolean flags" | Fetch all, filter on `valueType === "boolean"` |
| "Flags enabled in production" | Fetch all, filter on `environmentSettings.production.enabled === true` |
| "Flags with no rules" | Fetch all, filter on `rules.length === 0` |
| "Flags tagged payments" | `GET /api/v2/features?tag=payments` |
| "Flags in project Y" | Resolve project name → ID, then `GET /api/v2/features?projectId=` |

When filtering client-side on a large org, paginate through the full set first, then filter.

### Path C — Stale flag audit ("what can we clean up?")

GrowthBook defines a flag as stale when **both** conditions hold: (a) no updates for two weeks, and (b) either no active environments or all rules route 100% of traffic to a single variation.

**Step C-1: Get the flag IDs to audit.**

Either from the user's explicit list, from a codebase grep, or by pulling all IDs:

```bash
gb-call GET /api/v2/feature-keys
```

**Step C-2: Run the staleness check.**

The endpoint requires an explicit ID list (no "find all stale" shortcut):

```bash
gb-call GET '/api/v2/stale-features?ids=flag-a,flag-b,flag-c'
```

**Step C-3: Interpret the results.**

Each flag gets a `staleReason`:

| `staleReason` | Meaning | Action |
| --- | --- | --- |
| `rules-one-sided` | All rules route 100% of traffic to a single value — looks like a shipped feature | Safe to clean up — inline the winning value |
| `no-rules` | Flag has no rules at all | Safe to remove if `defaultValue` is already inlined |
| `toggled-off` | Disabled in all environments | Safe to remove if no longer needed |
| `abandoned-draft` | Has a draft open with no recent activity | Check the draft; discard or continue |
| `never-stale` | Explicitly excluded from stale detection | Skip — permanent intentional flag (kill switch, ops toggle) |
| `recently-updated` | Updated within the last two weeks | Not stale yet — revisit later |
| `active-draft` | Has an active draft revision in progress | Someone is working on it — leave alone |
| `has-dependents` | Other flags list this flag as a prerequisite | Cannot remove safely without updating dependents — use flag-graph first |
| `active-experiment` | Linked to a running experiment | Stop the experiment first via experiment-stop |
| `has-rules` | Has active rules that aren't one-sided | Still in use |

**Step C-4: Present the report.**

Group by recommendation:
1. **Cleanup candidates** (`launched`, `unused`, `abandoned`) — with suggested replacement values
2. **Excluded** (`never-stale`) — list separately, don't include in cleanup recommendations
3. **Still active** — skip

Surface the `defaultValue` and winning rule values for candidates — the user needs these to inline before removing.

Do not delete anything. Hand off to flag-cleanup for actual removal.

## Guardrails

- **`/stale-features` requires explicit IDs.** No "find all stale" endpoint exists. Fetch IDs from `/feature-keys` first if the user doesn't provide them.
- **`/feature-keys` is unpaginated; `/features` is paginated (100/page).** Use `/feature-keys` for full ID inventory; `/features` for detail queries.
- **`neverStale: true` flags are excluded from cleanup recommendations.** They appear as `staleReason: "never-stale"` — surface them separately but never suggest removing them.
- **Don't infer staleness yourself.** Use `/stale-features` for the canonical determination; it encodes GrowthBook's own rules and surfaces replacement values you can't compute locally.
- **Client-side filters on large orgs can be slow.** Rate limit is 60 rpm. If paginating through hundreds of flags, surface progress updates.
- **v2 rules are flat.** Under v2, the `rules` array is top-level on the flag object with `allEnvironments`/`environments` scope per rule — not nested under each environment as in v1.
- **Read-only.** Never POST, PUT, PATCH, or DELETE from this skill. Route to flag-cleanup for removals.

## Endpoints used

- `GET /api/v2/feature-keys` — full ID list, no pagination cap
- `GET /api/v2/features` — paginated list with full configuration (`limit`, `offset`, `projectId`, `tag` filters)
- `GET /api/v2/features/:id` — full configuration for one flag
- `GET /api/v2/stale-features?ids=a,b,c` — staleness audit (requires explicit `ids`)
- `GET /api/v1/projects` — resolve project name to ID for project-scoped searches

## Handoffs

- `flag-graph` — to trace dependencies for a specific flag (what does it depend on, what depends on it)
- `flag-cleanup` — to archive or delete cleanup candidates found in Path C
- `flag-targeting`, `flag-rules` — to make changes after identifying which flag needs updating
- `flag-revisions` — to check for open drafts on flags found in the search

## 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-search
- 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%.