LaunchDarkly SDK Onboarding

Prerequisites

• npx

  : Available on PATH when using

  npx skills add

  to install companion skills (see Step 3).
• LaunchDarkly account (outset only): Early in onboarding -- right after the Kickoff roadmap if the log does not already say -- ask only whether the user already has a LaunchDarkly account (they can sign in at https://app.launchdarkly.com). Do not ask in the same turn for SDK keys, client-side IDs, mobile keys, API access tokens, or whether keys are in env; defer those until the step that needs them (below).
  • If they do not have an account yet: Point them to https://app.launchdarkly.com/signup?source=agent. Continue with repo exploration, agent detection, and companion skills where those do not require LaunchDarkly API access; MCP OAuth and SDK work wait on account access.
  • If they have an account: Proceed through the workflow. Still do not prompt for SDK key material until Step 5 Apply code changes (or until run if they prefer to paste into env later).
• Keys and tokens (defer -- do not bundle with the account question): Collect these only when the path requires them -- never as part of the initial "do you have an account?" prompt.
  • Step 4 -- MCP: Hosted MCP uses OAuth; no API token or SDK key needed to configure it. Local

    npx

    MCP (federal/EU, etc.): API access token per mcp-configure and MCP Config Templates.
  • Step 5 -- SDK: SDK keys / client-side ID / mobile key when wiring env in Apply code changes, after the integration plan is confirmed.

    ldcli

    / REST for discovery: use

    ldcli login

    or an access token when you first run those commands, not at hello.
  • Key type must match the integration: server-side SDK -> SDK key; browser/client-side SDK -> Client-side ID; mobile -> Mobile key. Env variable names and bundler rules: Apply code changes.

npx

• get-environments

  -- list environments for a project; the response includes SDK keys, client-side IDs, and mobile keys per environment. Use this as the single source for all key types -- do not make separate requests for individual keys.

• create-feature-flag

  -- create the boolean flag for Step 6: Create Your First Feature Flag.

• update-feature-flag

  -- toggle or patch flag configuration during Step 6; see Create first feature flag for ldcli/API fallbacks.

list-feature-flags

get-feature-flag

get-flag-status-across-environments

Agent Behavior Directives

Progress Tracking

• Cursor: Use

  TodoWrite

  to create a todo for each step before beginning work. Update status as each step completes.
• Claude Code: Use

  TaskCreate

  to create a task for each step (or

  TodoWrite

  if native tasks are unavailable).
• Other agents: If your agent provides a native task list or progress tracking tool, use it. If not, present a numbered checklist in chat and update it after each step.

LAUNCHDARKLY_ONBOARDING.md

Decision Points

1. AskQuestion

   — call it with a

   prompt

   and

   options

   array

2. TaskAsk

   or equivalent structured-input tool
3. (fallback) If the tool call fails or no such tool exists, THEN render the question as numbered options in text and wait.

**D1 -- BLOCKING:** <instruction to call your question tool>
- question: "<the question>"
- options:
  - "<option A>" -> <what happens>
  - "<option B>" -> <what happens>
- STOP. Do not continue until the user selects an option.

User-Facing Communication

1. What we just did — one or two sentences summarizing the completed action and its result.
2. What we're doing next — a plain-English preview of the next step.
3. What you need to do (only when the user has a manual action) — a concrete instruction, not a vague label like "Your turn." Include where to perform the action (e.g. "in Cursor's integrated terminal," "in the project folder," "in your browser," "in macOS Terminal").

• Internal decision-point IDs (D1, D5, D7, etc.), step numbers as labels (e.g. "Step 5 -- detect"), or skill file names (e.g. "sdk-install/apply/SKILL.md").
• Quoting or paraphrasing raw skill instructions, directive headings, or markdown from these files.
• Workflow-engine language ("BLOCKING," "STOP," "call your structured question tool," "proceed to the next nested skill").

• "Run this in the integrated terminal in your editor"
• "Run this from the project root in your terminal"
• "Open a terminal in the

  packages/api

  folder and run …"

npm install

Step Execution Rules

.env

LAUNCHDARKLY.md

Core Principles

1. Detect, don't guess: Inspect the repo for language, framework, and package manager.
2. Minimal changes: Add SDK code alongside existing code; don't restructure the project.
3. Match existing patterns: Follow env vars, config files, and initialization patterns already in use.
4. Validate end-to-end: Confirm the SDK is connected before treating the first flag as proof of success.
5. Paper trail: Keep the Step 0 onboarding log current so another agent or session can continue without re-deriving context.
6. Orient the user first: On a fresh onboarding request, show the Kickoff roadmap before substantive work so the user knows the full arc.
7. Stage credential questions: Confirm account at the outset; ask for SDK keys / tokens only in Step 4-5 when that step's skill says they are required (Prerequisites).
8. Deep-link to the dashboard: When generating LaunchDarkly dashboard URLs and the project key and/or environment key are known (from MCP tools, user input, or the onboarding log), construct the most specific URL possible instead of linking to a generic page. Use these patterns:

   What you need to show	URL pattern
   Project flags list	https://app.launchdarkly.com/projects/{projectKey}/flags
   Specific flag	https://app.launchdarkly.com/projects/{projectKey}/flags/{flagKey}
   Environment keys / SDK keys	https://app.launchdarkly.com/projects/{projectKey}/settings/environments/{envKey}/keys
   Project environments list	https://app.launchdarkly.com/projects/{projectKey}/settings/environments
   All projects	https://app.launchdarkly.com/projects

   Only generate deep links when the required keys are known from tool responses or confirmed user input. If they are unknown, use the most specific generic path available and tell the user how to navigate from there (e.g. "Open your project in the LaunchDarkly dashboard, then go to Settings > Environments to find your SDK key").

Kickoff: onboarding roadmap

Kickoff sequence (new run — before any numbered step)

1. Task list: Call your native task tool (Progress Tracking) and create one task per step for Steps 0 through 6 (seven tasks minimum — one for each numbered row in the table below). Do this before rendering the roadmap table so progress tracking is in place before you pause on D1.
2. Roadmap: Render the roadmap table below in the user-visible reply (adjust row wording only if an Edge case will obviously skip a step). The roadmap is a chat artifact only -- do not create a file for it unless the user asks.
3. D1: Call your structured question tool for the account question (see D1 below). Do not create or update

   LAUNCHDARKLY_ONBOARDING.md

   , explore the repo for Step 1, detect the agent for Step 2, or run

   npx

   (or any shell install) for Step 3 until the user has answered D1.

• Resuming: If

  LAUNCHDARKLY_ONBOARDING.md

  already exists, read it first per Step 0. Show the same roadmap with a Status column filled from the log, or a shorter "where we are" summary -- whichever keeps the user oriented. Refresh the task list to match the log if needed; if D1 (account status) is already recorded in the log, do not ask D1 again -- continue from the log's Next step.

LAUNCHDARKLY_ONBOARDING.md

docs/...

--agent

npx skills add

npx skills add ...

launchdarkly/agent-skills

launchdarkly-flag-*

LAUNCHDARKLY.md

• question: "Do you already have a LaunchDarkly account you can sign into?"
• options:
  • "Yes, I have an account" -> proceed through full workflow
  • "No / not yet" -> point to https://app.launchdarkly.com/signup?source=agent, continue Steps 1-3 only
• STOP. Do not write the question as text. Do not continue until the user selects an option.

Workflow

Step 0: Create or Refresh the Onboarding Log

1. Look for an existing log at the repo root:

   LAUNCHDARKLY_ONBOARDING.md

   . If the project keeps docs under

   docs/

   , prefer

   docs/LAUNCHDARKLY_ONBOARDING.md

   when that folder already exists and the root file is absent.
2. Create or update the log file. This is part of the onboarding workflow -- write it directly without asking for permission.
3. If resuming: read the log first, align with the stated next step, and only redo work the log marks incomplete or invalid.
4. What to write (update after each numbered step finishes or when something important changes):
   • Checklist: Steps 0-6 with status (

     not started

     /

     in progress

     /

     done

     /

     skipped

     + brief reason).
   • Context: coding agent id (once known), language/framework summary, monorepo target path if any, LaunchDarkly project key and environment key when known (never paste secrets or full SDK keys -- say "stored in env" or "user provided offline").
   • MCP: configured yes/no, hosted vs fallback, link to config path if relevant.
   • Commands run: e.g.

     npx skills add ...

     (no secrets).
   • Blockers / errors: what failed and what was tried.
   • Next step: single explicit step number and name (e.g. "Step 5: Install and Initialize the SDK").
5. After errors: append or edit the log with what broke and where you are resuming.

LAUNCHDARKLY.md

Step 1: Explore the Project

1. Identify language and framework. Check dependency files:

   package.json

   ,

   go.mod

   ,

   requirements.txt

   /

   pyproject.toml

   /

   Pipfile

   ,

   pom.xml

   /

   build.gradle

   ,

   Gemfile

   ,

   *.csproj

   /

   *.sln

   ,

   Cargo.toml

   , etc.
2. Check for existing LaunchDarkly usage. Search for

   launchdarkly

   ,

   ldclient

   ,

   ld-client

   ,

   LDClient

   ,

   @launchdarkly

   .
   • If already present: note SDK version and patterns; you may shorten or skip Step 5 per edge cases.
   • If not present: plan full SDK setup.
3. Identify environment type: server-side app, client SPA, mobile, edge, etc. -- this drives SDK choice.
4. Summarize to the user: language, framework, environment type, whether LD is already integrated.

Step 2: Detect the Agent Environment

npx skills add --agent

1. Check for indicators (in priority order — stop at the first strong match):
   • Cursor:

     .cursor/

     ,

     .cursorrules

     , or

     CURSOR_

     env vars
   • Claude Code:

     ~/.claude/

     ,

     CLAUDE.md

     , or

     CLAUDE_

     env vars
   • Windsurf:

     .windsurfrules

   • GitHub Copilot:

     .github/copilot/

   • Codex:

     ~/.codex/

     ,

     AGENTS.md

2. If multiple indicators are present, pick the one whose runtime you are currently executing inside (e.g. if you have access to Cursor-specific tools like

   AskQuestion

   or

   TodoWrite

   , you are in Cursor). If none of the indicators match, default to the agent whose tool surface you observe at runtime.
3. Remember the agent id for Step 3 (e.g.

   cursor

   ,

   claude-code

   ). Mention the detected agent briefly when presenting the Step 1/2 summary so the user can correct you if wrong, but do not block on a question.

Step 3: Install Companion Skills

launchdarkly/agent-skills

npx skills add launchdarkly/agent-skills --skill launchdarkly-flag-create launchdarkly-flag-discovery launchdarkly-flag-targeting launchdarkly-flag-cleanup -y --agent <detected-agent>

<detected-agent>

references/

Step 4: Configure the MCP Server

list-feature-flags

Step 5: Install and Initialize the SDK

Step 6: Create Your First Feature Flag

1. Follow Create first feature flag.
2. If the

   launchdarkly-flag-create

   skill (installed in Step 3) is available, you may use it for create/evaluation wiring only while still completing the verify/toggle checklist in Create first feature flag. Onboarding must remain completable without it.

npx skills add launchdarkly/agent-skills --skill launchdarkly-flag-create -y --agent <detected-agent>

Default follow-through (not numbered steps)

LAUNCHDARKLY.md

LAUNCHDARKLY.md

1. SDK Details -- which SDK(s) are installed, package names, key types, initialization files
2. Configuration -- env var names, how secrets are managed, bundler-specific conventions
3. Where to Find Things -- dashboard links with real project key substituted
4. How Feature Flags Work -- a language-specific code example showing flag evaluation in this project's stack (not a generic snippet -- use the same pattern the agent wired during Step 5)
5. Next Steps / Advanced Capabilities -- links to Percentage Rollouts, Targeting Rules, Experimentation, AI Configs, Guarded Rollouts, and Observability
6. AI Agent Integration -- MCP server setup for continued agent-driven flag management

LAUNCHDARKLY_ONBOARDING.md

LAUNCHDARKLY.md

LAUNCHDARKLY.md

LAUNCHDARKLY_ONBOARDING.md

docs/LAUNCHDARKLY_ONBOARDING.md

• Add editor-specific rules or skill hooks per Editor Rules and Skills. Write them directly -- this is part of the onboarding workflow.

Edge Cases

npx skills add

LAUNCHDARKLY_ONBOARDING.md

What NOT to Do

• Don't install an SDK without exploring the project and detecting the stack (Steps 1 and 5); keep the Step 0 log updated as you go.
• Don't upgrade, pin, or add non-LaunchDarkly dependencies (peer-deps, lockfile churn, "latest" bumps) to install or compile the SDK without explicit user approval -- see Apply -- Permission before changing other dependencies.
• Don't hardcode SDK keys in source code -- always use environment variables (see Apply code changes).
• Don't restructure the user's project or refactor unrelated code.
• Don't create flags before Step 5 (SDK install) completes.
• Don't write decision-point questions as chat text -- use your structured question tool (see Decision Points).

References

• Step 0 --

  LAUNCHDARKLY_ONBOARDING.md

  (working log; see Step 0)

• mcp-configure/SKILL.md -- hosted MCP, verify, edge cases (follow this first)
• MCP UI links -- HTTPS +

  command:

  links to open MCP settings per editor
• MCP Config Templates -- per-agent JSON; Local server via

  npx

  when hosted MCP is unavailable

• sdk-install/SKILL.md -- orchestrates detect -> plan -> apply (follow this first)
• Detect repository stack
• Generate integration plan
• Apply code changes

• Create first feature flag

• Onboarding Summary -- template for

  LAUNCHDARKLY.md

• Editor Rules and Skills

• SDK recipes
• SDK snippets

• github.com/launchdarkly/agent-skills --

  launchdarkly-flag-create

  ,

  launchdarkly-flag-discovery

  ,

  launchdarkly-flag-targeting

  ,

  launchdarkly-flag-cleanup