diff --git a/README.md b/README.md
index 660e91b..8db84ee 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,12 @@ Agent Skills are modular, text-based playbooks that teach an agent how to perfor
| `feature-flags/launchdarkly-flag-targeting` | Control targeting, rollouts, rules, and cross-environment config |
| `feature-flags/launchdarkly-flag-cleanup` | Safely remove flags from code using LaunchDarkly as the source of truth |
+### Onboarding
+
+| Skill | Description |
+|-------|-------------|
+| `onboarding/launchdarkly-sdk-onboarding` | Detect tech stack, install the right SDK, validate the connection, and create a first feature flag |
+
### AI Configs
| Skill | Description |
@@ -70,6 +76,10 @@ Roll out dark-mode to 25% of users in production
Remove the `new-checkout-flow` feature flag from this codebase
```
+```
+Onboard me to LaunchDarkly — set up the SDK in this project
+```
+
## Install via skills.sh CLI
```bash
diff --git a/skills.json b/skills.json
index 941bbad..3f53aa8 100644
--- a/skills.json
+++ b/skills.json
@@ -123,6 +123,23 @@
"devops",
"mcp"
]
+ },
+ {
+ "name": "launchdarkly-sdk-onboarding",
+ "description": "Onboard a project to LaunchDarkly by detecting the tech stack, installing the right SDK, initializing it, validating the connection, and creating a first feature flag. Use when the user wants to add LaunchDarkly to their project, integrate an SDK, or says 'onboard me'.",
+ "path": "skills/onboarding/launchdarkly-sdk-onboarding",
+ "version": "0.1.0",
+ "license": "Apache-2.0",
+ "compatibility": "Requires LaunchDarkly API access token. Optionally uses the LaunchDarkly MCP server for flag creation and validation.",
+ "tags": [
+ "launchdarkly",
+ "onboarding",
+ "sdk-integration",
+ "feature-flags",
+ "getting-started",
+ "setup",
+ "mcp"
+ ]
}
]
}
diff --git a/skills/onboarding/launchdarkly-sdk-onboarding/README.md b/skills/onboarding/launchdarkly-sdk-onboarding/README.md
new file mode 100644
index 0000000..a73bf54
--- /dev/null
+++ b/skills/onboarding/launchdarkly-sdk-onboarding/README.md
@@ -0,0 +1,37 @@
+# LaunchDarkly SDK Onboarding
+
+Onboard a project to LaunchDarkly by detecting the tech stack, installing the correct SDK, initializing it, validating the connection, and creating a first feature flag.
+
+## When to Use
+
+Use this skill when a user wants to:
+- Add LaunchDarkly to their project
+- Integrate a LaunchDarkly SDK
+- Says "onboard me" or "set up LaunchDarkly"
+- Get started with feature flags in an existing codebase
+
+## Workflow
+
+1. **Detect** — Identify language, framework, package manager, and existing SDK usage
+2. **Plan** — Choose the correct SDK and generate a minimal integration plan
+3. **Apply** — Install the SDK dependency and add initialization code
+4. **Run** — Start the application and confirm SDK initialization
+5. **Validate** — Verify LaunchDarkly sees the SDK connection
+6. **First Flag** — Create a feature flag, evaluate it, and toggle it
+7. **Recover** — If any step fails, diagnose and resume
+
+## Supported SDKs
+
+### Server-Side
+Node.js, Python, Go, Java, Ruby, .NET, PHP, Rust, Erlang/Elixir
+
+### Client-Side
+React, Vue, JavaScript (browser), Node.js (Electron)
+
+### Mobile
+Swift/iOS, Android, Flutter, React Native
+
+## Requirements
+
+- LaunchDarkly account with an API access token
+- LaunchDarkly MCP server (optional, enhances flag creation and validation)
diff --git a/skills/onboarding/launchdarkly-sdk-onboarding/SKILL.md b/skills/onboarding/launchdarkly-sdk-onboarding/SKILL.md
new file mode 100644
index 0000000..9e2f5a8
--- /dev/null
+++ b/skills/onboarding/launchdarkly-sdk-onboarding/SKILL.md
@@ -0,0 +1,174 @@
+---
+name: launchdarkly-sdk-onboarding
+description: "Onboard a project to LaunchDarkly by detecting the tech stack, installing the right SDK, initializing it, validating the connection, and creating a first feature flag. Use when the user wants to add LaunchDarkly to their project, integrate an SDK, or says 'onboard me'."
+license: Apache-2.0
+compatibility: Requires LaunchDarkly API access token. Optionally uses the LaunchDarkly MCP server for flag creation and validation.
+metadata:
+ author: launchdarkly
+ version: "0.1.0"
+---
+
+# LaunchDarkly SDK Onboarding
+
+You're using a skill that will guide you through adding LaunchDarkly to a project. Your job is to detect the tech stack, choose the right SDK, install and initialize it, validate the connection, and help the user create their first feature flag.
+
+## Account and Credentials
+
+Before starting the SDK integration, ensure the user has access to LaunchDarkly:
+
+1. **Check for existing credentials**: Ask the user if they have a LaunchDarkly access token or SDK key.
+2. **If the user has an account**: Use the LaunchDarkly API (`GET /api/v2/projects/PROJECT_KEY`) or `ldcli` to retrieve the project, environment, and SDK key automatically. Ask the user for permission before reading the SDK key.
+3. **If the user does NOT have an account**: Prompt them to sign up at https://launchdarkly.com or log in via `ldcli login`. Guide them through creating their first project and environment if needed.
+4. **SDK key types**: The project response will contain the keys you need. Use the correct key type for the SDK:
+ - **SDK Key** for server-side SDKs
+ - **Client-side ID** for client-side/browser SDKs
+ - **Mobile Key** for mobile SDKs
+
+## Core Principles
+
+1. **Detect, don't guess**: Always inspect the repo to determine the language, framework, and package manager. Never assume.
+2. **Minimal changes**: Add SDK code alongside existing code. Don't restructure or refactor the user's project.
+3. **Match existing patterns**: If the project already has conventions (env vars, config files, initialization patterns), follow them.
+4. **Validate end-to-end**: Don't stop at installation. Confirm the SDK is actually connected to LaunchDarkly.
+
+## Workflow
+
+Follow these steps in order. If any step fails, go to [Step 10: Recover](#step-10-recover).
+
+### Step 1: Detect Repository Stack
+
+Before doing anything, understand the project.
+
+1. Inspect the repo for language, framework, and package manager
+2. Check for existing LaunchDarkly SDK usage
+3. Identify the application entrypoint
+
+See [Detect Repository Stack](references/1.0-detect.md) for detailed instructions.
+
+### Step 2: Generate Integration Plan
+
+Based on what you found, choose the correct SDK and plan the integration.
+
+1. Match the detected stack to an SDK using the [SDK Recipes](references/sdk-recipes.md)
+2. Identify which files need to change
+3. Determine if this is a server-side, client-side, or mobile integration
+
+See [Generate Integration Plan](references/1.1-plan.md) for detailed instructions.
+
+### Step 3: Install Dependencies and Apply Code
+
+Install the SDK and add initialization code to the project.
+
+1. Install the SDK package using the project's package manager
+2. Add SDK initialization code to the application entrypoint
+3. Configure the SDK key via environment variables
+
+See [Apply Code Changes](references/1.2-apply.md) for detailed instructions.
+
+### Step 4: Start the Application
+
+Verify the application runs with the SDK integrated.
+
+1. Start the application using its standard run command
+2. Confirm there are no import or initialization errors
+3. Look for SDK initialization success in logs
+
+See [Start the Application](references/1.3-run.md) for detailed instructions.
+
+### Step 5: Validate SDK Connection
+
+Confirm that LaunchDarkly sees the SDK connection.
+
+1. Check the SDK is active using the LaunchDarkly API or MCP
+2. Verify the connection in the LaunchDarkly dashboard
+
+See [Validate SDK Connection](references/1.4-validate.md) for detailed instructions.
+
+### Step 6: Create Your First Feature Flag
+
+Help the user create and evaluate a feature flag.
+
+1. Create a boolean feature flag
+2. Add flag evaluation code to the project
+3. Toggle the flag and observe the change
+
+See [Create First Feature Flag](references/1.5-first-flag.md) for detailed instructions.
+
+### Step 7: Offer MCP Server Installation
+
+After the SDK is working and the first flag is toggled, check if the LaunchDarkly MCP server is installed in the user's environment.
+
+1. Check if `@launchdarkly/mcp-server` is configured in the user's MCP settings
+2. If not installed, ask the user if they want to set it up
+3. If yes, guide them through installation and configuration
+
+The MCP server enables richer agent-driven workflows like flag management, targeting rules, and experimentation — all without leaving the editor.
+
+See [MCP Server Setup](references/1.7-mcp-setup.md) for detailed instructions.
+
+### Step 8: Leave Behind a Setup Summary
+
+Generate a `LAUNCHDARKLY.md` document in the user's repository with:
+
+1. How LaunchDarkly was set up (SDK, package, init file, key configuration)
+2. Links to the project's flags dashboard, environments, and SDK docs
+3. Suggested next steps: percentage rollouts, targeting rules, experimentation, AI configs, guarded rollouts, observability
+4. Useful `ldcli` commands for flag management
+
+This gives the user and their team a permanent reference. Ask the user for permission before committing it.
+
+See [Onboarding Summary](references/1.8-summary.md) for the template and detailed instructions.
+
+### Step 9: Install Editor Rules for Flag Management
+
+Leave behind editor-specific rules so the user's AI agent knows how to work with LaunchDarkly going forward.
+
+1. Detect which editor the user is using (Cursor, Claude Code, GitHub Copilot, etc.)
+2. Create the appropriate rules file with LaunchDarkly best practices and flag management skills
+3. Ask the user for permission before committing
+
+The rules cover: when to use flags, how to evaluate them, SDK key safety, flag hygiene, and links to documentation.
+
+See [Editor Rules and Skills](references/1.9-editor-rules.md) for editor-specific templates.
+
+### Step 10: Recover
+
+If any step fails, diagnose the issue and resume.
+
+1. Identify the failed step and error
+2. Choose a recovery action
+3. Resume the workflow
+
+See [Recovery Procedures](references/1.6-recover.md) for detailed instructions.
+
+## Edge Cases
+
+| Situation | Action |
+|-----------|--------|
+| SDK already installed | Skip to Step 4 (Run) or Step 5 (Validate) |
+| Multiple languages in repo | Ask the user which target to integrate first (frontend vs backend vs mobile) |
+| Monorepo | Identify the specific package/service to integrate and work within that subtree |
+| No package manager detected | Ask the user which SDK they want to install and provide manual install instructions |
+| Application won't start | Use the recover step to diagnose; don't block on run if the user confirms the app runs separately |
+
+## What NOT to Do
+
+- Don't install an SDK without detecting the stack first
+- Don't hardcode SDK keys in source code — always use environment variables
+- Don't restructure the user's project or refactor existing code
+- Don't skip validation — always confirm the SDK is connected
+- Don't create flags before the SDK connection is validated
+
+## References
+
+- [Detect Repository Stack](references/1.0-detect.md) — How to identify language, framework, and existing SDK usage
+- [Generate Integration Plan](references/1.1-plan.md) — How to choose the right SDK and plan changes
+- [Apply Code Changes](references/1.2-apply.md) — How to install dependencies and add initialization code
+- [Start the Application](references/1.3-run.md) — How to run the app and confirm SDK initialization
+- [Validate SDK Connection](references/1.4-validate.md) — How to verify LaunchDarkly sees the SDK
+- [Create First Feature Flag](references/1.5-first-flag.md) — How to create, evaluate, and toggle a flag
+- [Recovery Procedures](references/1.6-recover.md) — How to diagnose failures and resume
+- [MCP Server Setup](references/1.7-mcp-setup.md) — How to install the LaunchDarkly MCP server
+- [Onboarding Summary](references/1.8-summary.md) — Template for the setup reference document
+- [Editor Rules and Skills](references/1.9-editor-rules.md) — Editor-specific rules for ongoing flag management
+- [SDK Recipes](references/sdk-recipes.md) — Detection patterns, install commands, and init snippets for all SDKs
diff --git a/skills/onboarding/launchdarkly-sdk-onboarding/marketplace.json b/skills/onboarding/launchdarkly-sdk-onboarding/marketplace.json
new file mode 100644
index 0000000..454e5ca
--- /dev/null
+++ b/skills/onboarding/launchdarkly-sdk-onboarding/marketplace.json
@@ -0,0 +1,21 @@
+{
+ "name": "launchdarkly-sdk-onboarding",
+ "description": "Onboard a project to LaunchDarkly by detecting the tech stack, installing the right SDK, and validating the connection",
+ "version": "0.1.0",
+ "author": "LaunchDarkly",
+ "repository": "https://github.com/launchdarkly/agent-skills",
+ "skills": ["./"],
+ "tags": [
+ "launchdarkly",
+ "onboarding",
+ "sdk-integration",
+ "feature-flags",
+ "getting-started",
+ "setup",
+ "mcp"
+ ],
+ "requirements": {},
+ "optional": {
+ "mcp-servers": ["@launchdarkly/mcp-server"]
+ }
+}
diff --git a/skills/onboarding/launchdarkly-sdk-onboarding/references/1.0-detect.md b/skills/onboarding/launchdarkly-sdk-onboarding/references/1.0-detect.md
new file mode 100644
index 0000000..644f843
--- /dev/null
+++ b/skills/onboarding/launchdarkly-sdk-onboarding/references/1.0-detect.md
@@ -0,0 +1,118 @@
+---
+title: Detect Repository Stack
+description: Inspect the repository to identify languages, frameworks, package managers, entrypoints, and existing SDK usage
+---
+
+# Detect Repository Stack
+
+Before installing anything, you must understand the project. This step identifies what the project is built with and whether LaunchDarkly is already present.
+
+## What to Detect
+
+### 1. Language and Framework
+
+Look for these files to identify the stack:
+
+| File | Language/Framework |
+|------|--------------------|
+| `package.json` | JavaScript/TypeScript (check for React, Next.js, Vue, Angular, Express, React Native, Electron, etc.) |
+| `requirements.txt`, `pyproject.toml`, `Pipfile`, `setup.py` | Python (check for Django, Flask, FastAPI) |
+| `go.mod` | Go (check for Gin, Echo, Fiber, Chi) |
+| `pom.xml`, `build.gradle`, `build.gradle.kts` | Java/Kotlin (check for Spring, Quarkus, Android) |
+| `Gemfile` | Ruby (check for Rails, Sinatra) |
+| `*.csproj`, `*.sln`, `*.fsproj` | .NET/C# (check for ASP.NET, MAUI, Xamarin, WPF, UWP) |
+| `composer.json` | PHP (check for Laravel, Symfony) |
+| `Cargo.toml` | Rust (check for Actix, Axum, Rocket) |
+| `pubspec.yaml` | Flutter/Dart |
+| `Package.swift`, `Podfile`, `*.xcodeproj` | Swift/iOS |
+| `AndroidManifest.xml` | Android (also check `build.gradle` for `com.android`) |
+| `rebar.config`, `mix.exs` | Erlang/Elixir |
+| `CMakeLists.txt`, `Makefile` (with C/C++ patterns) | C/C++ (check for `#include` patterns) |
+| `*.cabal`, `stack.yaml` | Haskell |
+| `*.lua`, `rockspec` | Lua |
+| `manifest`, `*.brs` | Roku (BrightScript) |
+| `wrangler.toml` | Cloudflare Workers (edge SDK) |
+| `vercel.json` with edge functions | Vercel Edge (edge SDK) |
+
+Read the dependency file to identify the specific framework. For `package.json`, check both `dependencies` and `devDependencies`.
+
+**If you cannot identify the language or framework**, ask the user which SDK they want to use. Present the list of available SDKs from the [SDK Recipes](sdk-recipes.md) and let them choose.
+
+### 2. Package Manager
+
+Identify how the project installs dependencies:
+
+| Indicator | Package Manager |
+|-----------|----------------|
+| `package-lock.json` | npm |
+| `yarn.lock` | yarn |
+| `pnpm-lock.yaml` | pnpm |
+| `bun.lockb` | bun |
+| `Pipfile.lock` | pipenv |
+| `poetry.lock` | poetry |
+| `go.sum` | go modules |
+| `Gemfile.lock` | bundler |
+
+Use the detected package manager for all install commands. If multiple lock files exist, prefer the one that was most recently modified.
+
+### 3. Application Entrypoint
+
+Find the main file where the application starts. Common patterns:
+
+- **Node.js (server)**: Check `package.json` `"main"` field, or look for `index.js`, `server.js`, `app.js`, `src/index.ts`
+- **Python**: Look for `app.py`, `main.py`, `manage.py`, `wsgi.py`, or the `[tool.poetry.scripts]` section
+- **Go**: Look for `main.go` or `cmd/*/main.go`
+- **Java**: Search for `public static void main` or `@SpringBootApplication`
+- **Ruby**: Look for `config.ru`, `config/application.rb`
+- **React/Vue/Angular**: Look for `src/index.tsx`, `src/main.tsx`, `src/App.tsx`, `src/main.ts`
+- **React Native**: Look for `App.tsx`, `App.js`, `index.js` (with `AppRegistry.registerComponent`)
+- **JavaScript (browser)**: Look for `index.html`, `src/index.js`, or bundler entry in `webpack.config.js` / `vite.config.ts`
+- **Flutter**: Look for `lib/main.dart`
+- **Swift/iOS**: Look for `AppDelegate.swift`, `SceneDelegate.swift`, or `@main` struct
+- **Android**: Look for `MainActivity.java` or `MainActivity.kt`
+
+### 4. Existing LaunchDarkly SDK
+
+Search the codebase for existing LaunchDarkly usage:
+
+```
+Search for: launchdarkly, ldclient, ld-client, LDClient, @launchdarkly, launchdarkly-
+```
+
+Check:
+- Is the SDK already in the dependency file?
+- Is there initialization code?
+- Is it properly configured or partially set up?
+- Are there already feature flag evaluations?
+
+## SDK Confirmation
+
+After detecting the stack, confirm the SDK choice with the user:
+
+- **If one SDK is clearly the right fit**: Tell the user which SDK you recommend and ask for confirmation before proceeding.
+- **If multiple SDKs could apply** (e.g., a Next.js project with both server and client components): Ask the user whether they want to integrate one or multiple SDKs, and which to start with.
+- **If you cannot determine the right SDK**: Present the available options from the [SDK Recipes](sdk-recipes.md) and ask the user to choose.
+
+## Decision Tree
+
+After detection and confirmation:
+
+- **SDK already installed and initialized** -> Skip to [Validate SDK Connection](1.4-validate.md)
+- **SDK installed but not initialized** -> Skip to [Apply Code Changes](1.2-apply.md) (just add init code)
+- **SDK not present** -> Continue to [Generate Integration Plan](1.1-plan.md)
+- **Multiple targets detected (e.g., frontend + backend)** -> Ask the user which to integrate first
+- **Language not detected** -> Ask the user which SDK they want to use
+
+## Status
+
+Before beginning, report:
+
+```
+[STATUS] Inspecting repository structure
+[STATUS] Detecting language and framework
+[STATUS] Checking for existing LaunchDarkly SDK
+```
+
+---
+
+**Upon completion, continue with:** [Generate Integration Plan](1.1-plan.md)
diff --git a/skills/onboarding/launchdarkly-sdk-onboarding/references/1.1-plan.md b/skills/onboarding/launchdarkly-sdk-onboarding/references/1.1-plan.md
new file mode 100644
index 0000000..66ddb32
--- /dev/null
+++ b/skills/onboarding/launchdarkly-sdk-onboarding/references/1.1-plan.md
@@ -0,0 +1,100 @@
+---
+title: Generate Integration Plan
+description: Choose the correct SDK based on detected stack and generate a minimal integration plan
+---
+
+# Generate Integration Plan
+
+Based on what you detected in the previous step, choose the right SDK and plan the minimal set of changes needed.
+
+## Choose the Right SDK
+
+Use the [SDK Recipes](sdk-recipes.md) reference to match the detected stack to an SDK. The key decision:
+
+| Project Type | SDK Type | Key Type |
+|-------------|----------|----------|
+| Backend API, server-rendered app, CLI tool | Server-side SDK | SDK Key |
+| Browser SPA (React, Vue, Angular, vanilla JS) | Client-side SDK | Client-side ID |
+| iOS or Android native app | Mobile SDK | Mobile Key |
+| React Native, Flutter | Mobile SDK | Mobile Key |
+| Electron desktop app | Client-side SDK (Node.js) | Client-side ID |
+| Cloudflare Workers, Vercel Edge, AWS Lambda@Edge | Edge SDK | SDK Key |
+| .NET client (MAUI, Xamarin, WPF, UWP) | Client-side SDK (.NET) | Mobile Key |
+| C/C++ client application | Client-side SDK (C/C++) | Mobile Key |
+| C/C++ server application | Server-side SDK (C/C++) | SDK Key |
+| Haskell server | Server-side SDK (Haskell) | SDK Key |
+| Lua server | Server-side SDK (Lua) | SDK Key |
+| Roku (BrightScript) | Client-side SDK (Roku) | Mobile Key |
+
+For a complete list of SDKs, see:
+- Server-side: https://launchdarkly.com/docs/sdk/server-side
+- Client-side: https://launchdarkly.com/docs/sdk/client-side
+- Edge: https://launchdarkly.com/docs/sdk/edge
+
+**Important distinctions:**
+- **Next.js**: Use server-side SDK for API routes/server components, React client SDK for client components. Start with whichever matches the user's primary use case.
+- **Node.js**: If it's a backend service (Express, Fastify, etc.), use the server-side SDK. There is also a [Node.js client SDK](https://launchdarkly.com/docs/sdk/client-side/node-js) for desktop/Electron apps.
+- **React**: If it's a standalone SPA, use `launchdarkly-react-client-sdk`. If it's part of Next.js, see above.
+- **.NET**: Use the server SDK for ASP.NET/backend services. Use the client SDK for MAUI, Xamarin, WPF, or UWP apps.
+
+## Plan the Changes
+
+Your integration plan should identify exactly:
+
+### 1. Files to Modify
+
+Use the information gathered during the [Detect step](1.0-detect.md) — specifically the detected package manager, dependency file, and application entrypoint:
+
+- **Dependency file**: The file identified during detection (e.g., `package.json`, `requirements.txt`, `go.mod`) — use the detected package manager to add the SDK
+- **Entrypoint file**: The application entrypoint identified during detection — where SDK initialization code will go
+- **Environment/config file**: `.env`, `.env.example`, or equivalent (for the SDK key) — follow the project's existing configuration pattern
+
+### 2. Code Changes
+
+For each file, describe the specific change:
+
+1. **Add SDK dependency** — the install command from the SDK recipe
+2. **Add SDK import** — the import statement at the top of the entrypoint
+3. **Add SDK initialization** — the init code, placed early in the application startup
+4. **Configure the SDK key** — via environment variable, never hardcoded
+
+### 3. Environment Variable Convention
+
+Check how the project handles configuration:
+- Does it use `.env` files? Add `LAUNCHDARKLY_SDK_KEY` (or `LAUNCHDARKLY_CLIENT_SIDE_ID` for client SDKs)
+- Does it use a config module? Add the key there
+- Does it read from process.env directly? Follow that pattern
+
+If a `.env.example` or `.env.sample` exists, plan to add the variable there too (with a placeholder value).
+
+## Present the Plan
+
+Before making any changes, summarize the plan to the user:
+
+```
+Integration Plan:
+- SDK: [SDK name] ([server/client/mobile]-side)
+- Package: [package name]
+- Install: [install command]
+- Files to change:
+ 1. [dependency file] — add SDK dependency
+ 2. [entrypoint file] — add import and initialization
+ 3. [env file] — add SDK key variable
+```
+
+Wait for user confirmation before proceeding, especially if:
+- Multiple SDKs could apply (ask which one)
+- The entrypoint is ambiguous (ask which file)
+- The project structure is unusual
+
+## Status
+
+```
+[STATUS] Selecting SDK for detected stack
+[STATUS] Identifying files to modify
+[STATUS] Generating integration plan
+```
+
+---
+
+**Upon completion, continue with:** [Apply Code Changes](1.2-apply.md)
diff --git a/skills/onboarding/launchdarkly-sdk-onboarding/references/1.2-apply.md b/skills/onboarding/launchdarkly-sdk-onboarding/references/1.2-apply.md
new file mode 100644
index 0000000..51796ac
--- /dev/null
+++ b/skills/onboarding/launchdarkly-sdk-onboarding/references/1.2-apply.md
@@ -0,0 +1,151 @@
+---
+title: Apply Code Changes
+description: Install the SDK dependency and add initialization code to the application entrypoint
+---
+
+# Apply Code Changes
+
+Now execute the integration plan. Install the SDK and add the minimal code needed to initialize it.
+
+## Step 1: Install the SDK Dependency
+
+Run the install command from the [SDK Recipes](sdk-recipes.md) using the project's package manager.
+
+**Examples:**
+```bash
+# Node.js (npm)
+npm install @launchdarkly/node-server-sdk --save
+
+# Python (pip)
+pip install launchdarkly-server-sdk
+
+# Go
+go get github.com/launchdarkly/go-server-sdk/v7
+
+# Ruby
+bundle add launchdarkly-server-sdk
+
+# .NET
+dotnet add package LaunchDarkly.ServerSdk
+```
+
+After installation, verify the dependency appears in the lock file or dependency manifest.
+
+## Step 2: Add the SDK Key to Environment Configuration
+
+**Never hardcode SDK keys in source code.**
+
+Add the appropriate environment variable:
+
+| SDK Type | Variable Name | Where to Get It |
+|----------|--------------|-----------------|
+| Server-side | `LAUNCHDARKLY_SDK_KEY` | LaunchDarkly > Project settings > Environments > SDK key |
+| Client-side | `LAUNCHDARKLY_CLIENT_SIDE_ID` | LaunchDarkly > Project settings > Environments > Client-side ID |
+| Mobile | `LAUNCHDARKLY_MOBILE_KEY` | LaunchDarkly > Project settings > Environments > Mobile key |
+
+Add to the project's environment configuration:
+
+1. If `.env` exists, add the variable there
+2. If `.env.example` or `.env.sample` exists, add a placeholder entry
+3. If the project uses a config module, add it there following existing patterns
+
+```bash
+# .env
+LAUNCHDARKLY_SDK_KEY=your-sdk-key-here
+```
+
+Tell the user they need to replace the placeholder with their actual key.
+
+## Step 3: Add SDK Initialization Code
+
+Add the import and initialization code to the application entrypoint. Place initialization **early** in the startup sequence, before any code that might need feature flags.
+
+### Key Principles
+
+1. **Import at the top** of the file with other imports
+2. **Initialize early** in the application lifecycle
+3. **Wait for initialization** before evaluating flags (most SDKs support this)
+4. **Handle errors** — log failures but don't crash the application
+5. **Match existing code style** — use the same patterns (async/await, callbacks, error handling) as the rest of the codebase
+
+### Server-Side Initialization Pattern
+
+```javascript
+// Node.js example
+const LaunchDarkly = require('@launchdarkly/node-server-sdk');
+
+const ldClient = LaunchDarkly.init(process.env.LAUNCHDARKLY_SDK_KEY);
+
+// Wait for initialization before serving requests
+await ldClient.waitForInitialization();
+console.log('LaunchDarkly SDK initialized successfully');
+```
+
+```python
+# Python example
+import ldclient
+from ldclient.config import Config
+
+ldclient.set_config(Config(os.environ['LAUNCHDARKLY_SDK_KEY']))
+client = ldclient.get()
+
+if client.is_initialized():
+ print('LaunchDarkly SDK initialized successfully')
+```
+
+```go
+// Go example
+import ld "github.com/launchdarkly/go-server-sdk/v7"
+
+ldClient, err := ld.MakeClient(os.Getenv("LAUNCHDARKLY_SDK_KEY"), 5*time.Second)
+if err != nil {
+ log.Printf("LaunchDarkly SDK failed to initialize: %v", err)
+}
+```
+
+### Client-Side Initialization Pattern
+
+```tsx
+// React example
+import { asyncWithLDProvider } from 'launchdarkly-react-client-sdk';
+
+const LDProvider = await asyncWithLDProvider({
+ clientSideID: process.env.REACT_APP_LAUNCHDARKLY_CLIENT_SIDE_ID,
+ context: {
+ kind: 'user',
+ key: 'anonymous',
+ },
+});
+
+// Wrap your app with the provider
+root.render(
+
+
+
+);
+```
+
+Refer to the [SDK Recipes](sdk-recipes.md) for language-specific import and init snippets.
+
+## Step 4: Verify the Code Compiles
+
+After making changes:
+
+1. Run the project's build or compile step
+2. Run the linter if one is configured
+3. Fix any import errors or type issues
+
+Do not proceed to the next step if the code doesn't compile.
+
+## Status
+
+```
+[STATUS] Installing SDK dependency
+[STATUS] Configuring SDK key
+[STATUS] Adding initialization code
+[STATUS] Verifying code compiles
+```
+
+---
+
+**Upon completion, continue with:** [Start the Application](1.3-run.md)
diff --git a/skills/onboarding/launchdarkly-sdk-onboarding/references/1.3-run.md b/skills/onboarding/launchdarkly-sdk-onboarding/references/1.3-run.md
new file mode 100644
index 0000000..96f9f22
--- /dev/null
+++ b/skills/onboarding/launchdarkly-sdk-onboarding/references/1.3-run.md
@@ -0,0 +1,89 @@
+---
+title: Start the Application
+description: Run the application and confirm the LaunchDarkly SDK initializes successfully
+---
+
+# Start the Application
+
+After installing the SDK and adding initialization code, verify the application starts and the SDK connects.
+
+## Step 1: Identify the Run Command
+
+Find how the project is normally started:
+
+| Indicator | Run Command |
+|-----------|-------------|
+| `package.json` `"scripts"."start"` | `npm start` or `npm run dev` |
+| `package.json` `"scripts"."dev"` | `npm run dev` |
+| `Makefile` with `run` target | `make run` |
+| `manage.py` (Django) | `python manage.py runserver` |
+| `app.py` or `main.py` (Flask/FastAPI) | `python app.py` or `uvicorn main:app` |
+| `go.mod` | `go run .` or `go run cmd/server/main.go` |
+| `Gemfile` with Rails | `bin/rails server` |
+| `Cargo.toml` | `cargo run` |
+
+If the project has a README with run instructions, follow those.
+
+## Step 2: Start the Application
+
+Run the application. Do NOT rely on specific log messages to determine success — different SDKs log differently and some don't log at all.
+
+### What to Look For
+- The application starts without crashing
+- No import errors or module-not-found errors
+- The app is responsive (e.g., serves HTTP requests, renders UI)
+
+### Common Startup Errors
+- `Module not found` or `ImportError` — the SDK wasn't installed correctly. Re-run the install command.
+- `TypeError` or `undefined` — initialization code may have a syntax issue. Check the code against the SDK recipe.
+- Network timeout — the SDK can't reach LaunchDarkly (check firewall/proxy settings).
+- App crashes on startup — check if the SDK key environment variable is set.
+
+**Important**: The SDK may initialize silently. Do not assume failure just because you don't see a success log message. The actual validation happens in the next step using the `sdk-active` endpoint.
+
+## Step 3: Handle Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| SDK key not set | Remind the user to set the `LAUNCHDARKLY_SDK_KEY` environment variable |
+| Module not found | Re-run the install command; check the dependency file |
+| Initialization timeout | Check network connectivity; verify the SDK key is valid |
+| Type errors | Check the import statement matches the SDK version |
+| App starts but no SDK log | Verify the initialization code is actually being executed (not behind a conditional) |
+
+## Step 4: Confirm SDK Activity
+
+Once the application is running, use the `sdk-active` endpoint to confirm the SDK has connected to LaunchDarkly. This is the definitive check — not log messages.
+
+Use `ldcli` if available:
+
+```bash
+ldcli sdk-active \
+ --access-token YOUR_ACCESS_TOKEN \
+ --project PROJECT_KEY \
+ --environment ENVIRONMENT_KEY
+```
+
+Or call the API directly:
+
+```bash
+curl -s -X GET \
+ "https://app.launchdarkly.com/api/v2/projects/PROJECT_KEY/environments/ENVIRONMENT_KEY/sdk-active" \
+ -H "Authorization: LAUNCHDARKLY_ACCESS_TOKEN"
+```
+
+If the SDK is not yet active, wait 30 seconds and retry — the SDK needs to send at least one event to LaunchDarkly before it shows as active.
+
+If you cannot start the application (e.g., it requires infrastructure the agent doesn't have access to), ask the user to start it manually and confirm it's running.
+
+## Status
+
+```
+[STATUS] Identifying run command
+[STATUS] Starting application
+[STATUS] Checking SDK initialization
+```
+
+---
+
+**Upon completion, continue with:** [Validate SDK Connection](1.4-validate.md)
diff --git a/skills/onboarding/launchdarkly-sdk-onboarding/references/1.4-validate.md b/skills/onboarding/launchdarkly-sdk-onboarding/references/1.4-validate.md
new file mode 100644
index 0000000..7fcab25
--- /dev/null
+++ b/skills/onboarding/launchdarkly-sdk-onboarding/references/1.4-validate.md
@@ -0,0 +1,99 @@
+---
+title: Validate SDK Connection
+description: Confirm that LaunchDarkly sees the SDK connection using the API or MCP
+---
+
+# Validate SDK Connection
+
+The application is running — now confirm LaunchDarkly actually sees the SDK connection. This is the critical step that proves the integration works end-to-end.
+
+## Option A: Validate via ldcli (Preferred)
+
+The `ldcli sdk-active` command is the fastest way to check if the SDK is connected:
+
+```bash
+ldcli sdk-active \
+ --access-token YOUR_ACCESS_TOKEN \
+ --project PROJECT_KEY \
+ --environment ENVIRONMENT_KEY
+```
+
+This checks the LaunchDarkly backend for recent SDK activity in the target environment.
+
+## Option B: Validate via LaunchDarkly API
+
+If `ldcli` is not available, use the REST API directly:
+
+```bash
+curl -s -X GET \
+ "https://app.launchdarkly.com/api/v2/projects/PROJECT_KEY/environments/ENVIRONMENT_KEY/sdk-active" \
+ -H "Authorization: LAUNCHDARKLY_ACCESS_TOKEN"
+```
+
+Replace:
+- `PROJECT_KEY` with the LaunchDarkly project key
+- `ENVIRONMENT_KEY` with the environment key (e.g., `test`, `production`)
+- `LAUNCHDARKLY_ACCESS_TOKEN` with the API access token
+
+A successful response means the SDK has connected to LaunchDarkly.
+
+## Option C: Validate via MCP
+
+If the LaunchDarkly MCP server is available, use the `get-environment` tool to check the SDK status:
+
+1. Call `get-environment` with the project key and environment key
+2. Look for the SDK-related fields in the response
+3. If the environment shows recent SDK activity, the connection is confirmed
+
+## Option D: Validate via Dashboard
+
+As a fallback, direct the user to check:
+
+**https://app.launchdarkly.com/projects/default/flags**
+
+If the SDK is connected, the flags page will show evaluation data and SDK version information.
+
+## Interpreting Results
+
+| Result | Meaning | Next Step |
+|--------|---------|-----------|
+| SDK active / connected | Integration is working | Continue to [Create First Feature Flag](1.5-first-flag.md) |
+| SDK not active | SDK hasn't connected yet | Wait 30 seconds and retry; check the SDK key is correct |
+| 401 Unauthorized | Invalid access token | Verify the API access token |
+| 404 Not Found | Invalid project or environment key | Verify the project and environment keys |
+| Network error | Can't reach LaunchDarkly API | Check internet connectivity |
+
+## Retry Logic
+
+The SDK needs to send at least one event to LaunchDarkly before it registers as active. This can take up to 60 seconds after the application starts.
+
+**Retry strategy:**
+1. Wait 15 seconds after the app starts, then check
+2. If not active, wait 30 seconds and retry
+3. If not active, wait 30 seconds and retry once more
+4. **After 3 failed attempts, stop retrying.** Do not loop indefinitely.
+
+Keep track of what you've already tried. If you've already verified the SDK key, checked the environment, and confirmed the app is running, don't repeat those checks — move to the troubleshooting section.
+
+## Troubleshooting
+
+If validation fails after 3 attempts:
+
+1. **Verify the SDK key**: Make sure you're using the right key type (SDK key for server-side, Client-side ID for client-side, Mobile key for mobile)
+2. **Verify the environment**: Make sure the SDK key matches the environment you're validating against
+3. **Check the application logs**: Look for any SDK error messages
+4. **Check network**: The SDK needs outbound HTTPS access to `events.launchdarkly.com` and `stream.launchdarkly.com`
+5. **Check if the app is actually running**: The sdk-active endpoint requires the app to be running and to have sent at least one event. If the app hasn't started or crashed, fix that first.
+
+If none of the above works, proceed to [Recovery Procedures](1.6-recover.md).
+
+## Status
+
+```
+[STATUS] Validating SDK connection
+[STATUS] Checking LaunchDarkly API for SDK activity
+```
+
+---
+
+**Upon completion, continue with:** [Create First Feature Flag](1.5-first-flag.md)
diff --git a/skills/onboarding/launchdarkly-sdk-onboarding/references/1.5-first-flag.md b/skills/onboarding/launchdarkly-sdk-onboarding/references/1.5-first-flag.md
new file mode 100644
index 0000000..73e2aa4
--- /dev/null
+++ b/skills/onboarding/launchdarkly-sdk-onboarding/references/1.5-first-flag.md
@@ -0,0 +1,194 @@
+---
+title: Create Your First Feature Flag
+description: Create a boolean feature flag, add evaluation code, and toggle it to demonstrate end-to-end functionality
+---
+
+# Create Your First Feature Flag
+
+The SDK is connected. Now help the user create their first feature flag and see it work end-to-end.
+
+## Step 1: Create the Flag
+
+### Via MCP (Preferred)
+
+If the LaunchDarkly MCP server is available, use `create-flag`:
+
+- **Key**: `my-first-flag` (or a name relevant to the user's project)
+- **Name**: "My First Flag"
+- **Kind**: `boolean`
+- **Variations**: `true` / `false`
+- **Temporary**: `true`
+
+### Via LaunchDarkly API
+
+```bash
+curl -s -X POST \
+ "https://app.launchdarkly.com/api/v2/flags/PROJECT_KEY" \
+ -H "Authorization: LAUNCHDARKLY_ACCESS_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "My First Flag",
+ "key": "my-first-flag",
+ "kind": "boolean",
+ "variations": [
+ {"value": true},
+ {"value": false}
+ ],
+ "temporary": true
+ }'
+```
+
+### Via ldcli
+
+```bash
+ldcli flags create \
+ --access-token YOUR_ACCESS_TOKEN \
+ --project PROJECT_KEY \
+ --data '{"name": "My First Flag", "key": "my-first-flag", "kind": "boolean"}'
+```
+
+After creation, the flag starts with **targeting OFF**, serving the off variation (`false`) to everyone.
+
+## Step 2: Add Flag Evaluation Code
+
+Add code to evaluate the flag in the application. Place this where it makes sense for the user's feature.
+
+### Server-Side Examples
+
+```javascript
+// Node.js
+const context = { kind: 'user', key: 'example-user-key', name: 'Example User' };
+const showFeature = await ldClient.variation('my-first-flag', context, false);
+
+if (showFeature) {
+ console.log('Feature is ON');
+} else {
+ console.log('Feature is OFF');
+}
+```
+
+```python
+# Python
+context = Context.builder("example-user-key").name("Example User").build()
+show_feature = client.variation("my-first-flag", context, False)
+
+if show_feature:
+ print("Feature is ON")
+else:
+ print("Feature is OFF")
+```
+
+```go
+// Go
+context := ldcontext.NewBuilder("example-user-key").Name("Example User").Build()
+showFeature, _ := ldClient.BoolVariation("my-first-flag", context, false)
+
+if showFeature {
+ fmt.Println("Feature is ON")
+} else {
+ fmt.Println("Feature is OFF")
+}
+```
+
+### Client-Side Examples
+
+```tsx
+// React
+import { useFlags } from 'launchdarkly-react-client-sdk';
+
+function MyComponent() {
+ const { myFirstFlag } = useFlags();
+
+ return (
+
+ {myFirstFlag ?
Feature is ON
:
Feature is OFF
}
+