From 02393bfab483aceb5209360204ff9a2a6d135a88 Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 2 Sep 2026 16:01:20 +0200 Subject: [PATCH 01/12] Trim duplicated vercel flags CLI docs from flags-sdk skill Point agents at --help for syntax and keep lifecycle/safety guidance that skills must own (EXP-3411). --- skills/flags-sdk/SKILL.md | 6 +- skills/flags-sdk/references/providers.md | 82 ++++-------------------- 2 files changed, 17 insertions(+), 71 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 686454d7..163926c6 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -4,13 +4,15 @@ description: > Set up and use feature flags and A/B tests with the Flags SDK (`flags` npm package) and Vercel Flags. Use when installing or configuring the SDK, adding a flag, wiring `vercelAdapter` / FLAGS env vars, declaring flags with `flag()`, using `vercel flags` CLI (create, list, enable, disable, inspect, - archive, rm, sdk-keys), setting up providers/adapters (Vercel, Statsig, LaunchDarkly, PostHog, + archive, rm, sdk-keys, set, split, rollout, segments, update, open, prepare, override), + setting up providers/adapters (Vercel, Statsig, LaunchDarkly, PostHog, GrowthBook, Global Config, OpenFeature, Split, Flagsmith, Reflag, Optimizely, or custom), precompute, `identify`/`dedupe`, Flags Explorer/Toolbar, Next.js or SvelteKit, custom adapters, or encrypting/decrypting flag values. Triggers: set up feature flags, install Flags SDK, add a feature flag, feature flags, A/B testing, experimentation, flags SDK, flag adapters, precompute, Flags Explorer, feature gates, flag overrides, Vercel Flags, vercel flags CLI, vercel flags create/list/enable/disable, + vercel flags set/split/rollout/segments/update/open/prepare/override, `flags/next`, `flags/sveltekit`, `flags/react`, `@flags-sdk/*`. --- @@ -147,7 +149,7 @@ Vercel Flags is Vercel's feature flags platform. You create and manage flags fro To install the SDK, follow [Set up the SDK](#set-up-the-sdk). To create a flag end-to-end, follow [Create a flag](#create-a-flag). -For the full Vercel provider reference — user targeting, `vercel flags` CLI subcommands, custom adapter configuration, and Flags Explorer setup — see [references/providers.md](references/providers.md#vercel). +For the full Vercel provider reference — user targeting, `vercel flags` lifecycle guidance, custom adapter configuration, and Flags Explorer setup — see [references/providers.md](references/providers.md#vercel). Run `vercel flags --help` for the current CLI reference. ## Declaring flags diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index cf5dbc27..ebfbf687 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -114,80 +114,24 @@ export const exampleFlag = flag({ Manage Vercel Flags from the terminal. Requires the [Vercel CLI](https://vercel.com/docs/cli) and a linked project. -> **Prerequisite**: The Vercel CLI must be installed (`pnpm i -g vercel`) and the project must be linked (`vercel link` — check for a `.vercel` directory). For authentication issues, read and follow the `vercel-cli` skill. +> **Prerequisite**: The Vercel CLI must be installed (`pnpm i -g vercel`) and the project must be linked (`vercel link` — check for a `.vercel` directory). For authentication or linking issues, follow the `vercel-cli` skill if available; otherwise suggest `npx skills add vercel/vercel@vercel-cli` (do not auto-install). -#### Subcommands +For the current subcommand list and options, run `vercel flags --help` or `vercel flags --help`. Do not rely on skill tables for CLI syntax — `--help` is the source of truth. For CLI-wide contracts and playbooks, see the `vercel-cli` skill. -| Subcommand | Description | -| ------------ | ----------------------------------------------------- | -| `list` | List all flags in the project | -| `create` | Create a new flag | -| `inspect` | Show details, status, and targeting rules of a flag | -| `enable` | Enable a boolean flag for a specific environment | -| `disable` | Disable a boolean flag for a specific environment | -| `archive` | Archive a flag (required before deleting) | -| `rm` | Delete an archived flag | -| `sdk-keys` | Manage SDK keys (subcommands: `ls`, `add`, `rm`) | +#### Lifecycle and safety (Flags SDK) -#### Create and toggle a flag +Keep these judgments in the skill; they are not covered by `--help`: -```bash -# Create a boolean flag with a description -vercel flags create my-feature --kind boolean --description "New onboarding flow" - -# Enable in development first -vercel flags enable my-feature --environment development - -# Promote to production -vercel flags enable my-feature --environment production - -# Disable in production -vercel flags disable my-feature --environment production - -# Change string variant in production -vercel flags set my-feature -e production --variant my-variant -``` - -`enable` and `disable` only work with boolean flags. For changing the state of other flag types, use the `set` command. Use the vercel-cli skill for full reference. - - -#### Inspect and list flags - -```bash -# Show details of a specific flag (status, environments, targeting rules) -vercel flags inspect my-feature - -# List all flags in the project -vercel flags list -``` - -#### Archive and delete a flag - -A flag must be archived before it can be deleted: - -```bash -vercel flags archive my-feature -vercel flags rm my-feature -``` - -#### Manage SDK keys - -SDK keys connect your application to Vercel Flags. The `FLAGS` environment variable contains an SDK key. - -```bash -# List SDK keys for the project -vercel flags sdk-keys ls - -# Create a new SDK key -vercel flags sdk-keys add - -# Remove an SDK key -vercel flags sdk-keys rm -``` - -These examples cover common flag operations. For the full `vercel flags` reference and other Vercel CLI commands, see the `vercel-cli` skill. If it isn't installed, suggest the user install it with `npx skills add vercel/vercel@vercel-cli`. +- **Link first**: Always confirm `.vercel/` (or run `vercel link`) before any `vercel flags` command. +- **Create → pull env**: After creating a flag, run `vercel env pull` so `FLAGS` / `FLAGS_SECRET` land in `.env.local`. Without them, `vercelAdapter` cannot evaluate. +- **Key match**: The CLI flag key must match the `key` passed to `flag()`. +- **Promote carefully**: Prefer development → preview → production. Do not enable in production until the code path that reads the flag is deployed. +- **Boolean vs other kinds**: `enable` / `disable` apply to boolean flags. For other kinds, use `set` (see `--help` for options). +- **Archive before delete**: Archive first; only `rm` when nothing still references the flag. Prefer archive over delete until you are sure. +- **SDK keys**: `FLAGS` holds an SDK key. Manage keys with `vercel flags sdk-keys` (see `--help`). +- **Rollouts / splits / segments / overrides**: Use the matching CLI subcommands when needed; confirm syntax with `--help` and escalate beyond the CLI (dashboard / support) when targeting rules are unclear. -Full CLI reference: https://vercel.com/docs/cli/flags +Docs: https://vercel.com/docs/cli/flags --- From acf73c3ba18e46ff63b66bc97ec602329c66f372 Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 2 Sep 2026 16:04:06 +0200 Subject: [PATCH 02/12] Shrink flags-sdk skill description under 1024 chars Drop duplicate CLI trigger phrases; keep subcommand names once for activation. --- skills/flags-sdk/SKILL.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 163926c6..0f9a447c 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -5,15 +5,12 @@ description: > Use when installing or configuring the SDK, adding a flag, wiring `vercelAdapter` / FLAGS env vars, declaring flags with `flag()`, using `vercel flags` CLI (create, list, enable, disable, inspect, archive, rm, sdk-keys, set, split, rollout, segments, update, open, prepare, override), - setting up providers/adapters (Vercel, Statsig, LaunchDarkly, PostHog, - GrowthBook, Global Config, OpenFeature, Split, Flagsmith, Reflag, Optimizely, or custom), - precompute, `identify`/`dedupe`, Flags Explorer/Toolbar, Next.js or SvelteKit, custom adapters, - or encrypting/decrypting flag values. - Triggers: set up feature flags, install Flags SDK, add a feature flag, feature flags, - A/B testing, experimentation, flags SDK, flag adapters, precompute, Flags Explorer, - feature gates, flag overrides, Vercel Flags, vercel flags CLI, vercel flags create/list/enable/disable, - vercel flags set/split/rollout/segments/update/open/prepare/override, - `flags/next`, `flags/sveltekit`, `flags/react`, `@flags-sdk/*`. + setting up providers/adapters (Vercel, Statsig, LaunchDarkly, PostHog, GrowthBook, Global Config, + OpenFeature, Split, Flagsmith, Reflag, Optimizely, or custom), precompute, `identify`/`dedupe`, + Flags Explorer/Toolbar, Next.js or SvelteKit, custom adapters, or encrypting/decrypting flag values. + Triggers: set up feature flags, install Flags SDK, add a feature flag, feature flags, A/B testing, + experimentation, flags SDK, flag adapters, precompute, Flags Explorer, feature gates, flag overrides, + Vercel Flags, vercel flags CLI, `flags/next`, `flags/sveltekit`, `flags/react`, `@flags-sdk/*`. --- # Set up and use the Flags SDK From 15603dde0ccebbc67a793a3a49511b9f211e2414 Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 2 Sep 2026 16:22:33 +0200 Subject: [PATCH 03/12] Drop stale skill-tables wording from CLI pointer --- skills/flags-sdk/references/providers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index ebfbf687..c368740d 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -116,7 +116,7 @@ Manage Vercel Flags from the terminal. Requires the [Vercel CLI](https://vercel. > **Prerequisite**: The Vercel CLI must be installed (`pnpm i -g vercel`) and the project must be linked (`vercel link` — check for a `.vercel` directory). For authentication or linking issues, follow the `vercel-cli` skill if available; otherwise suggest `npx skills add vercel/vercel@vercel-cli` (do not auto-install). -For the current subcommand list and options, run `vercel flags --help` or `vercel flags --help`. Do not rely on skill tables for CLI syntax — `--help` is the source of truth. For CLI-wide contracts and playbooks, see the `vercel-cli` skill. +For the current subcommand list and options, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts and playbooks, see the `vercel-cli` skill. #### Lifecycle and safety (Flags SDK) From 620300e72af633e053b88315c572c86b9b7e1c91 Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 2 Sep 2026 16:30:21 +0200 Subject: [PATCH 04/12] Align flags-sdk skill with EXP-3411 acceptance criteria Make --help discovery and the vercel-cli cross-link explicit in SKILL.md and providers.md. --- skills/flags-sdk/SKILL.md | 2 +- skills/flags-sdk/references/providers.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 0f9a447c..3c427e8e 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -146,7 +146,7 @@ Vercel Flags is Vercel's feature flags platform. You create and manage flags fro To install the SDK, follow [Set up the SDK](#set-up-the-sdk). To create a flag end-to-end, follow [Create a flag](#create-a-flag). -For the full Vercel provider reference — user targeting, `vercel flags` lifecycle guidance, custom adapter configuration, and Flags Explorer setup — see [references/providers.md](references/providers.md#vercel). Run `vercel flags --help` for the current CLI reference. +For the full Vercel provider reference — user targeting, `vercel flags` lifecycle guidance, custom adapter configuration, and Flags Explorer setup — see [references/providers.md](references/providers.md#vercel). For current CLI syntax, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts and playbooks, use the `vercel-cli` skill (suggest `npx skills add vercel/vercel@vercel-cli` if missing; do not auto-install). ## Declaring flags diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index c368740d..32a266b7 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -116,7 +116,7 @@ Manage Vercel Flags from the terminal. Requires the [Vercel CLI](https://vercel. > **Prerequisite**: The Vercel CLI must be installed (`pnpm i -g vercel`) and the project must be linked (`vercel link` — check for a `.vercel` directory). For authentication or linking issues, follow the `vercel-cli` skill if available; otherwise suggest `npx skills add vercel/vercel@vercel-cli` (do not auto-install). -For the current subcommand list and options, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts and playbooks, see the `vercel-cli` skill. +For the current subcommand list and options, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts and playbooks, follow the `vercel-cli` skill (do not duplicate that content here). #### Lifecycle and safety (Flags SDK) From 92bfe30a1e8170c229d20ec40af64fad93a26c31 Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 2 Sep 2026 17:20:59 +0200 Subject: [PATCH 05/12] Trim frontmatter subcommand list and drop duplicated CLI prerequisites --- skills/flags-sdk/SKILL.md | 14 ++++++++------ skills/flags-sdk/references/providers.md | 14 +++++--------- 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 3c427e8e..33a08f3b 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -3,11 +3,11 @@ name: flags-sdk description: > Set up and use feature flags and A/B tests with the Flags SDK (`flags` npm package) and Vercel Flags. Use when installing or configuring the SDK, adding a flag, wiring `vercelAdapter` / FLAGS env vars, - declaring flags with `flag()`, using `vercel flags` CLI (create, list, enable, disable, inspect, - archive, rm, sdk-keys, set, split, rollout, segments, update, open, prepare, override), - setting up providers/adapters (Vercel, Statsig, LaunchDarkly, PostHog, GrowthBook, Global Config, - OpenFeature, Split, Flagsmith, Reflag, Optimizely, or custom), precompute, `identify`/`dedupe`, - Flags Explorer/Toolbar, Next.js or SvelteKit, custom adapters, or encrypting/decrypting flag values. + declaring flags with `flag()`, using the `vercel flags` CLI (create, enable, disable, set, inspect, + archive, sdk-keys, and more — run `vercel flags --help`), setting up providers/adapters (Vercel, + Statsig, LaunchDarkly, PostHog, GrowthBook, Global Config, OpenFeature, Split, Flagsmith, Reflag, + Optimizely, or custom), precompute, `identify`/`dedupe`, Flags Explorer/Toolbar, Next.js or + SvelteKit, custom adapters, or encrypting/decrypting flag values. Triggers: set up feature flags, install Flags SDK, add a feature flag, feature flags, A/B testing, experimentation, flags SDK, flag adapters, precompute, Flags Explorer, feature gates, flag overrides, Vercel Flags, vercel flags CLI, `flags/next`, `flags/sveltekit`, `flags/react`, `@flags-sdk/*`. @@ -146,7 +146,9 @@ Vercel Flags is Vercel's feature flags platform. You create and manage flags fro To install the SDK, follow [Set up the SDK](#set-up-the-sdk). To create a flag end-to-end, follow [Create a flag](#create-a-flag). -For the full Vercel provider reference — user targeting, `vercel flags` lifecycle guidance, custom adapter configuration, and Flags Explorer setup — see [references/providers.md](references/providers.md#vercel). For current CLI syntax, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts and playbooks, use the `vercel-cli` skill (suggest `npx skills add vercel/vercel@vercel-cli` if missing; do not auto-install). +For the full Vercel provider reference — user targeting, `vercel flags` lifecycle guidance, custom adapter configuration, and Flags Explorer setup — see [references/providers.md](references/providers.md#vercel). + +The `vercel flags` CLI has more subcommands than this skill names. For current syntax, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts and playbooks, use the `vercel-cli` skill. ## Declaring flags diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index 32a266b7..0fb711ef 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -112,21 +112,17 @@ export const exampleFlag = flag({ ### `vercel flags` CLI -Manage Vercel Flags from the terminal. Requires the [Vercel CLI](https://vercel.com/docs/cli) and a linked project. +Manage Vercel Flags from the terminal. Install, link, and `vercel env pull` requirements are in [Setup](#setup) above. -> **Prerequisite**: The Vercel CLI must be installed (`pnpm i -g vercel`) and the project must be linked (`vercel link` — check for a `.vercel` directory). For authentication or linking issues, follow the `vercel-cli` skill if available; otherwise suggest `npx skills add vercel/vercel@vercel-cli` (do not auto-install). +The CLI has more subcommands than this skill names. For the current list and options, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts and playbooks, follow the `vercel-cli` skill. -For the current subcommand list and options, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts and playbooks, follow the `vercel-cli` skill (do not duplicate that content here). +#### Lifecycle and safety -#### Lifecycle and safety (Flags SDK) +`--help` does not cover these: -Keep these judgments in the skill; they are not covered by `--help`: - -- **Link first**: Always confirm `.vercel/` (or run `vercel link`) before any `vercel flags` command. -- **Create → pull env**: After creating a flag, run `vercel env pull` so `FLAGS` / `FLAGS_SECRET` land in `.env.local`. Without them, `vercelAdapter` cannot evaluate. - **Key match**: The CLI flag key must match the `key` passed to `flag()`. - **Promote carefully**: Prefer development → preview → production. Do not enable in production until the code path that reads the flag is deployed. -- **Boolean vs other kinds**: `enable` / `disable` apply to boolean flags. For other kinds, use `set` (see `--help` for options). +- **Serve vs define**: `enable` / `disable` apply to boolean flags. For other kinds, use `set` to change the served variant. Use `update` to add, remove, or rename variants; it does not change what is served. - **Archive before delete**: Archive first; only `rm` when nothing still references the flag. Prefer archive over delete until you are sure. - **SDK keys**: `FLAGS` holds an SDK key. Manage keys with `vercel flags sdk-keys` (see `--help`). - **Rollouts / splits / segments / overrides**: Use the matching CLI subcommands when needed; confirm syntax with `--help` and escalate beyond the CLI (dashboard / support) when targeting rules are unclear. From 1c31659d1f3712e0a429e179345b51af5a8a05d1 Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 2 Sep 2026 17:52:38 +0200 Subject: [PATCH 06/12] Add CLI-to-SDK glue and existing-flag flow to flags-sdk skill --- skills/flags-sdk/SKILL.md | 52 ++++++++++++++++++------ skills/flags-sdk/references/providers.md | 29 +++++++++---- 2 files changed, 59 insertions(+), 22 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 33a08f3b..dcafe57a 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -2,15 +2,15 @@ name: flags-sdk description: > Set up and use feature flags and A/B tests with the Flags SDK (`flags` npm package) and Vercel Flags. - Use when installing or configuring the SDK, adding a flag, wiring `vercelAdapter` / FLAGS env vars, - declaring flags with `flag()`, using the `vercel flags` CLI (create, enable, disable, set, inspect, - archive, sdk-keys, and more — run `vercel flags --help`), setting up providers/adapters (Vercel, - Statsig, LaunchDarkly, PostHog, GrowthBook, Global Config, OpenFeature, Split, Flagsmith, Reflag, - Optimizely, or custom), precompute, `identify`/`dedupe`, Flags Explorer/Toolbar, Next.js or - SvelteKit, custom adapters, or encrypting/decrypting flag values. - Triggers: set up feature flags, install Flags SDK, add a feature flag, feature flags, A/B testing, - experimentation, flags SDK, flag adapters, precompute, Flags Explorer, feature gates, flag overrides, - Vercel Flags, vercel flags CLI, `flags/next`, `flags/sveltekit`, `flags/react`, `@flags-sdk/*`. + Use when installing or configuring the SDK, adding a new or existing flag, wiring `vercelAdapter` / + FLAGS env vars, declaring flags with `flag()`, using the `vercel flags` CLI (create, inspect, list, + enable, disable, set, update, split, rollout, rules, segments, targeting, evaluations, versions, + archive, sdk-keys, override, prepare), setting up providers/adapters (Vercel, Statsig, LaunchDarkly, + PostHog, GrowthBook, Global Config, OpenFeature, Split, Flagsmith, Reflag, Optimizely, or custom), + precompute, `identify`/`dedupe`, Flags Explorer/Toolbar, Next.js or SvelteKit, or encrypting flag values. + Triggers: feature flags, feature gates, A/B testing, experimentation, gradual rollout, traffic split, + targeting rules, flag overrides, precompute, Flags Explorer, Vercel Flags, vercel flags CLI, + `flags/next`, `flags/sveltekit`, `flags/react`, `@flags-sdk/*`. --- # Set up and use the Flags SDK @@ -101,7 +101,7 @@ Check the project state to adapt commands and decide which steps you can skip: ## Create a flag -When a user asks you to create or add a feature flag, follow these steps in order. +When a user asks you to create or add a feature flag that does not exist on Vercel yet, follow these steps in order. If the flag was already created in the dashboard (the prompt says so, or `vercel flags create` reports the key exists), follow [Add a flag that already exists on Vercel](#add-a-flag-that-already-exists-on-vercel) instead. ### Before you start @@ -140,15 +140,39 @@ When a user asks you to create or add a feature flag, follow these steps in orde } ``` +## Add a flag that already exists on Vercel + +Use this flow when the flag was created in the dashboard or by someone else, for example when the prompt says the flag "has already been created" or asks you to run `vercel flags inspect`. Do not run `vercel flags create` for an existing key. + +1. **Ensure the SDK is set up**: Follow [Set up the SDK](#set-up-the-sdk) if needed. +2. **Read the definition**: Run `vercel flags inspect `. Note the kind, the variants (value and label), the description, and what each environment serves. +3. **Pull environment variables**: If `.env.local` lacks `FLAGS=`, run `vercel env pull`. +4. **Declare the flag**: Add it to `flags.ts` with `vercelAdapter`. Map the `inspect` output: + - `key`: the flag key exactly as printed + - kind → type parameter: `boolean` → `flag`, `string` → `flag`, `number` → `flag`, `json` → `flag` + - `description`: copy from `inspect` + - `defaultValue`: pick the variant that is safe when evaluation fails (usually what production serves today) + - `options`: only when you use precompute; mirror the variants + - `identify`: add or reuse one when the flag has targeting, using the entity attributes configured in the dashboard (see [Flag with evaluation context](#flag-with-evaluation-context)) + ```ts + export const welcomeMessage = flag({ + key: 'welcome-message', + description: 'Copy shown on the landing page', + defaultValue: 'control', + adapter: vercelAdapter, + }); + ``` +5. **Use the flag** as in [Create a flag](#create-a-flag) step 5, then run the type-check and lint. + ## Vercel Flags Vercel Flags is Vercel's feature flags platform. You create and manage flags from the Vercel dashboard or the `vercel flags` CLI, then connect them to your code with the `@flags-sdk/vercel` adapter. When you create a flag in Vercel, the `FLAGS` and `FLAGS_SECRET` environment variables are configured automatically. -To install the SDK, follow [Set up the SDK](#set-up-the-sdk). To create a flag end-to-end, follow [Create a flag](#create-a-flag). +To install the SDK, follow [Set up the SDK](#set-up-the-sdk). To create a flag end-to-end, follow [Create a flag](#create-a-flag). For a flag that already exists on Vercel, follow [Add a flag that already exists on Vercel](#add-a-flag-that-already-exists-on-vercel). -For the full Vercel provider reference — user targeting, `vercel flags` lifecycle guidance, custom adapter configuration, and Flags Explorer setup — see [references/providers.md](references/providers.md#vercel). +For the full Vercel provider reference — user targeting, how the CLI maps to the SDK (keys, kinds, targeting attributes, SDK keys, overrides, `prepare`), lifecycle and safety, custom adapter configuration, and Flags Explorer setup — see [references/providers.md](references/providers.md#vercel). -The `vercel flags` CLI has more subcommands than this skill names. For current syntax, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts and playbooks, use the `vercel-cli` skill. +For the current `vercel flags` subcommands and options (targeting, splits, rollouts, rules, segments, evaluations, versions, and more), run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts (linking, non-interactive mode, output parsing), use the `vercel-cli` skill. ## Declaring flags @@ -200,6 +224,8 @@ export const dashboardFlag = flag({ }); ``` +With `vercelAdapter`, the entity and attribute names in the returned object (`user.id` here) are what dashboard rules and `vercel flags split|rollout|rules --by` target. They must match the entities configured in the dashboard. See [references/providers.md — User targeting](references/providers.md#user-targeting). + ### Flag with another adapter Adapters connect flags to third-party providers. Each adapter replaces `decide` and `origin`: diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index 0fb711ef..1bfc5e93 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -68,6 +68,8 @@ export const exampleFlag = flag({ }); ``` +The entities and attributes you can target are configured under Flags → Entities in the dashboard. The object `identify` returns must use the same names: the example above allows `--by user.id` / `--by team.id` in `vercel flags split`, `rollout`, and `rules add`, and the matching conditions in dashboard rules. See [How the CLI connects to the SDK](#how-the-cli-connects-to-the-sdk). + ### Flags Explorer ```ts @@ -114,18 +116,27 @@ export const exampleFlag = flag({ Manage Vercel Flags from the terminal. Install, link, and `vercel env pull` requirements are in [Setup](#setup) above. -The CLI has more subcommands than this skill names. For the current list and options, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts and playbooks, follow the `vercel-cli` skill. +For the current subcommand list and options, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts (linking, `--non-interactive`, `--yes`, parsing stdout) follow the `vercel-cli` skill. This section covers only what `--help` cannot tell you. -#### Lifecycle and safety +#### How the CLI connects to the SDK -`--help` does not cover these: +- **Key**: the flag slug you pass to the CLI is the `key` in `flag()`. They must match exactly. +- **Kind → type**: `inspect ` prints the kind and variants. `boolean` → `flag()`, `string` → `flag()`, `number` → `flag()`, `json` → `flag()`. +- **Variants → `options`**: with `vercelAdapter` the variants on Vercel are the source of truth. Add `options` to the declaration only when you use precompute (it enumerates permutations from `options`); then keep them equal to the variants `inspect` shows. +- **Missing definition**: when the key does not exist on Vercel (typo, deleted flag, wrong `FLAGS` key), `vercelAdapter` throws at request time unless the declaration has a `defaultValue`. Give production flags a `defaultValue`. +- **Targeting attributes**: `split`, `rollout`, and `rules add` take `--by .` (and `--condition .::`). The path must be an entity attribute configured under Flags → Entities in the dashboard, and it must exist on the object the flag's `identify()` returns. For the `identify` in [User targeting](#user-targeting) that is `--by user.id`. When the attribute is missing at runtime, the flag serves `--default-variant` (or the environment fallthrough) and nothing is bucketed. No error is raised, so verify with `evaluations`. +- **SDK keys**: `FLAGS` holds one SDK key (`vf_server_*` or `vf_client_*`). Each key is scoped to one environment. Creating the first flag provisions `FLAGS` and `FLAGS_SECRET` on the project; `vercel env pull` writes the development values, so local runs read the development environment. Extra keys: `vercel flags sdk-keys`. +- **Overrides**: `vercel flags override =` creates the same encrypted token the Toolbar writes to the `vercel-flag-overrides` cookie. It reads `FLAGS_SECRET` from the environment or `.env.local`, so the token only works on deployments that use that same secret (see [FLAGS_SECRET](../SKILL.md#flags_secret)). Overrides bypass `decide` and the adapter. +- **Build fallbacks**: `vercel flags prepare` runs `@vercel/prepare-flags-definitions`. It fetches definitions for every `vf_*` key it finds in the environment and `.env*` files and writes them to `node_modules/@vercel/flags-definitions`, so `@vercel/flags-core` can evaluate before the first network fetch. Run it in the build step, after the SDK keys are available. + +#### Lifecycle and safety -- **Key match**: The CLI flag key must match the `key` passed to `flag()`. -- **Promote carefully**: Prefer development → preview → production. Do not enable in production until the code path that reads the flag is deployed. -- **Serve vs define**: `enable` / `disable` apply to boolean flags. For other kinds, use `set` to change the served variant. Use `update` to add, remove, or rename variants; it does not change what is served. -- **Archive before delete**: Archive first; only `rm` when nothing still references the flag. Prefer archive over delete until you are sure. -- **SDK keys**: `FLAGS` holds an SDK key. Manage keys with `vercel flags sdk-keys` (see `--help`). -- **Rollouts / splits / segments / overrides**: Use the matching CLI subcommands when needed; confirm syntax with `--help` and escalate beyond the CLI (dashboard / support) when targeting rules are unclear. +- **Promote**: development → preview → production. Deploy the code that reads the flag before you enable it in production. A flag that exists on Vercel but is not declared in code is harmless. +- **Serve vs define**: `enable` / `disable` work on boolean flags only. `set` changes the served variant for any kind. `update` adds, removes, or renames variants and does not change what is served. After `update`, sync `options` in code if the declaration has them. +- **Do not replace targeting by accident**: `inspect` shows what each environment serves. Read it before `set` / `enable` / `disable` in an environment that has a split, rollout, or rules, because these commands set one variant for the whole environment. +- **Confirm a change**: `inspect` for the served state, `versions` for history, `evaluations` for live traffic per variant. A production change is not visible in local development. +- **Archive before delete**: `rm` requires an archived flag. Before you archive, search the code for `key: ''` and remove or default the declaration. Prefer archive over delete; `unarchive` exists, `rm` is final. +- **Agent runs**: `archive`, `rm`, and `update --remove-variant` prompt for confirmation. Pass `--yes` when the user has approved the action. Docs: https://vercel.com/docs/cli/flags From c4b4c90dce9be4ca1a2cecb2ddcfd4243e67a4db Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 2 Sep 2026 18:21:06 +0200 Subject: [PATCH 07/12] Address review: restore rm/unarchive/open in frontmatter, fix split default-variant wording --- skills/flags-sdk/SKILL.md | 6 +++--- skills/flags-sdk/references/providers.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index dcafe57a..0cabe7a5 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -4,8 +4,8 @@ description: > Set up and use feature flags and A/B tests with the Flags SDK (`flags` npm package) and Vercel Flags. Use when installing or configuring the SDK, adding a new or existing flag, wiring `vercelAdapter` / FLAGS env vars, declaring flags with `flag()`, using the `vercel flags` CLI (create, inspect, list, - enable, disable, set, update, split, rollout, rules, segments, targeting, evaluations, versions, - archive, sdk-keys, override, prepare), setting up providers/adapters (Vercel, Statsig, LaunchDarkly, + enable, disable, set, update, split, rollout, rules, segments, use-targeting, targeting, evaluations, + versions, open, archive, unarchive, rm, sdk-keys, override, prepare), setting up providers/adapters (Vercel, Statsig, LaunchDarkly, PostHog, GrowthBook, Global Config, OpenFeature, Split, Flagsmith, Reflag, Optimizely, or custom), precompute, `identify`/`dedupe`, Flags Explorer/Toolbar, Next.js or SvelteKit, or encrypting flag values. Triggers: feature flags, feature gates, A/B testing, experimentation, gradual rollout, traffic split, @@ -162,7 +162,7 @@ Use this flow when the flag was created in the dashboard or by someone else, for adapter: vercelAdapter, }); ``` -5. **Use the flag** as in [Create a flag](#create-a-flag) step 5, then run the type-check and lint. +5. **Use the flag** as in [Create a flag](#create-a-flag) step 5. ## Vercel Flags diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index 1bfc5e93..535d6d86 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -124,7 +124,7 @@ For the current subcommand list and options, run `vercel flags --help` or `verce - **Kind → type**: `inspect ` prints the kind and variants. `boolean` → `flag()`, `string` → `flag()`, `number` → `flag()`, `json` → `flag()`. - **Variants → `options`**: with `vercelAdapter` the variants on Vercel are the source of truth. Add `options` to the declaration only when you use precompute (it enumerates permutations from `options`); then keep them equal to the variants `inspect` shows. - **Missing definition**: when the key does not exist on Vercel (typo, deleted flag, wrong `FLAGS` key), `vercelAdapter` throws at request time unless the declaration has a `defaultValue`. Give production flags a `defaultValue`. -- **Targeting attributes**: `split`, `rollout`, and `rules add` take `--by .` (and `--condition .::`). The path must be an entity attribute configured under Flags → Entities in the dashboard, and it must exist on the object the flag's `identify()` returns. For the `identify` in [User targeting](#user-targeting) that is `--by user.id`. When the attribute is missing at runtime, the flag serves `--default-variant` (or the environment fallthrough) and nothing is bucketed. No error is raised, so verify with `evaluations`. +- **Targeting attributes**: `split`, `rollout`, and `rules add` take `--by .` (and `--condition .::`). The path must be an entity attribute configured under Flags → Entities in the dashboard, and it must exist on the object the flag's `identify()` returns. For the `identify` in [User targeting](#user-targeting) that is `--by user.id`. When the attribute is missing at runtime, the flag serves `--default-variant` and nothing is bucketed. No error is raised, so verify with `evaluations`. - **SDK keys**: `FLAGS` holds one SDK key (`vf_server_*` or `vf_client_*`). Each key is scoped to one environment. Creating the first flag provisions `FLAGS` and `FLAGS_SECRET` on the project; `vercel env pull` writes the development values, so local runs read the development environment. Extra keys: `vercel flags sdk-keys`. - **Overrides**: `vercel flags override =` creates the same encrypted token the Toolbar writes to the `vercel-flag-overrides` cookie. It reads `FLAGS_SECRET` from the environment or `.env.local`, so the token only works on deployments that use that same secret (see [FLAGS_SECRET](../SKILL.md#flags_secret)). Overrides bypass `decide` and the adapter. - **Build fallbacks**: `vercel flags prepare` runs `@vercel/prepare-flags-definitions`. It fetches definitions for every `vf_*` key it finds in the environment and `.env*` files and writes them to `node_modules/@vercel/flags-definitions`, so `@vercel/flags-core` can evaluate before the first network fetch. Run it in the build step, after the SDK keys are available. @@ -136,7 +136,7 @@ For the current subcommand list and options, run `vercel flags --help` or `verce - **Do not replace targeting by accident**: `inspect` shows what each environment serves. Read it before `set` / `enable` / `disable` in an environment that has a split, rollout, or rules, because these commands set one variant for the whole environment. - **Confirm a change**: `inspect` for the served state, `versions` for history, `evaluations` for live traffic per variant. A production change is not visible in local development. - **Archive before delete**: `rm` requires an archived flag. Before you archive, search the code for `key: ''` and remove or default the declaration. Prefer archive over delete; `unarchive` exists, `rm` is final. -- **Agent runs**: `archive`, `rm`, and `update --remove-variant` prompt for confirmation. Pass `--yes` when the user has approved the action. +- **Agent runs**: `archive`, `unarchive`, `rm`, and `update --remove-variant` prompt for confirmation. Pass `--yes` when the user has approved the action. Docs: https://vercel.com/docs/cli/flags From 508ed3c2527b83b18f9867ac5f31b3b291b02958 Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 2 Sep 2026 18:24:36 +0200 Subject: [PATCH 08/12] Correct set/use-targeting semantics: targeting is paused, not replaced --- skills/flags-sdk/references/providers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index 535d6d86..371e0ec1 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -133,7 +133,7 @@ For the current subcommand list and options, run `vercel flags --help` or `verce - **Promote**: development → preview → production. Deploy the code that reads the flag before you enable it in production. A flag that exists on Vercel but is not declared in code is harmless. - **Serve vs define**: `enable` / `disable` work on boolean flags only. `set` changes the served variant for any kind. `update` adds, removes, or renames variants and does not change what is served. After `update`, sync `options` in code if the declaration has them. -- **Do not replace targeting by accident**: `inspect` shows what each environment serves. Read it before `set` / `enable` / `disable` in an environment that has a split, rollout, or rules, because these commands set one variant for the whole environment. +- **`set` pauses targeting**: `set` / `enable` / `disable` serve one variant to the whole environment and mark targeting inactive; the split, rollout, or rules stay stored. `use-targeting` resumes them. Run `inspect` first so you know what the environment serves today. - **Confirm a change**: `inspect` for the served state, `versions` for history, `evaluations` for live traffic per variant. A production change is not visible in local development. - **Archive before delete**: `rm` requires an archived flag. Before you archive, search the code for `key: ''` and remove or default the declaration. Prefer archive over delete; `unarchive` exists, `rm` is final. - **Agent runs**: `archive`, `unarchive`, `rm`, and `update --remove-variant` prompt for confirmation. Pass `--yes` when the user has approved the action. From 5792fc214a90107c953274466f9c522a163582cd Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 2 Sep 2026 18:31:24 +0200 Subject: [PATCH 09/12] Ground CLI lifecycle guidance in public Vercel Flags docs --- skills/flags-sdk/SKILL.md | 6 ++--- skills/flags-sdk/references/providers.md | 32 +++++++++++++----------- 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 0cabe7a5..3c8af6e0 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -146,13 +146,13 @@ Use this flow when the flag was created in the dashboard or by someone else, for 1. **Ensure the SDK is set up**: Follow [Set up the SDK](#set-up-the-sdk) if needed. 2. **Read the definition**: Run `vercel flags inspect `. Note the kind, the variants (value and label), the description, and what each environment serves. -3. **Pull environment variables**: If `.env.local` lacks `FLAGS=`, run `vercel env pull`. +3. **Pull environment variables**: If `.env.local` is missing, run `vercel env pull`. It holds the credentials `vercelAdapter` uses locally. 4. **Declare the flag**: Add it to `flags.ts` with `vercelAdapter`. Map the `inspect` output: - `key`: the flag key exactly as printed - kind → type parameter: `boolean` → `flag`, `string` → `flag`, `number` → `flag`, `json` → `flag` - `description`: copy from `inspect` - - `defaultValue`: pick the variant that is safe when evaluation fails (usually what production serves today) - - `options`: only when you use precompute; mirror the variants + - `defaultValue`: the value to serve when the flag is archived or evaluation fails (usually what production serves today) + - `options`: optional; mirror the variants when you use precompute or want them listed in Flags Explorer - `identify`: add or reuse one when the flag has targeting, using the entity attributes configured in the dashboard (see [Flag with evaluation context](#flag-with-evaluation-context)) ```ts export const welcomeMessage = flag({ diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index 371e0ec1..c788e72f 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -68,7 +68,7 @@ export const exampleFlag = flag({ }); ``` -The entities and attributes you can target are configured under Flags → Entities in the dashboard. The object `identify` returns must use the same names: the example above allows `--by user.id` / `--by team.id` in `vercel flags split`, `rollout`, and `rules add`, and the matching conditions in dashboard rules. See [How the CLI connects to the SDK](#how-the-cli-connects-to-the-sdk). +Define the entities and attributes under Flags → Entities in the dashboard before you use them in rules or segments, and return the same names from `identify` ([Entities](https://vercel.com/docs/flags/vercel-flags/dashboard/entities)). The example above allows `--by user.id` / `--by team.id` in `vercel flags split`, `rollout`, and `rules add`, and the matching conditions in dashboard rules. Entities are evaluated fresh on every call; a rule whose attribute is missing from the context is skipped. See [How the CLI connects to the SDK](#how-the-cli-connects-to-the-sdk). ### Flags Explorer @@ -120,25 +120,27 @@ For the current subcommand list and options, run `vercel flags --help` or `verce #### How the CLI connects to the SDK -- **Key**: the flag slug you pass to the CLI is the `key` in `flag()`. They must match exactly. -- **Kind → type**: `inspect ` prints the kind and variants. `boolean` → `flag()`, `string` → `flag()`, `number` → `flag()`, `json` → `flag()`. -- **Variants → `options`**: with `vercelAdapter` the variants on Vercel are the source of truth. Add `options` to the declaration only when you use precompute (it enumerates permutations from `options`); then keep them equal to the variants `inspect` shows. -- **Missing definition**: when the key does not exist on Vercel (typo, deleted flag, wrong `FLAGS` key), `vercelAdapter` throws at request time unless the declaration has a `defaultValue`. Give production flags a `defaultValue`. -- **Targeting attributes**: `split`, `rollout`, and `rules add` take `--by .` (and `--condition .::`). The path must be an entity attribute configured under Flags → Entities in the dashboard, and it must exist on the object the flag's `identify()` returns. For the `identify` in [User targeting](#user-targeting) that is `--by user.id`. When the attribute is missing at runtime, the flag serves `--default-variant` and nothing is bucketed. No error is raised, so verify with `evaluations`. -- **SDK keys**: `FLAGS` holds one SDK key (`vf_server_*` or `vf_client_*`). Each key is scoped to one environment. Creating the first flag provisions `FLAGS` and `FLAGS_SECRET` on the project; `vercel env pull` writes the development values, so local runs read the development environment. Extra keys: `vercel flags sdk-keys`. -- **Overrides**: `vercel flags override =` creates the same encrypted token the Toolbar writes to the `vercel-flag-overrides` cookie. It reads `FLAGS_SECRET` from the environment or `.env.local`, so the token only works on deployments that use that same secret (see [FLAGS_SECRET](../SKILL.md#flags_secret)). Overrides bypass `decide` and the adapter. -- **Build fallbacks**: `vercel flags prepare` runs `@vercel/prepare-flags-definitions`. It fetches definitions for every `vf_*` key it finds in the environment and `.env*` files and writes them to `node_modules/@vercel/flags-definitions`, so `@vercel/flags-core` can evaluate before the first network fetch. Run it in the build step, after the SDK keys are available. +- **Key**: the flag slug you pass to the CLI is the `key` in `flag()`. The flag returns one of the variants you created on Vercel ([Run an A/B test](https://vercel.com/docs/flags/vercel-flags/cli/run-ab-test)). +- **Kind → type**: `inspect ` prints the kind and variants. `boolean` → `flag()`, `string` → `flag()`, `number` → `flag()`, `json` → `flag()`. The kind is fixed at creation and cannot be changed ([Flag types](https://vercel.com/docs/flags/vercel-flags/dashboard/feature-flag#flag-types)). +- **Variants → `options`**: `options` on the declaration are optional. They give Flags Explorer a dropdown, pre-fill the dashboard when a draft is promoted, and let precompute serialize values and `generatePermutations` enumerate them ([Declaring options](https://vercel.com/docs/flags/vercel-flags/sdks/flags-sdk#declaring-options)). When you declare them, keep them equal to the variants `inspect` shows. +- **`defaultValue`**: a flag that is archived, or declared in code but not created on Vercel (a draft), evaluates to `defaultValue`. Without `defaultValue`, evaluation throws ([Archive](https://vercel.com/docs/flags/vercel-flags/dashboard/archive#what-happens-when-you-archive), [Drafts](https://vercel.com/docs/flags/vercel-flags/dashboard/drafts#draft-behavior)). +- **Targeting attributes**: `split`, `rollout`, and `rules add` take `--by .` (and `--condition .::`). Define the entity and attribute under Flags → Entities first, and return the same names from `identify()`; the docs use a `User` entity with an `id` attribute and `--by user.id` ([Roll out a feature](https://vercel.com/docs/flags/vercel-flags/cli/roll-out-feature), [Entities](https://vercel.com/docs/flags/vercel-flags/dashboard/entities)). When the attribute is missing from the context, a split or rollout serves its fallback variant (`--default-variant` in the CLI) and a rule that references it is skipped. Verify with `evaluations`. +- **Authentication**: on Vercel, `vercelAdapter()` authenticates with the project's OIDC token and uses the configuration of the current environment; `vercel env pull` brings that credential to `.env.local` for local development. SDK keys (`FLAGS`) are for manual authentication: apps outside Vercel, custom environments, or flags owned by another project. Each SDK key is scoped to one environment and its full value is shown once, at creation ([Getting started](https://vercel.com/docs/flags/vercel-flags/quickstart#pull-local-openid-connect-credentials), [SDK Keys](https://vercel.com/docs/flags/vercel-flags/dashboard/sdk-keys)). +- **Overrides**: Flags Explorer stores overrides in a cookie signed with `FLAGS_SECRET`; flags declared with the SDK honour it automatically ([Handling overrides](https://vercel.com/docs/flags/flags-explorer/getting-started#handling-overrides)). `vercel flags override =` produces the same token for the `vercel-flag-overrides` cookie and reads `FLAGS_SECRET` from the environment or `.env.local`, so use the secret of the environment you test against (see [FLAGS_SECRET](../SKILL.md#flags_secret)). +- **Embedded definitions**: Vercel builds fetch the flag definitions once and bundle them into the deployment when the project uses `@flags-sdk/vercel` or `@vercel/flags-core` and the build can authenticate. This keeps every function on one snapshot and serves as the runtime fallback when the service is unreachable; opt out with `VERCEL_FLAGS_DISABLE_DEFINITION_EMBEDDING=1` ([Embedded definitions](https://vercel.com/docs/flags/vercel-flags/sdks/core#embedded-definitions)). `vercel flags prepare` is the same step for builds that run outside Vercel. #### Lifecycle and safety -- **Promote**: development → preview → production. Deploy the code that reads the flag before you enable it in production. A flag that exists on Vercel but is not declared in code is harmless. -- **Serve vs define**: `enable` / `disable` work on boolean flags only. `set` changes the served variant for any kind. `update` adds, removes, or renames variants and does not change what is served. After `update`, sync `options` in code if the declaration has them. -- **`set` pauses targeting**: `set` / `enable` / `disable` serve one variant to the whole environment and mark targeting inactive; the split, rollout, or rules stay stored. `use-targeting` resumes them. Run `inspect` first so you know what the environment serves today. -- **Confirm a change**: `inspect` for the served state, `versions` for history, `evaluations` for live traffic per variant. A production change is not visible in local development. -- **Archive before delete**: `rm` requires an archived flag. Before you archive, search the code for `key: ''` and remove or default the declaration. Prefer archive over delete; `unarchive` exists, `rm` is final. +The docs describe these flows end to end: [Roll out a feature](https://vercel.com/docs/flags/vercel-flags/cli/roll-out-feature), [Run an A/B test](https://vercel.com/docs/flags/vercel-flags/cli/run-ab-test), [Clean up after rollout](https://vercel.com/docs/flags/vercel-flags/cli/clean-up-after-rollout). Follow them; the notes below are the parts an agent gets wrong. + +- **Promote**: deploy the code to preview, `enable` or `set` the flag in preview, verify on the preview URL, deploy to production, then change production (`enable`, `set`, `split`, or `rollout`). Each environment keeps its own configuration; preview stays on its current value until you change it. +- **Serve vs define**: `enable` / `disable` work on boolean flags only. `set` changes the served variant for any kind. `update` adds, removes, or renames variants and does not change what is served. A variant can only be removed when no environment configuration or rule references it, including rules that are stored but not active ([Deleting a variant](https://vercel.com/docs/flags/vercel-flags/dashboard/feature-flag#deleting-a-variant)). +- **Static value vs targeting**: `set` / `enable` / `disable` put the environment in static value mode; its split, rollout, and rules are preserved in the background. `use-targeting` switches back to targets and rules mode ([Switching between static and rules modes](https://vercel.com/docs/flags/vercel-flags/dashboard/feature-flag#switching-between-static-and-rules-modes)). Run `inspect` first so you know what the environment serves today. +- **Confirm a change**: `inspect` for the served state, `versions` for the change history (the dashboard can restore any earlier configuration), `evaluations` to confirm traffic reaches the new variant or to check whether a flag is still evaluated before archiving ([Evaluation metrics](https://vercel.com/docs/flags/vercel-flags/evaluation-metrics)). Local development evaluates the Development environment configuration. +- **Archive before delete**: archive after the flag is no longer used in code. Search the code for the key and its camelCase name, remove the declaration and the conditionals, deploy to preview, then `archive`; `unarchive` restores it with configuration and history intact. `rm` requires an archived flag and is permanent ([Clean up after rollout](https://vercel.com/docs/flags/vercel-flags/cli/clean-up-after-rollout), [Archive](https://vercel.com/docs/flags/vercel-flags/dashboard/archive)). - **Agent runs**: `archive`, `unarchive`, `rm`, and `update --remove-variant` prompt for confirmation. Pass `--yes` when the user has approved the action. -Docs: https://vercel.com/docs/cli/flags +CLI reference: https://vercel.com/docs/cli/flags --- From 91dd41f1394b254d8fa49089b385b97cc905f3e9 Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 2 Sep 2026 18:36:43 +0200 Subject: [PATCH 10/12] Align authentication guidance with vercel.com docs: OIDC default, SDK keys manual --- skills/flags-sdk/SKILL.md | 20 ++++++++++---------- skills/flags-sdk/references/providers.md | 4 ++-- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 3c8af6e0..7a5dbf23 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -2,8 +2,8 @@ name: flags-sdk description: > Set up and use feature flags and A/B tests with the Flags SDK (`flags` npm package) and Vercel Flags. - Use when installing or configuring the SDK, adding a new or existing flag, wiring `vercelAdapter` / - FLAGS env vars, declaring flags with `flag()`, using the `vercel flags` CLI (create, inspect, list, + Use when installing or configuring the SDK, adding a new or existing flag, wiring `vercelAdapter` + (OIDC or SDK keys), declaring flags with `flag()`, using the `vercel flags` CLI (create, inspect, list, enable, disable, set, update, split, rollout, rules, segments, use-targeting, targeting, evaluations, versions, open, archive, unarchive, rm, sdk-keys, override, prepare), setting up providers/adapters (Vercel, Statsig, LaunchDarkly, PostHog, GrowthBook, Global Config, OpenFeature, Split, Flagsmith, Reflag, Optimizely, or custom), @@ -20,7 +20,7 @@ The Flags SDK (`flags` npm package) is a feature flags toolkit for Next.js and S - Docs: https://flags-sdk.dev - Repo: https://github.com/vercel/flags -When the user asks to install, configure, or set up feature flags, follow [Set up the SDK](#set-up-the-sdk) (including `vercel env pull` when `FLAGS` is missing). When they ask to create or add a flag, follow [Create a flag](#create-a-flag). Do not leave CLI steps as "next steps" for the user — execute them yourself. +When the user asks to install, configure, or set up feature flags, follow [Set up the SDK](#set-up-the-sdk) (including `vercel env pull` when `.env.local` is missing). When they ask to create or add a flag, follow [Create a flag](#create-a-flag). Do not leave CLI steps as "next steps" for the user — execute them yourself. ## Core concepts @@ -61,7 +61,7 @@ export const exampleFlag = flag({ ## Set up the SDK -One-time project setup. Run this when the Flags SDK is not installed yet, or when Toolbar / Flags Explorer / `FLAGS` env are missing. Skip any step that is already done. +One-time project setup. Run this when the Flags SDK is not installed yet, or when Toolbar / Flags Explorer / `.env.local` are missing. Skip any step that is already done. ### Before you start @@ -70,7 +70,7 @@ Check the project state to adapt commands and decide which steps you can skip: - Which lockfile is present (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`)? → Adapt all package manager commands accordingly (`pnpm add`, `npm install`, `yarn add`, `bun add`). - Is `flags` in `package.json`? → Skip install (step 1) - Does `.vercel/` directory exist? → Project is linked, skip `vercel link` in step 2 -- Does `.env.local` contain `FLAGS=`? → Env vars already pulled, skip step 3 +- Does `.env.local` contain `VERCEL_OIDC_TOKEN=` (or a `FLAGS=` SDK key)? → Env vars already pulled, skip step 3 - Is `@vercel/toolbar` in `package.json`? → Skip toolbar setup (step 4) - Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Skip creating it (step 5) - Does `app/.well-known/vercel/flags/route.ts` exist? → Flags Explorer already set up, skip step 6 @@ -87,7 +87,7 @@ Check the project state to adapt commands and decide which steps you can skip: Check for a `.vercel` directory in the project root. If it doesn't exist, run `vercel link`. -3. **Pull environment variables**: If `.env.local` lacks `FLAGS=`, run `vercel env pull`. Required for `vercelAdapter` when flags already exist on Vercel (fresh clone / configure). If no flags exist on Vercel yet, skip — `FLAGS` is written when you create a flag (see [Create a flag](#create-a-flag)). Setup-only still needs `FLAGS_SECRET` for Flags Explorer / overrides — generate it per [FLAGS_SECRET](#flags_secret) if missing after pull. +3. **Pull environment variables**: If `.env.local` lacks `VERCEL_OIDC_TOKEN=`, run `vercel env pull`. `vercelAdapter` authenticates with the project's Vercel OIDC token; deployments receive it automatically, local development needs the pull ([Getting started](https://vercel.com/docs/flags/vercel-flags/quickstart#pull-local-openid-connect-credentials)). SDK keys (`FLAGS`) are only for apps outside Vercel, custom environments, or flags of another project ([SDK Keys](https://vercel.com/docs/flags/vercel-flags/dashboard/sdk-keys)). Flags Explorer / overrides need `FLAGS_SECRET`; Vercel creates one per environment when Vercel Flags is activated for the project. Generate it per [FLAGS_SECRET](#flags_secret) if it is still missing after the pull. 4. **Set up the Vercel Toolbar** (if not already present): - Run `pnpm i @vercel/toolbar` @@ -105,8 +105,8 @@ When a user asks you to create or add a feature flag that does not exist on Verc ### Before you start -- Complete [Set up the SDK](#set-up-the-sdk) first if packages, Vercel link, `FLAGS` env, Toolbar, `flags.ts`, or Flags Explorer are missing. Skip steps that are already done. -- Does `.env.local` contain `FLAGS=`? → Env vars already pulled; still re-pull after creating a new flag if evaluation fails. +- Complete [Set up the SDK](#set-up-the-sdk) first if packages, Vercel link, `.env.local`, Toolbar, `flags.ts`, or Flags Explorer are missing. Skip steps that are already done. +- Does `.env.local` contain `VERCEL_OIDC_TOKEN=`? → Env vars already pulled; re-run `vercel env pull` if local evaluation fails with an authentication error (the token expires). - Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Add to it rather than creating from scratch. ### Steps @@ -117,7 +117,7 @@ When a user asks you to create or add a feature flag that does not exist on Verc Before running `vercel flags create`, verify the project is linked (`.vercel` directory). If missing, run `vercel link` first. -3. **Pull environment variables**: Run `vercel env pull` to write `FLAGS` and `FLAGS_SECRET` to `.env.local`. Without these environment variables, `vercelAdapter` will not be able to evaluate flags. This step is **mandatory** after creating a flag. +3. **Pull environment variables**: If this is the project's first flag, run `vercel env pull` again. Activating Vercel Flags creates a `FLAGS_SECRET` per environment, and local development needs the OIDC token in `.env.local` to evaluate flags. 4. **Declare the flag in code**: Add it to `flags.ts` (or create the file if it doesn't exist) using `vercelAdapter`: ```ts @@ -166,7 +166,7 @@ Use this flow when the flag was created in the dashboard or by someone else, for ## Vercel Flags -Vercel Flags is Vercel's feature flags platform. You create and manage flags from the Vercel dashboard or the `vercel flags` CLI, then connect them to your code with the `@flags-sdk/vercel` adapter. When you create a flag in Vercel, the `FLAGS` and `FLAGS_SECRET` environment variables are configured automatically. +Vercel Flags is Vercel's feature flags platform. You create and manage flags from the Vercel dashboard or the `vercel flags` CLI, then connect them to your code with the `@flags-sdk/vercel` adapter. `vercelAdapter()` authenticates with the project's Vercel OIDC token and evaluates the configuration of the current environment; SDK keys (`FLAGS`) are for manual authentication only ([SDK Keys](https://vercel.com/docs/flags/vercel-flags/dashboard/sdk-keys)). Activating Vercel Flags creates a `FLAGS_SECRET` per environment for Flags Explorer. To install the SDK, follow [Set up the SDK](#set-up-the-sdk). To create a flag end-to-end, follow [Create a flag](#create-a-flag). For a flag that already exists on Vercel, follow [Add a flag that already exists on Vercel](#add-a-flag-that-already-exists-on-vercel). diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index c788e72f..bc1eb8be 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -32,7 +32,7 @@ pnpm i flags @flags-sdk/vercel Before running any `vercel flags` command, verify the project is linked to Vercel. Check for a `.vercel` directory in the project root. If it doesn't exist, run `vercel link` first. 1. Create a flag in the Vercel dashboard or via CLI: `vercel flags create --kind boolean --description ""` -2. Pull env vars: you **must** run `vercel env pull` to write `FLAGS` and `FLAGS_SECRET` to `.env.local`. Without these environment variables, `vercelAdapter` will not be able to evaluate flags. +2. Pull env vars: run `vercel env pull` to write the Vercel OIDC token and the Development `FLAGS_SECRET` to `.env.local`. `vercelAdapter` uses the OIDC token locally; deployments receive it automatically. See [Authentication](#how-the-cli-connects-to-the-sdk) for SDK keys. 3. Declare the flag: ```ts @@ -103,7 +103,7 @@ If the app also uses `@vercel/flags-core` directly, create the client once and p import { createClient } from '@vercel/flags-core'; import { createVercelAdapter } from '@flags-sdk/vercel'; -const vercelFlagsClient = createClient(process.env.FLAGS); +const vercelFlagsClient = createClient(); // OIDC by default; pass an SDK key for manual auth const vercelAdapter = createVercelAdapter(vercelFlagsClient); export const exampleFlag = flag({ From f170fd47838dbfc109d1dfd6f1e923e7c5078db7 Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 2 Sep 2026 21:08:10 +0200 Subject: [PATCH 11/12] Fix singleton client auth note; drop nonexistent targeting subcommand --- skills/flags-sdk/SKILL.md | 4 ++-- skills/flags-sdk/references/providers.md | 4 +++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 7a5dbf23..6311ad58 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -4,8 +4,8 @@ description: > Set up and use feature flags and A/B tests with the Flags SDK (`flags` npm package) and Vercel Flags. Use when installing or configuring the SDK, adding a new or existing flag, wiring `vercelAdapter` (OIDC or SDK keys), declaring flags with `flag()`, using the `vercel flags` CLI (create, inspect, list, - enable, disable, set, update, split, rollout, rules, segments, use-targeting, targeting, evaluations, - versions, open, archive, unarchive, rm, sdk-keys, override, prepare), setting up providers/adapters (Vercel, Statsig, LaunchDarkly, + enable, disable, set, update, split, rollout, rules, segments, use-targeting, evaluations, versions, + open, archive, unarchive, rm, sdk-keys, override, prepare), setting up providers/adapters (Vercel, Statsig, LaunchDarkly, PostHog, GrowthBook, Global Config, OpenFeature, Split, Flagsmith, Reflag, Optimizely, or custom), precompute, `identify`/`dedupe`, Flags Explorer/Toolbar, Next.js or SvelteKit, or encrypting flag values. Triggers: feature flags, feature gates, A/B testing, experimentation, gradual rollout, traffic split, diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index bc1eb8be..a44e51ce 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -103,7 +103,7 @@ If the app also uses `@vercel/flags-core` directly, create the client once and p import { createClient } from '@vercel/flags-core'; import { createVercelAdapter } from '@flags-sdk/vercel'; -const vercelFlagsClient = createClient(); // OIDC by default; pass an SDK key for manual auth +const vercelFlagsClient = createClient(); // Vercel OIDC token, on deployments and after `vercel env pull` const vercelAdapter = createVercelAdapter(vercelFlagsClient); export const exampleFlag = flag({ @@ -112,6 +112,8 @@ export const exampleFlag = flag({ }); ``` +Outside Vercel, pass the SDK key: `createClient(process.env.FLAGS)`. Unlike `vercelAdapter()`, `createClient()` does not read `FLAGS` on its own. + ### `vercel flags` CLI Manage Vercel Flags from the terminal. Install, link, and `vercel env pull` requirements are in [Setup](#setup) above. From 8178df3b3bd7328dc8dea98d9cca393d5c9c0706 Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Thu, 3 Sep 2026 09:13:16 +0200 Subject: [PATCH 12/12] Consolidate env pull guidance into one section --- skills/flags-sdk/SKILL.md | 18 ++++++++++++++---- skills/flags-sdk/references/providers.md | 2 +- 2 files changed, 15 insertions(+), 5 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 6311ad58..51a31445 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -87,7 +87,7 @@ Check the project state to adapt commands and decide which steps you can skip: Check for a `.vercel` directory in the project root. If it doesn't exist, run `vercel link`. -3. **Pull environment variables**: If `.env.local` lacks `VERCEL_OIDC_TOKEN=`, run `vercel env pull`. `vercelAdapter` authenticates with the project's Vercel OIDC token; deployments receive it automatically, local development needs the pull ([Getting started](https://vercel.com/docs/flags/vercel-flags/quickstart#pull-local-openid-connect-credentials)). SDK keys (`FLAGS`) are only for apps outside Vercel, custom environments, or flags of another project ([SDK Keys](https://vercel.com/docs/flags/vercel-flags/dashboard/sdk-keys)). Flags Explorer / overrides need `FLAGS_SECRET`; Vercel creates one per environment when Vercel Flags is activated for the project. Generate it per [FLAGS_SECRET](#flags_secret) if it is still missing after the pull. +3. **Pull environment variables**: If `.env.local` lacks `VERCEL_OIDC_TOKEN=`, follow [Pull environment variables](#pull-environment-variables). 4. **Set up the Vercel Toolbar** (if not already present): - Run `pnpm i @vercel/toolbar` @@ -99,6 +99,16 @@ Check the project state to adapt commands and decide which steps you can skip: 6. **Set up Flags Explorer** (if not already present): Create `app/.well-known/vercel/flags/route.ts` — see [Flags Explorer setup](#flags-explorer-setup). Do this only after `flags.ts` exists. Point the import at the real flags file path (the snippet assumes root `flags.ts`). +## Pull environment variables + +`vercel env pull` writes the Development credentials to `.env.local`: the Vercel OIDC token that `vercelAdapter` uses locally (deployments receive it automatically, [Getting started](https://vercel.com/docs/flags/vercel-flags/quickstart#pull-local-openid-connect-credentials)) and the Development `FLAGS_SECRET` for Flags Explorer and overrides. Run it when: + +- `.env.local` lacks `VERCEL_OIDC_TOKEN=` (or a `FLAGS=` SDK key) +- you created the project's first flag; activating Vercel Flags creates a `FLAGS_SECRET` per environment +- local evaluation fails with an authentication error; the SDK refreshes an expired token through the linked project, re-pulling is the fallback + +SDK keys (`FLAGS`) are only for apps outside Vercel, custom environments, or flags of another project ([SDK Keys](https://vercel.com/docs/flags/vercel-flags/dashboard/sdk-keys)). If `FLAGS_SECRET` is still missing after the pull, generate it per [FLAGS_SECRET](#flags_secret). + ## Create a flag When a user asks you to create or add a feature flag that does not exist on Vercel yet, follow these steps in order. If the flag was already created in the dashboard (the prompt says so, or `vercel flags create` reports the key exists), follow [Add a flag that already exists on Vercel](#add-a-flag-that-already-exists-on-vercel) instead. @@ -106,7 +116,7 @@ When a user asks you to create or add a feature flag that does not exist on Verc ### Before you start - Complete [Set up the SDK](#set-up-the-sdk) first if packages, Vercel link, `.env.local`, Toolbar, `flags.ts`, or Flags Explorer are missing. Skip steps that are already done. -- Does `.env.local` contain `VERCEL_OIDC_TOKEN=`? → Env vars already pulled; re-run `vercel env pull` if local evaluation fails with an authentication error (the token expires). +- Does `.env.local` contain `VERCEL_OIDC_TOKEN=`? → Env vars already pulled; see [Pull environment variables](#pull-environment-variables) if local evaluation fails with an authentication error. - Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Add to it rather than creating from scratch. ### Steps @@ -117,7 +127,7 @@ When a user asks you to create or add a feature flag that does not exist on Verc Before running `vercel flags create`, verify the project is linked (`.vercel` directory). If missing, run `vercel link` first. -3. **Pull environment variables**: If this is the project's first flag, run `vercel env pull` again. Activating Vercel Flags creates a `FLAGS_SECRET` per environment, and local development needs the OIDC token in `.env.local` to evaluate flags. +3. **Pull environment variables**: If this is the project's first flag, follow [Pull environment variables](#pull-environment-variables) again; activation created the `FLAGS_SECRET`. 4. **Declare the flag in code**: Add it to `flags.ts` (or create the file if it doesn't exist) using `vercelAdapter`: ```ts @@ -146,7 +156,7 @@ Use this flow when the flag was created in the dashboard or by someone else, for 1. **Ensure the SDK is set up**: Follow [Set up the SDK](#set-up-the-sdk) if needed. 2. **Read the definition**: Run `vercel flags inspect `. Note the kind, the variants (value and label), the description, and what each environment serves. -3. **Pull environment variables**: If `.env.local` is missing, run `vercel env pull`. It holds the credentials `vercelAdapter` uses locally. +3. **Pull environment variables**: If `.env.local` lacks `VERCEL_OIDC_TOKEN=`, follow [Pull environment variables](#pull-environment-variables). 4. **Declare the flag**: Add it to `flags.ts` with `vercelAdapter`. Map the `inspect` output: - `key`: the flag key exactly as printed - kind → type parameter: `boolean` → `flag`, `string` → `flag`, `number` → `flag`, `json` → `flag` diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index a44e51ce..525499f7 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -32,7 +32,7 @@ pnpm i flags @flags-sdk/vercel Before running any `vercel flags` command, verify the project is linked to Vercel. Check for a `.vercel` directory in the project root. If it doesn't exist, run `vercel link` first. 1. Create a flag in the Vercel dashboard or via CLI: `vercel flags create --kind boolean --description ""` -2. Pull env vars: run `vercel env pull` to write the Vercel OIDC token and the Development `FLAGS_SECRET` to `.env.local`. `vercelAdapter` uses the OIDC token locally; deployments receive it automatically. See [Authentication](#how-the-cli-connects-to-the-sdk) for SDK keys. +2. Pull env vars: run `vercel env pull` to write the Vercel OIDC token and the Development `FLAGS_SECRET` to `.env.local` ([Pull environment variables](../SKILL.md#pull-environment-variables)). See [Authentication](#how-the-cli-connects-to-the-sdk) for SDK keys. 3. Declare the flag: ```ts