diff --git a/apps/docs/app/[lang]/home/[code]/install-command.tsx b/apps/docs/app/[lang]/home/[code]/install-command.tsx index 4b721aab..9cf9cb14 100644 --- a/apps/docs/app/[lang]/home/[code]/install-command.tsx +++ b/apps/docs/app/[lang]/home/[code]/install-command.tsx @@ -12,9 +12,10 @@ import { CommandPromptViewport, } from '@vercel/geistdocs/components/command-prompt'; import { useState } from 'react'; +import { INSTALL_SKILL_COMMAND } from '@/lib/agent-skill'; const COMMAND_FOR_HUMANS = 'npm install flags'; -const COMMAND_FOR_AGENTS = 'npx skills add vercel/flags@flags-sdk'; +const COMMAND_FOR_AGENTS = INSTALL_SKILL_COMMAND; const oneYearInSeconds = 31_536_000; type Audience = 'humans' | 'agents'; diff --git a/apps/docs/content/docs/agent-skill.mdx b/apps/docs/content/docs/agent-skill.mdx new file mode 100644 index 00000000..9aa7855d --- /dev/null +++ b/apps/docs/content/docs/agent-skill.mdx @@ -0,0 +1,23 @@ +--- +title: Install the Flags SDK agent skill +description: Install the Flags SDK agent skill so AI coding assistants follow the recommended workflows. +--- + +The Flags SDK ships an [agent skill](https://skills.sh/) that teaches AI coding assistants how to declare flags, wire adapters, use the `vercel flags` CLI, and apply patterns like precompute. + +## How to install + +```sh title="Terminal" +npx skills add vercel/flags@flags-sdk +``` + +Works with Cursor, Claude Code, Codex, and other assistants that support the skills standard. + +## What the skill covers + +- Declaring typed flags with `flag()` in Next.js and SvelteKit +- Connecting providers through adapters (Vercel Flags, Statsig, LaunchDarkly, and others) +- Managing Vercel Flags with the `vercel flags` CLI +- Precompute, identify/dedupe, and Flags Explorer setup + +After install, ask your assistant to add a feature flag or connect a provider. The skill steers the assistant through the Flags SDK workflow. diff --git a/apps/docs/content/docs/api-reference/core/core.mdx b/apps/docs/content/docs/api-reference/core/core.mdx index 69775d32..5514aa0c 100644 --- a/apps/docs/content/docs/api-reference/core/core.mdx +++ b/apps/docs/content/docs/api-reference/core/core.mdx @@ -3,6 +3,8 @@ title: 'flags' description: 'The `flags` package provides the core functionality for integrating with Vercel.' --- +> **Flags SDK agent skill:** Install with `npx skills add vercel/flags@flags-sdk` so your AI coding assistant follows the recommended workflows. See the [agent skill guide](/docs/agent-skill). + ### `verifyAccess` A method for verifying access to your flags endpoint based on encrypted tokens (JWEs) generated by the SDK functions documented below. diff --git a/apps/docs/content/docs/frameworks/next/index.mdx b/apps/docs/content/docs/frameworks/next/index.mdx index f040cf27..2ef041f0 100644 --- a/apps/docs/content/docs/frameworks/next/index.mdx +++ b/apps/docs/content/docs/frameworks/next/index.mdx @@ -10,8 +10,8 @@ Add feature flags and A/B tests to your application with the Flags SDK, a free, - Works with any flag provider or custom setup. - Compatible with App Router, Pages Router, and Middleware. - - Add Flags SDK to my existing Next.js app. Create a `flags.ts` file with a typed feature flag using `flags/next`, use the flag in an App Router page or Pages Router page based on my app structure, add the Flags Explorer discovery endpoint at `app/.well-known/vercel/flags/route.ts`, and run the relevant type checks or build when finished. + + Install the Flags SDK agent skill with `npx skills add vercel/flags@flags-sdk` if it is not already installed. Then add Flags SDK to my existing Next.js app. Create a `flags.ts` file with a typed feature flag using `flags/next`, use the flag in an App Router page or Pages Router page based on my app structure, add the Flags Explorer discovery endpoint at `app/.well-known/vercel/flags/route.ts`, and run the relevant type checks or build when finished. ## Installation @@ -22,11 +22,7 @@ Install the Flags SDK using your preferred package manager: npm install flags ``` -If you use an AI coding assistant, we recommend installing the Flags SDK agent skill: - -```sh title="Terminal" -npx skills add vercel/flags --skill flags-sdk -``` +> **Flags SDK agent skill:** Install with `npx skills add vercel/flags@flags-sdk` so your AI coding assistant follows the recommended workflows. See the [agent skill guide](/docs/agent-skill). ## Declaring a feature flag diff --git a/apps/docs/content/docs/frameworks/next/precompute.mdx b/apps/docs/content/docs/frameworks/next/precompute.mdx index f7c2e119..b896cab5 100644 --- a/apps/docs/content/docs/frameworks/next/precompute.mdx +++ b/apps/docs/content/docs/frameworks/next/precompute.mdx @@ -6,8 +6,8 @@ description: Using the precompute pattern in Next.js This page shows how to implement the precompute pattern in Next.js to keep pages static, even when multiple feature flags are used on a single page, or even when feature flags are used across multiple pages. Ensure you've read about the general precompute concept to understand the pattern and benefits: - - Implement precomputed feature flags in my Next.js app. Add a `FLAGS_SECRET`, group the relevant `flags/next` declarations, call `precompute` from Proxy to rewrite requests with the generated code, update the destination route to read precomputed values from `[code]`, generate static params or use ISR for variants, and run the relevant type checks or build when finished. + + Install the Flags SDK agent skill with `npx skills add vercel/flags@flags-sdk` if it is not already installed. Then implement precomputed feature flags in my Next.js app. Add a `FLAGS_SECRET`, group the relevant `flags/next` declarations, call `precompute` from Proxy to rewrite requests with the generated code, update the destination route to read precomputed values from `[code]`, generate static params or use ISR for variants, and run the relevant type checks or build when finished. diff --git a/apps/docs/content/docs/frameworks/sveltekit/index.mdx b/apps/docs/content/docs/frameworks/sveltekit/index.mdx index 2cd764b8..26edc9ca 100644 --- a/apps/docs/content/docs/frameworks/sveltekit/index.mdx +++ b/apps/docs/content/docs/frameworks/sveltekit/index.mdx @@ -5,8 +5,8 @@ description: Using the Flags SDK in SvelteKit [SvelteKit](https://svelte.dev/docs/kit/introduction) is a framework for building web applications with [Svelte](https://svelte.dev/). The Flags SDK supports SvelteKit out of the box. - - Add Flags SDK to my existing SvelteKit app. Configure `FLAGS_SECRET`, install and wire the Vercel Toolbar for local development, create a typed flag in `src/lib/flags.ts` using `flags/sveltekit`, add the server hook with `createHandle`, use the flag from server and client code where appropriate, and run the relevant type checks or build when finished. + + Install the Flags SDK agent skill with `npx skills add vercel/flags@flags-sdk` if it is not already installed. Then add Flags SDK to my existing SvelteKit app. Configure `FLAGS_SECRET`, install and wire the Vercel Toolbar for local development, create a typed flag in `src/lib/flags.ts` using `flags/sveltekit`, add the server hook with `createHandle`, use the flag from server and client code where appropriate, and run the relevant type checks or build when finished. A minimal feature flag declaration for SvelteKit looks like this: @@ -30,6 +30,8 @@ Install the Vercel CLI using the following command: npm i -g vercel@latest ``` +> **Flags SDK agent skill:** Install with `npx skills add vercel/flags@flags-sdk` so your AI coding assistant follows the recommended workflows. See the [agent skill guide](/docs/agent-skill). + ## Set up SvelteKit application 1. Set up your SvelteKit application: @@ -117,12 +119,6 @@ npm i -g vercel@latest npm i flags ``` - If you use an AI coding assistant, we recommend installing the Flags SDK agent skill: - - ```sh - npx skills add vercel/flags --skill flags-sdk - ``` - 2. Create your first feature flag by importing the `flag` method from `flags/sveltekit`: ```ts title="src/lib/flags.ts" diff --git a/apps/docs/content/docs/frameworks/sveltekit/precompute.mdx b/apps/docs/content/docs/frameworks/sveltekit/precompute.mdx index 750d9e07..b4466343 100644 --- a/apps/docs/content/docs/frameworks/sveltekit/precompute.mdx +++ b/apps/docs/content/docs/frameworks/sveltekit/precompute.mdx @@ -7,8 +7,8 @@ description: Using the precompute pattern in SvelteKit This page shows how to implement the precompute pattern in Next.js to keep pages static, even when multiple feature flags are used on a single page, or even when feature flags are used across multiple pages. Ensure you've read about the general precompute concept to understand the pattern and benefits: - - Implement precomputed feature flags in my SvelteKit app. Add `FLAGS_SECRET`, group the relevant `flags/sveltekit` declarations, add server-side precompute logic, use SvelteKit `reroute` for client navigations, use Vercel Routing Middleware for full page requests, update the `[code]` route to read precomputed values, configure prerendering or ISR for variants, and run the relevant checks when finished. + + Install the Flags SDK agent skill with `npx skills add vercel/flags@flags-sdk` if it is not already installed. Then implement precomputed feature flags in my SvelteKit app. Add `FLAGS_SECRET`, group the relevant `flags/sveltekit` declarations, add server-side precompute logic, use SvelteKit `reroute` for client navigations, use Vercel Routing Middleware for full page requests, update the `[code]` route to read precomputed values, configure prerendering or ISR for variants, and run the relevant checks when finished. diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json index 80308aed..f73d79b4 100644 --- a/apps/docs/content/docs/meta.json +++ b/apps/docs/content/docs/meta.json @@ -2,6 +2,7 @@ "pages": [ "frameworks/next", "frameworks/sveltekit", + "agent-skill", "principles", "providers", "api-reference" diff --git a/apps/docs/content/docs/providers/custom-adapters.mdx b/apps/docs/content/docs/providers/custom-adapters.mdx index 472fe548..f181b186 100644 --- a/apps/docs/content/docs/providers/custom-adapters.mdx +++ b/apps/docs/content/docs/providers/custom-adapters.mdx @@ -9,14 +9,15 @@ it is also possible to write a custom adapter in case we don't list your provider or in case you have an in-house solution for feature flags. - - Create a custom Flags SDK adapter for my feature flag provider. Implement an - adapter factory that initializes or accepts my provider client, define - `origin` and `decide` behavior, optionally implement `bulkDecide` (and set - `adapterId`) for batch evaluation, expose a default adapter when appropriate, - use the adapter from typed flag declarations, preserve Edge Runtime - compatibility where possible, and run the relevant tests or build when - finished. + + Install the Flags SDK agent skill with `npx skills add vercel/flags@flags-sdk` if it + is not already installed. Then create a custom Flags SDK adapter for my feature + flag provider. Implement an adapter factory that initializes or accepts my + provider client, define `origin` and `decide` behavior, optionally implement + `bulkDecide` (and set `adapterId`) for batch evaluation, expose a default + adapter when appropriate, use the adapter from typed flag declarations, + preserve Edge Runtime compatibility where possible, and run the relevant tests + or build when finished. Adapters conceptually replace the `decide` and `origin` parts of a flag declaration. diff --git a/apps/docs/content/docs/providers/index.mdx b/apps/docs/content/docs/providers/index.mdx index f3bca0ca..b30e4091 100644 --- a/apps/docs/content/docs/providers/index.mdx +++ b/apps/docs/content/docs/providers/index.mdx @@ -8,6 +8,8 @@ using an adapter. We publish adapters for the most common providers, but it is also possible to write a [custom adapter](/providers/custom-adapters) in case we don't list your provider or in case you have an in-house solution for feature flags. +> **Flags SDK agent skill:** Install with `npx skills add vercel/flags@flags-sdk` so your AI coding assistant follows the recommended workflows. See the [agent skill guide](/docs/agent-skill). + ## Featured providers Featured providers offer fast setup using [Vercel Marketplace](https://vercel.com/marketplace/category/experimentation), diff --git a/apps/docs/content/docs/providers/openfeature/index.mdx b/apps/docs/content/docs/providers/openfeature/index.mdx index 31d0435a..751c8021 100644 --- a/apps/docs/content/docs/providers/openfeature/index.mdx +++ b/apps/docs/content/docs/providers/openfeature/index.mdx @@ -4,8 +4,8 @@ title: 'OpenFeature' [OpenFeature](https://openfeature.dev/) is an open specification that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool or in-house solution. The Flags SDK OpenFeature adapter allows you to use the Flags SDK with any OpenFeature provider. - - Integrate my OpenFeature provider with Flags SDK. Install `@flags-sdk/openfeature` and `@openfeature/server-sdk`, configure my OpenFeature provider and client, create a `createOpenFeatureAdapter` instance, add a request-aware `identify` function for the evaluation context, declare typed flags with default values, add Flags Explorer support if applicable, and run the relevant type checks or build when finished. + + Install the Flags SDK agent skill with `npx skills add vercel/flags@flags-sdk` if it is not already installed. Then integrate my OpenFeature provider with Flags SDK. Install `@flags-sdk/openfeature` and `@openfeature/server-sdk`, configure my OpenFeature provider and client, create a `createOpenFeatureAdapter` instance, add a request-aware `identify` function for the evaluation context, declare typed flags with default values, add Flags Explorer support if applicable, and run the relevant type checks or build when finished. diff --git a/apps/docs/content/docs/providers/vercel.mdx b/apps/docs/content/docs/providers/vercel.mdx index a8de3155..5d81307d 100644 --- a/apps/docs/content/docs/providers/vercel.mdx +++ b/apps/docs/content/docs/providers/vercel.mdx @@ -4,8 +4,8 @@ title: 'Vercel Flags' Vercel Flags is a feature flag provider built into Vercel's platform, allowing you to manage flags directly in your Vercel projects. The `@flags-sdk/vercel` package connects the Flags SDK to Vercel Flags. - - Connect my existing Flags SDK setup to Vercel Flags. Install `@flags-sdk/vercel`, pull the `FLAGS` and `FLAGS_SECRET` environment variables, update my flag declarations to use `vercelAdapter`, add or reuse an `identify` function for targeting entities, create the Flags Explorer discovery endpoint, and run the relevant type checks or build when finished. + + Install the Flags SDK agent skill with `npx skills add vercel/flags@flags-sdk` if it is not already installed. Then connect my existing Flags SDK setup to Vercel Flags. Install `@flags-sdk/vercel`, pull the `FLAGS` and `FLAGS_SECRET` environment variables, update my flag declarations to use `vercelAdapter`, add or reuse an `identify` function for targeting entities, create the Flags Explorer discovery endpoint, and run the relevant type checks or build when finished. diff --git a/apps/docs/geistdocs.tsx b/apps/docs/geistdocs.tsx index f5c1c428..27a8d8eb 100644 --- a/apps/docs/geistdocs.tsx +++ b/apps/docs/geistdocs.tsx @@ -34,6 +34,7 @@ export const suggestions = [ "What frameworks are supported by Flags SDK?", "Which providers are supported by Flags SDK?", "How do I precompute flags?", + "How do I install the Flags SDK agent skill?", ]; export const title = "Flags SDK Documentation"; @@ -60,6 +61,11 @@ export const agent = { href: `https://github.com/${github.owner}/${github.repo}`, description: "Source repository for Flags SDK", }, + { + label: "Flags SDK agent skill", + href: "https://flags-sdk.dev/docs/agent-skill", + description: "Install with npx skills add vercel/flags@flags-sdk", + }, ], } satisfies GeistdocsAgentReadinessConfig; diff --git a/apps/docs/lib/agent-skill.ts b/apps/docs/lib/agent-skill.ts new file mode 100644 index 00000000..53fbb86d --- /dev/null +++ b/apps/docs/lib/agent-skill.ts @@ -0,0 +1 @@ +export const INSTALL_SKILL_COMMAND = 'npx skills add vercel/flags@flags-sdk'; diff --git a/apps/docs/next.config.ts b/apps/docs/next.config.ts index 07744dff..0c562342 100644 --- a/apps/docs/next.config.ts +++ b/apps/docs/next.config.ts @@ -184,6 +184,11 @@ const config: NextConfig = { destination: "/docs/api-reference/:path*", permanent: true, }, + { + source: "/agent-skill", + destination: "/docs/agent-skill", + permanent: true, + }, ]; }, };