Skip to content

docs(skills): separate flag management from SDK setup #495

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
vincent-derks wants to merge 3 commits into
base: main
Choose a base branch
from
+21 −11
Draft

docs(skills): separate flag management from SDK setup #495

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
675390a
docs(skills): separate flag management from SDK setup
vincent-derks Sep 9, 2026
3445c26
docs(skills): restore vercel link step and route CLI-only requests
vincent-derks Sep 9, 2026
9f67eb5
docs(skills): keep setup first and define CLI-only requests
vincent-derks Sep 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 18 additions & 8 deletions skills/flags-sdk/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `.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.
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). A request is CLI-only when the user asks to inspect or change a remote flag and asks for no code change; then follow [CLI-only flag management](#cli-only-flag-management). Inside an app repository, default to the full flow. Do not leave CLI steps as "next steps" for the user — execute them yourself.

## Core concepts

Expand Down Expand Up @@ -69,7 +69,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
- Is the project linked? → Verify as described in [Project targeting](#project-targeting), then skip `vercel link` in step 2
- 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)
Expand All @@ -82,10 +82,10 @@ Check the project state to adapt commands and decide which steps you can skip:
pnpm i flags @flags-sdk/vercel
```

2. **Link the project to Vercel** (required for `vercel flags` and env vars):
> **Prerequisite**: The `vercel flags` commands require the Vercel CLI to be installed and authenticated. If the Vercel CLI is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel <command> --help` in the meantime.
2. **Link the project to Vercel** (required for `vercel env pull` and local OIDC token refresh):
> **Prerequisite**: The Vercel CLI must be installed and authenticated. If it is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel <command> --help` in the meantime.

Check for a `.vercel` directory in the project root. If it doesn't exist, run `vercel link`.
Verify the link as described in [Project targeting](#project-targeting). If the project is not linked, run `vercel link`.

3. **Pull environment variables**: If `.env.local` lacks `VERCEL_OIDC_TOKEN=`, follow [Pull environment variables](#pull-environment-variables).

Expand All @@ -111,7 +111,7 @@ SDK keys (`FLAGS`) are only for apps outside Vercel, custom environments, or fla

## 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.
When a user asks you to create or add a feature flag that does not exist on Vercel yet, follow these steps in order. For a [CLI-only request](#cli-only-flag-management), run step 2 only. 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

Expand All @@ -125,7 +125,7 @@ When a user asks you to create or add a feature flag that does not exist on Verc

2. **Register the flag with Vercel**: Run `vercel flags create <flag-key> --kind boolean --description "<description>"`.

Before running `vercel flags create`, verify the project is linked (`.vercel` directory). If missing, run `vercel link` first.
Target the project as described in [Project targeting](#project-targeting).

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`.

Expand All @@ -152,7 +152,7 @@ When a user asks you to create or add a feature flag that does not exist on Verc

## 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.
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. For a [CLI-only request](#cli-only-flag-management), run step 2 only.

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 <flag-key>`. Note the kind, the variants (value and label), the description, and what each environment serves.
Expand All @@ -174,6 +174,16 @@ Use this flow when the flag was created in the dashboard or by someone else, for
```
5. **Use the flag** as in [Create a flag](#create-a-flag) step 5.

## CLI-only flag management

Managing remote flags with `vercel flags` requires an authenticated CLI, but not SDK packages, Toolbar, Flags Explorer, or `.env.local`. For a CLI-only request, skip app setup and code changes.

CLI authentication is separate from the app's OIDC or SDK key. Pull local credentials only when the app needs local SDK evaluation, not to prepare a CLI flag command.

### Project targeting

Use `--project <name-or-id>` and `--scope <team>` to select the target without a local link. If the CLI rejects `--project`, upgrade it first (`pnpm i -g vercel`). Without these options the commands use the linked project: run `vercel project inspect --non-interactive` and check the reported owner and project name; a `.vercel/` directory alone does not prove a link. If it reports `link_required`, the project is not linked. If the user named a project or team and the output differs, stop and ask instead of relinking.

## 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. `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.
Expand Down
6 changes: 3 additions & 3 deletions skills/flags-sdk/references/providers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@ pnpm i flags @flags-sdk/vercel

### Setup

> **Prerequisite**: The `vercel flags` commands require the Vercel CLI to be installed and authenticated. If the Vercel CLI is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel <command> --help` in the meantime.
> **Prerequisite**: The Vercel CLI must be installed and authenticated. If it is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel <command> --help` in the meantime.

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.
The following steps integrate a flag into an app and need a linked project for `vercel env pull`; verify the link as described in [Project targeting](../SKILL.md#project-targeting). To only inspect or change remote flags, follow [CLI-only flag management](../SKILL.md#cli-only-flag-management) instead.

1. Create a flag in the Vercel dashboard or via CLI: `vercel flags create <flag-key> --kind boolean --description "<description>"`
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.
Expand Down Expand Up @@ -116,7 +116,7 @@ Outside Vercel, pass the SDK key: `createClient(process.env.FLAGS)`. Unlike `ver

### `vercel flags` CLI

Manage Vercel Flags from the terminal. Install, link, and `vercel env pull` requirements are in [Setup](#setup) above.
Manage Vercel Flags from the terminal with an authenticated CLI and a targeted project ([Project targeting](../SKILL.md#project-targeting)). SDK installation and `vercel env pull` are app-development steps, not CLI prerequisites (see [Setup](#setup)).

For the current subcommand list and options, run `vercel flags --help` or `vercel flags <cmd> --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.

Expand Down
Loading