Back to Details

onboarding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LaunchDarkly SDK Onboarding

LaunchDarkly SDK 接入指南

Orchestrates LaunchDarkly setup in an existing codebase: on kickoff, show a roadmap in chat (see Kickoff: onboarding roadmap); Step 0 writes a living onboarding log so a new session or the user can resume; then explore the project, detect the agent, install flag-management skills, configure the LaunchDarkly MCP server early, install and initialize the SDK (sdk-install and nested detect/plan/apply), and create a first feature flag. Nested skills: mcp-configure, sdk-install, first-flag.
协调现有代码库中的LaunchDarkly设置流程：启动时在聊天中展示路线图（参见启动：接入路线图）；步骤0创建动态接入日志，支持新会话或用户恢复流程；随后探索项目、检测智能代理、安装旗标管理技能、尽早配置LaunchDarkly MCP服务器、安装并初始化SDK（sdk-install及嵌套的检测/规划/实施流程），并创建首个功能旗标。嵌套技能：mcp-configure、sdk-install、first-flag。

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.
MCP (preferred): Complete Step 4 via mcp-configure/SKILL.md before SDK work when possible. If MCP is unavailable or the user opts out, use ldcli / REST fallbacks described in that skill (including MCP Config Templates for local 
npx
fallback when hosted MCP does not apply) -- onboarding must still be completable.
Optional MCP tools (when configured):
  • 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.
Other MCP tools you may use if present (not required): 
list-feature-flags
, 
get-feature-flag
, 
get-flag-status-across-environments
.
  • npx
    ：     使用
    npx skills add
    安装配套技能时需在PATH中可用（参见步骤3）。
  • LaunchDarkly账号（仅初始阶段）： 接入流程初期——在展示启动路线图后，如果日志未记录相关信息，仅询问用户是否已拥有LaunchDarkly账号（可登录https://app.launchdarkly.com）。请勿在同一轮对话中询问SDK密钥、客户端ID、移动密钥、API访问令牌，或密钥是否已存入环境变量；这些信息需推迟到对应步骤需要时再收集（详见下文）。
  • 密钥与令牌（推迟收集——请勿与账号问题合并）： 仅在流程需要时收集这些信息——绝不能作为初始“是否拥有账号？”问题的一部分。
    • 步骤4——MCP： 托管式MCP使用OAuth；配置时无需API令牌或SDK密钥。本地
      npx
      MCP      （联邦/欧盟等场景）：需按照mcp-configure和MCP配置模板要求提供API访问令牌。
    • 步骤5——SDK： 在实施代码变更中配置环境变量时，确认集成方案后收集SDK密钥/客户端ID/移动密钥。
      ldcli
      /REST      用于发现：首次运行这些命令时使用**
      ldcli login
      **或访问令牌，而非在初始问候时请求。
    • 密钥类型必须与集成场景匹配： 服务端SDK对应SDK密钥；浏览器/客户端SDK对应客户端ID；移动端对应移动密钥。环境变量名称和打包工具规则：参见实施代码变更。
MCP（推荐）： 尽可能在SDK相关工作前完成步骤4，按照mcp-configure/SKILL.md配置MCP。若MCP不可用或用户选择不使用，则使用该技能中描述的ldcli/REST备选方案（包括当托管式MCP不适用时，使用本地
npx
备选方案的MCP配置模板）——接入流程仍需能够完成。
可选MCP工具（配置完成后）：
  • get-environments
    ——列出项目的环境；响应包含每个环境对应的SDK密钥、客户端ID和移动密钥。将此作为所有密钥类型的唯一数据源——请勿单独请求单个密钥。
  • create-feature-flag
    ——为步骤6：创建首个功能旗标创建布尔型旗标。
  • update-feature-flag
    ——在步骤6中切换或修补旗标配置；参见创建首个功能旗标中的ldcli/API备选方案。
若存在以下MCP工具也可使用（非必需）：
list-feature-flags
、
get-feature-flag
、
get-flag-status-across-environments
。

Agent Behavior Directives

智能代理行为指令

Progress Tracking

进度跟踪

The roadmap (Steps 0-6 + follow-through) MUST be tracked using your agent's native task-tracking tool in addition to the onboarding log file.
  • 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.
Do NOT work through steps mentally or rely solely on the 
LAUNCHDARKLY_ONBOARDING.md
log for in-session tracking.
路线图（步骤0-6+后续工作）必须使用智能代理原生的任务跟踪工具，配合接入日志文件进行跟踪。
  • Cursor： 使用
    TodoWrite
    在开始工作前为每个步骤创建待办事项。完成每个步骤后更新状态。
  • Claude Code： 使用
    TaskCreate
    为每个步骤创建任务（若原生任务不可用则使用
    TodoWrite
    ）。
  • 其他代理： 若代理提供原生任务列表或进度跟踪工具，则使用该工具。若没有，则在聊天中展示编号清单，并在每个步骤完成后更新。
请勿仅在脑中规划步骤，或仅依赖
LAUNCHDARKLY_ONBOARDING.md
日志进行会话内跟踪。

Decision Points

决策点

When a step requires user input to determine branching, you MUST collect the answer by calling a tool — do NOT write the question as prose text in your response.
Call the tool directly. Use the first tool from this list that your environment provides:
  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.
Do NOT decide in advance whether you have the tool. Attempt the call. The tool call IS the question — do not also write the question as text.
Throughout this skill and its nested skills you will see decision-point markers formatted like this:
**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.
These are instructions for you to follow, not content to display. When you reach one: make the tool call (or render numbered options if no tool exists), then STOP and wait. Do NOT copy the marker text into your response.
当步骤需要用户输入来确定分支时，必须通过调用工具收集答案——请勿在回复中以散文形式编写问题。
直接调用工具。使用环境提供的以下列表中的第一个工具：
  1. AskQuestion
    ——传入
    prompt
    和
    options
    数组调用
  2. TaskAsk
    或等效的结构化输入工具 3.（备选）若工具调用失败或无此类工具，则 将问题渲染为编号选项文本并等待用户回复。
请勿预先判断是否拥有该工具。尝试调用工具。工具调用即为问题——请勿同时以文本形式编写问题。
在本技能及其嵌套技能中，你会看到如下格式的决策点标记：
**D1 -- BLOCKING:** <调用问题工具的指令>
- question: "<问题内容>"
- options:
  - "<选项A>" -> <后续操作>
  - "<选项B>" -> <后续操作>
- STOP. 等待用户选择选项后再继续。
这些是供你遵循的指令，而非展示给用户的内容。当遇到此类标记时：调用工具（若无工具则渲染编号选项），然后停止并等待。请勿将标记文本复制到回复中。

User-Facing Communication

用户沟通规范

Every reply during onboarding must sound like a friendly, knowledgeable colleague walking someone through setup — not a workflow engine quoting internal instructions. Follow these rules in all user-facing output:
Required response structure. Every substantive onboarding reply must include:
  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").
Forbidden in user-facing output:
  • 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").
When telling the user to run a command, always say where to run it. Good examples:
  • "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 …"
Bad: "Run 
npm install
" (without location context).
Tone: Friendly, conversational, and confident — like a knowledgeable colleague, not a manual. Use first person naturally (e.g. "I just detected that the flag was created, now I'm going to …"). Assume the reader is an engineer so don't over-explain basic concepts (what a package manager is, what an environment variable does), but do explain LaunchDarkly-specific concepts briefly on first mention (what a context is, what an SDK key is for, why there are different key types).
接入过程中的每一次回复都应听起来像友好、专业的同事在引导用户完成设置——而非工作流引擎引用内部指令。在所有面向用户的输出中遵循以下规则：
必需的回复结构。每一条实质性的接入回复必须包含：
  1. 我们刚完成的操作——用一两句话总结已完成的操作及其结果。
  2. 下一步计划——用通俗易懂的语言预览下一步内容。
  3. 你需要做的操作（仅当用户需要手动操作时）——具体的指令，而非模糊的标签如“轮到你了”。需包含操作位置（例如：“在Cursor的集成终端中”、“在项目文件夹中”、“在浏览器中”、“在macOS终端中”）。
面向用户的输出中禁止出现：
  • 内部决策点ID（D1、D5、D7等）、作为标签的步骤编号（例如“Step 5 -- detect”）或技能文件名（例如“sdk-install/apply/SKILL.md”）。
  • 引用或改写原始技能指令、指令标题或这些文件中的markdown内容。
  • 工作流引擎术语（“BLOCKING”、“STOP”、“调用结构化问题工具”、“进入下一个嵌套技能”）。
当告知用户运行命令时，务必说明运行位置。示例：
  • “在编辑器的集成终端中运行此命令”
  • “在项目根目录的终端中运行此命令”
  • “在
    packages/api
    文件夹中打开终端并运行……”
错误示例：“Run 
npm install
”（未说明位置上下文）。
语气： 友好、口语化且自信——像专业的同事，而非操作手册。自然使用第一人称（例如：“我刚检测到旗标已创建，现在我将……”）。假设读者是工程师，无需过度解释基础概念（如包管理器是什么、环境变量的作用），但需在首次提及LaunchDarkly特定概念时简要说明（如上下文是什么、SDK密钥的用途、为何存在不同类型的密钥）。

Step Execution Rules

步骤执行规则

Do NOT treat the user's initial request (e.g. "onboard me," "set up LaunchDarkly") as blanket permission for file writes, installs, or configuration changes. Each action that modifies the repo, installs packages, or writes secrets requires its own consent at the step where it occurs.
Blocking decision points (you MUST halt and wait for the user's response before continuing):
IDLocationQuestion
D1KickoffDo you have a LaunchDarkly account?
D4-LOCALStep 4 (local MCP)User chooses whether to handle the access token themselves (recommended) or let the agent help
D5-NOAPPStep 5 -- detectNo runnable app found: user points to app or requests demo
D5-UNCLEARStep 5 -- detectWeak evidence: user confirms the correct app folder
D5Step 5 -- detectSDK confirmation / one-vs-both-SDKs scope choice
D6Step 5 -- planApprove the integration plan before any code changes
D7Step 5 -- applyUser chooses how secrets are set up: user-specified location, user handles it, or 
.env
fallback
D8Step 5 -- applyApproval before changing non-LaunchDarkly dependencies
D9Step 6Auth errors (401/403): stop, do not retry automatically
Non-blocking (you may proceed automatically): Step 0 onboarding log (write it directly), Step 1 exploration (read-only), Step 3 skill install (installs to agent config, not the user's repo), Step 5 detect (file reads only), compile check (Step 5 apply Step 4), follow-through file writes (
LAUNCHDARKLY.md
, editor rules).
请勿将用户的初始请求（例如“帮我接入”、“设置LaunchDarkly”）视为对文件写入、安装或配置变更的全面许可。每一项修改仓库、安装包或写入密钥的操作，都需要在对应步骤获得单独的同意。
阻塞型决策点（必须暂停并等待用户回复后再继续）：
ID位置问题
D1启动阶段你是否拥有LaunchDarkly账号？
D4-LOCAL步骤4（本地MCP）用户选择自行处理访问令牌（推荐）或让代理协助
D5-NOAPP步骤5——检测未找到可运行的应用：用户指定应用位置或请求演示
D5-UNCLEAR步骤5——检测证据不足：用户确认正确的应用文件夹
D5步骤5——检测SDK确认/单SDK/双SDK范围选择
D6步骤5——规划在进行任何代码变更前批准集成方案
D7步骤5——实施用户选择密钥设置方式：指定位置、自行处理或
.env
备选方案
D8步骤5——实施在修改非LaunchDarkly依赖项前获得批准
D9步骤6认证错误（401/403）：停止，请勿自动重试
非阻塞型（可自动继续）：步骤0接入日志（直接写入）、步骤1探索（只读）、步骤3技能安装（安装到代理配置，而非用户仓库）、步骤5检测（仅读取文件）、编译检查（步骤5实施的第4步）、后续文件写入（
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 showURL 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").
  1. 检测而非猜测： 检查仓库的语言、框架和包管理器。
  2. 最小变更： 在现有代码旁添加SDK代码；请勿重构项目。
  3. 匹配现有模式： 遵循项目已使用的环境变量、配置文件和初始化模式。
  4. 端到端验证： 在将首个旗标视为成功证据前，确认SDK已连接。
  5. 可追溯记录： 保持步骤0接入日志的更新，以便其他代理或后续会话无需重新推导上下文即可继续流程。
  6. 先引导用户： 在新的接入请求中，先展示启动路线图再进行实质性工作，让用户了解完整流程。
  7. 分阶段询问凭证： 初始阶段确认账号；仅在步骤4-5中，当对应技能说明需要时，再询问SDK密钥/令牌（参见前置条件）。
  8. 深度链接到控制台： 生成LaunchDarkly控制台URL时，若已知项目密钥和/或环境密钥（来自MCP工具、用户输入或接入日志），则构建最具体的URL，而非链接到通用页面。使用以下模式：
    需展示内容URL模式
    项目旗标列表
    https://app.launchdarkly.com/projects/{projectKey}/flags
    特定旗标
    https://app.launchdarkly.com/projects/{projectKey}/flags/{flagKey}
    环境密钥/SDK密钥
    https://app.launchdarkly.com/projects/{projectKey}/settings/environments/{envKey}/keys
    项目环境列表
    https://app.launchdarkly.com/projects/{projectKey}/settings/environments
    所有项目
    https://app.launchdarkly.com/projects
    仅当从工具响应或已确认的用户输入中获取到所需密钥时，才生成深度链接。若未知密钥，则使用最具体的通用路径，并告知用户如何从该路径导航（例如：“在LaunchDarkly控制台中打开你的项目，然后前往设置 > 环境查找SDK密钥”）。

Kickoff: onboarding roadmap

启动：接入路线图

When the user invokes this onboarding flow (for example by asking you to follow this skill, run LaunchDarkly onboarding, or set up feature flags in the project), treat it as a fresh kickoff unless you are clearly resuming (see Resuming below).
当用户调用此接入流程（例如要求遵循本技能、运行LaunchDarkly接入或在项目中设置功能旗标）时，除非明确是恢复流程（参见下文恢复流程），否则视为全新启动。

Kickoff sequence (new run — before any numbered step)

启动流程（全新运行——在任何编号步骤之前）

Perform these in order in the same assistant turn, then stop at D1 until the user answers:
  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.
StepWhat happensYou get
0 -- Onboarding logCreate or refresh 
LAUNCHDARKLY_ONBOARDING.md
(or 
docs/...
)		Resumable checklist, context, next-step pointer
1 -- Explore projectDetect language, framework, existing LD usage, environment typeStack summary for the user
2 -- Detect agentCursor, Claude Code, Copilot, etc.Correct 
--agent
for 
npx skills add
3 -- Companion skills
npx skills add ...
flag skills from 
launchdarkly/agent-skills
launchdarkly-flag-*
skills available
4 -- MCPConfigure LaunchDarkly MCP; user restarts; agent auto-verifies on next turnMCP tools (or ldcli/API fallback)
5 -- SDK installdetect -> plan -> apply (sdk-install)Packages + init wired to env vars
6 -- First flagCreate boolean flag, evaluate, toggle, add interactive demo (first-flag)End-to-end proof + visible "wow" moment
Follow-throughOptional: 
LAUNCHDARKLY.md
, editor rules (1.8-summary, 1.9-editor-rules)		Durable docs for the repo
D1 -- BLOCKING (end of kickoff sequence): Call your structured question tool now.
  • question: "Do you already have a LaunchDarkly account you can sign into?"
  • options:
  • STOP. Do not write the question as text. Do not continue until the user selects an option.
If they need an account, point them to https://app.launchdarkly.com/signup?source=agent and explain which later steps (MCP, SDK keys) will wait on it. Then proceed with Step 0 (or the log's Next step if resuming).
按顺序在同一轮助理回复中执行以下操作，然后在D1处停止，等待用户回复：
  1. 任务列表： 调用原生任务工具（参见进度跟踪），为步骤0至步骤6创建每个步骤对应一个任务（至少7个任务——对应下表中的每一行编号步骤）。在渲染路线图表格之前完成此操作，以便在暂停于D1前完成进度跟踪设置。
  2. 路线图： 在用户可见的回复中渲染下方的路线图表格（仅当边缘情况明显会跳过某个步骤时，才调整行文字）。路线图仅为聊天中的临时内容——请勿创建文件，除非用户要求。
  3. D1： 调用结构化问题工具询问账号问题（参见下文D1）。请勿创建或更新
    LAUNCHDARKLY_ONBOARDING.md
    、执行步骤1的仓库探索、步骤2的代理检测，或运行**
    npx
    **（或任何shell安装命令）进行步骤3的操作，直到用户回复D1。
  • 恢复流程： 若
    LAUNCHDARKLY_ONBOARDING.md
    已存在，则先读取该文件（参见步骤0）。展示相同的路线图，并根据日志填充状态列，或展示更简短的“当前进度”摘要——以用户易理解的方式为准。若需要，刷新任务列表以匹配日志；若日志中已记录D1（账号状态），请勿再次询问D1——从日志中的下一步继续。
步骤操作内容成果
0 -- 接入日志创建或更新
LAUNCHDARKLY_ONBOARDING.md
（或
docs/...
）		可恢复的清单、上下文、下一步指引
1 -- 项目探索检测语言、框架、现有LD使用情况、环境类型为用户提供技术栈摘要
2 -- 代理检测检测Cursor、Claude Code、Copilot等智能代理为
npx skills add
选择正确的
--agent
参数
3 -- 配套技能通过
npx skills add ...
从
launchdarkly/agent-skills
安装旗标技能		可使用
launchdarkly-flag-*
系列技能
4 -- MCP配置配置LaunchDarkly MCP；用户重启代理；代理在下一轮对话中自动验证可使用MCP工具（或ldcli/API备选方案）
5 -- SDK安装检测 -> 规划 -> 实施（参见sdk-install）包已安装 + 初始化已关联到环境变量
6 -- 首个旗标创建布尔型旗标、评估、切换、添加交互式演示（参见first-flag）端到端验证成果 + 直观的“成功”展示
后续工作可选：创建
LAUNCHDARKLY.md
、配置编辑器规则（参见1.8-summary、1.9-editor-rules）		仓库的持久化文档
D1 -- BLOCKING（启动流程末尾）：立即调用结构化问题工具。
若用户需要账号，引导其访问https://app.launchdarkly.com/signup?source=agent，并说明哪些后续步骤（MCP、SDK密钥）需等待账号就绪。然后继续执行[步骤0](#step-0-create-or-refresh-the-onboarding-log)（或若为恢复流程，则从日志中的下一步开始）。

Workflow

工作流程

Follow Steps 0-6 in order unless an Edge case says otherwise. When Step 6 (first flag) completes successfully, continue with Default follow-through.
按步骤0-6顺序执行，除非边缘情况另有说明。当步骤6（首个旗标）成功完成后，继续执行默认后续工作。

Step 0: Create or Refresh the Onboarding Log

步骤0：创建或刷新接入日志

Before substantive work, give this run a durable paper trail so a new agent or a later session can see what was decided, what ran, and what is next.
  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.
This file is a working log during onboarding. After success, the user may delete it, archive it, or fold facts into 
LAUNCHDARKLY.md
(Onboarding Summary).
在进行实质性工作前，为本次运行创建持久化可追溯记录，以便新代理或后续会话了解已做出的决策、已执行的操作和下一步计划。
  1. 查找现有日志：在仓库根目录查找
    LAUNCHDARKLY_ONBOARDING.md
    。若项目文档存放在
    docs/
    文件夹下，且根目录无该文件，则优先使用
    docs/LAUNCHDARKLY_ONBOARDING.md
    。
  2. 创建或更新日志文件：这是接入工作流的一部分——直接写入，无需征求许可。
  3. 若为恢复流程： 先读取日志，与日志中指定的下一步保持一致，仅重新执行日志标记为未完成或无效的工作。
  4. 日志内容（每个编号步骤完成后或重要变更发生时更新）：
    • 清单： 步骤0-6及其状态（
      not started
      / 
      in progress
      / 
      done
      / 
      skipped
      + 简短原因）。
    • 上下文： 编码代理ID（已知后）、语言/框架摘要、单体仓库目标路径（如有）、LaunchDarkly项目密钥和环境密钥（已知后——绝不要粘贴密钥或完整SDK密钥，只需标注“存储在环境中”或“用户离线提供”）。
    • MCP： 是否已配置、托管式还是备选方案、配置路径链接（如有）。
    • 已执行命令： 例如
      npx skills add ...
      （不包含密钥）。
    • 阻塞点/错误： 失败内容及已尝试的解决方法。
    • 下一步： 明确的步骤编号和名称（例如“步骤5：安装并初始化SDK”）。
  5. 错误处理后： 在日志中追加或编辑错误信息及恢复位置。
此文件是接入过程中的工作日志。成功完成接入后，用户可删除、归档该文件，或将其中的信息整合到
LAUNCHDARKLY.md
中（参见接入总结）。

Step 1: Explore the Project

步骤1：项目探索

Understand what you are integrating before installing packages.
  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.
Deep detection details: Detect repository stack (nested under sdk-install).
在安装包之前，了解要集成的环境。
  1. 识别语言和框架：检查依赖文件：
    package.json
    、
    go.mod
    、
    requirements.txt
    / 
    pyproject.toml
    / 
    Pipfile
    、
    pom.xml
    / 
    build.gradle
    、
    Gemfile
    、
    *.csproj
    / 
    *.sln
    、
    Cargo.toml
    等。
  2. 检查现有LaunchDarkly使用情况：搜索
    launchdarkly
    、
    ldclient
    、
    ld-client
    、
    LDClient
    、
    @launchdarkly
    。
    • 若已存在：记录SDK版本和使用模式；可根据边缘情况缩短或跳过步骤5。
    • 若不存在：规划完整的SDK设置流程。
  3. 识别环境类型： 服务端应用、客户端SPA、移动端、边缘计算等——这将决定SDK的选择。
  4. 向用户总结： 语言、框架、环境类型、是否已集成LD。
深度检测详情：参见检测仓库技术栈（嵌套在sdk-install下）。

Step 2: Detect the Agent Environment

步骤2：检测代理环境

Determine which coding agent is running so MCP config and 
npx skills add --agent
use the right target. Infer the agent silently — do not ask the user.
  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.
确定运行的编码代理，以便MCP配置和
npx skills add --agent
使用正确的目标。静默推断代理——请勿询问用户。
  1. 按优先级顺序检查标识（找到第一个强匹配项后停止）：
    • Cursor： 
      .cursor/
      、
      .cursorrules
      或
      CURSOR_
      环境变量
    • Claude Code： 
      ~/.claude/
      、
      CLAUDE.md
      或
      CLAUDE_
      环境变量
    • Windsurf： 
      .windsurfrules
    • GitHub Copilot： 
      .github/copilot/
    • Codex： 
      ~/.codex/
      、
      AGENTS.md
  2. 若存在多个标识，选择当前运行的代理（例如：若可访问Cursor特定工具如
    AskQuestion
    或
    TodoWrite
    ，则当前为Cursor环境）。若没有匹配的标识，则默认使用当前观察到的工具对应的代理。
  3. 记录代理ID用于步骤3（例如
    cursor
    、
    claude-code
    ）。在展示步骤1/2总结时简要提及检测到的代理，以便用户在错误时纠正，但无需等待用户确认。

Step 3: Install Companion Skills

步骤3：安装配套技能

Install flag-management skills from the public repo so later steps can delegate when appropriate (see Bundled vs public below).
From 
launchdarkly/agent-skills
(flag workflows):
bash
npx skills add launchdarkly/agent-skills --skill launchdarkly-flag-create launchdarkly-flag-discovery launchdarkly-flag-targeting launchdarkly-flag-cleanup -y --agent <detected-agent>
Replace 
<detected-agent>
with the value from Step 2. Confirm success; skip skills already installed.
Bundled vs public: Orchestration and setup for this flow live in this folder -- parent SKILL.md, nested mcp-configure, sdk-install (detect / plan / apply), first-flag, and 
references/
(SDK recipes, snippets, summary, editor rules, etc.). The command above installs flag-management skills from the public launchdarkly/agent-skills repo only.
从公共仓库安装旗标管理技能，以便后续步骤可适当委托执行（参见下文内置技能vs公共技能）。
从
launchdarkly/agent-skills
（旗标工作流）安装：
bash
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>
替换为步骤2中获取的值。确认安装成功；跳过已安装的技能。
内置技能vs公共技能： 本流程的编排和设置逻辑位于当前文件夹——父级SKILL.md、嵌套的mcp-configure、sdk-install（检测/规划/实施）、first-flag和
references/
（SDK参考示例、代码片段、总结、编辑器规则等）。上述命令仅从公共launchdarkly/agent-skills仓库安装旗标管理技能。

Step 4: Configure the MCP Server

步骤4：配置MCP服务器

Hand off to mcp-configure/SKILL.md for setup (hosted MCP, quick install, manual JSON, agent authorization).
MCP setup requires the user to act outside the agent (clicking a quick-install link, completing OAuth, enabling the server in editor settings). After presenting the instructions, tell the user to restart or refresh the agent so MCP tools become available. Then continue to Step 5 — do not block here with a confirmation question.
Auto-verify on next turn: When the conversation resumes (after the user restarts or sends a message), probe for MCP by calling a lightweight MCP tool such as 
list-feature-flags
with the known project key. If the tool responds normally, MCP is live — note it in the onboarding log and use MCP tools for later steps. If the call fails or no MCP tools are visible, fall back silently to ldcli/API for Steps 5-6 and note the fallback in the onboarding log. Do not ask the user whether MCP is working — find out by trying it.
Do not duplicate MCP procedures in this file. Do not block Step 5 indefinitely on MCP.
委托给mcp-configure/SKILL.md进行设置（托管式MCP、快速安装、手动JSON配置、代理授权）。
MCP设置需要用户在代理外部操作（点击快速安装链接、完成OAuth、在编辑器设置中启用服务器）。展示说明后，告知用户重启或刷新代理，以便MCP工具可用。然后继续执行步骤5——无需在此等待用户确认。
下一轮对话自动验证： 当对话恢复（用户重启代理或发送消息后），调用轻量级MCP工具（例如使用已知项目密钥调用
list-feature-flags
）探测MCP是否可用。若工具正常响应，则MCP已启用——在接入日志中记录，并在后续步骤中使用MCP工具。若调用失败或无MCP工具可用，则静默切换到ldcli/API执行步骤5-6，并在接入日志中记录备选方案。请勿询问用户MCP是否正常工作——通过尝试调用工具确认。
请勿在此文件中重复MCP流程。请勿无限期阻塞步骤5等待MCP配置完成。

Step 5: Install and Initialize the SDK

步骤5：安装并初始化SDK

If the project already has LaunchDarkly installed and initialized (see detect decision tree), skip to Step 6: Create Your First Feature Flag.
Otherwise hand off to LaunchDarkly SDK Install (onboarding), which runs nested skills in order: Detect repository stack -> Generate integration plan -> Apply code changes, using SDK recipes and SDK snippets. If the user asked for both server and client (e.g. API + SPA, Next.js server + browser), follow Dual SDK integrations through plan and apply so both SDKs are really installed and initialized.
Blocking decision points inside Step 5 (see nested skills): D5 (SDK scope), D6 (plan approval), D7 (secret consent), D8 (dependency changes). Do NOT batch tool calls across these boundaries.
若项目已安装并初始化LaunchDarkly（参见检测决策树），则跳至步骤6：创建首个功能旗标。
否则委托给LaunchDarkly SDK安装（接入流程），该技能将按顺序运行嵌套技能：检测仓库技术栈 -> 生成集成方案 -> 实施代码变更，使用SDK参考示例和代码片段。若用户要求同时集成服务端和客户端（例如API + SPA、Next.js服务端 + 浏览器），则按照双SDK集成完成规划和实施，确保两个SDK都已安装并初始化。
步骤5中的阻塞型决策点（参见嵌套技能）：D5（SDK范围）、D6（方案批准）、D7（密钥同意）、D8（依赖变更）。请勿跨这些边界批量调用工具。

Step 6: Create Your First Feature Flag

步骤6：创建首个功能旗标

Create and evaluate a boolean flag; toggle and observe end-to-end.
  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.
Install or refresh flag skills via:
npx skills add launchdarkly/agent-skills --skill launchdarkly-flag-create -y --agent <detected-agent>
See D9 in first-flag for the blocking stop on auth errors.
创建并评估布尔型旗标；切换旗标并观察端到端流程。
  1. 遵循创建首个功能旗标流程。
  2. 若**
    launchdarkly-flag-create
    **技能（步骤3中安装）可用，可使用该技能完成创建/评估关联，但仍需完成创建首个功能旗标中的验证/切换清单。即使没有该技能，接入流程仍需能够完成。
通过以下命令安装或刷新旗标技能：
npx skills add launchdarkly/agent-skills --skill launchdarkly-flag-create -y --agent <detected-agent>
认证错误的阻塞停止规则参见first-flag中的D9。

Default follow-through (not numbered steps)

默认后续工作（非编号步骤）

Do these when finishing onboarding -- same session when possible. They are documentation and handoff tasks, not repeats of Steps 0-6. Do not skip this section -- it is the primary deliverable the user keeps after onboarding.
Setup summary (
LAUNCHDARKLY.md
) -- REQUIRED
Generate the repo summary per Onboarding Summary. Write it directly -- this is part of the onboarding workflow. The generated 
LAUNCHDARKLY.md
must include all of the following (see template in that reference):
  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
This is not the same file as 
LAUNCHDARKLY_ONBOARDING.md
. The onboarding log is a working checklist; 
LAUNCHDARKLY.md
is the permanent reference for the team.
Clean up the onboarding log: After writing 
LAUNCHDARKLY.md
, delete 
LAUNCHDARKLY_ONBOARDING.md
(or 
docs/LAUNCHDARKLY_ONBOARDING.md
if that was the location used). This is part of the workflow -- do not ask for permission. Removing the working log avoids confusion from having two LaunchDarkly docs in the repo.
Editor rules / skills
  • Add editor-specific rules or skill hooks per Editor Rules and Skills. Write them directly -- this is part of the onboarding workflow.
完成接入后执行这些工作——尽可能在同一会话中完成。这些是文档和交接任务，而非步骤0-6的重复。请勿跳过此部分——这是用户在接入完成后保留的主要交付物。
设置总结文档(
LAUNCHDARKLY.md
)——必需
按照接入总结生成仓库总结文档。直接写入——这是接入工作流的一部分。生成的
LAUNCHDARKLY.md
必须包含以下所有内容（参见该参考中的模板）：
  1. SDK详情——已安装的SDK、包名称、密钥类型、初始化文件
  2. 配置信息——环境变量名称、密钥管理方式、打包工具特定约定
  3. 资源位置——已替换真实项目密钥的控制台链接
  4. 功能旗标使用方式——针对项目技术栈的语言特定代码示例（非通用片段——使用步骤5中代理配置的相同模式）
  5. 下一步/高级功能——指向百分比发布、目标规则、实验、AI配置、受控发布和可观测性的链接
  6. AI代理集成——用于持续代理驱动旗标管理的MCP服务器设置
此文件不同于
LAUNCHDARKLY_ONBOARDING.md
。接入日志是工作清单；
LAUNCHDARKLY.md
是团队的永久参考文档。
清理接入日志： 写入
LAUNCHDARKLY.md
后，删除
LAUNCHDARKLY_ONBOARDING.md
（或使用的
docs/LAUNCHDARKLY_ONBOARDING.md
）。这是工作流的一部分——无需征求许可。移除工作日志可避免仓库中存在两个LaunchDarkly文档造成混淆。
编辑器规则/技能
  • 按照编辑器规则与技能添加编辑器特定规则或技能钩子。直接写入——这是接入工作流的一部分。

Edge Cases

边缘情况

SituationAction
SDK already installed and initialized (see detect decision tree)Skip Step 5; go to Step 6 (First flag)
SDK in dependencies but not initializedContinue Step 5 from apply / init (see sdk-install); do not skip validation
SDK state unclearRe-run Detect repository stack, then follow its decision tree
No runnable app found or app target unclearFollow the workspace classification in Detect: classify workspace confidence — ask the user to point to the real app or offer to create a demo. Do not proceed to plan or apply without a confirmed app target.
Multiple languages in repoBlocking (D5): use question tool to ask which target to integrate first -- do not guess
User wants both frontend and backend (or server + browser) in the same targetDual SDK plan: two packages, two entrypoints, two inits; apply must complete both tracks
MonorepoBlocking (D5): use question tool to ask which package/service to integrate -- do not assume the root
No package manager detectedBlocking (D5): use question tool to ask which SDK to install; provide manual install instructions from SDK recipes
Companion flag skills already installed (Step 3)Skip re-running 
npx skills add
for those skill names
Resuming after a break or new agent sessionRead 
LAUNCHDARKLY_ONBOARDING.md
(Step 0); continue from Next step; refresh the log as you go
MCP configuration fails or user declines MCPContinue with Step 5 using ldcli/API/dashboard per mcp-configure; note limitation for flag tooling
User / repo already fully onboardedSummarize state from Step 0 log and repo; offer next steps without redoing completed steps
场景操作
SDK已安装且已初始化（参见检测决策树）跳过步骤5；直接进入步骤6（首个旗标）
SDK已在依赖中但未初始化从实施/初始化阶段继续步骤5（参见sdk-install）；请勿跳过验证
SDK状态不明确重新运行检测仓库技术栈，然后遵循其决策树
未找到可运行的应用或应用目标不明确遵循检测：工作区置信度分类中的工作区分类——要求用户指定真实应用位置或提供演示。无确认的应用目标时请勿进入规划或实施阶段。
仓库中存在多种语言阻塞型（D5）： 使用问题工具询问用户优先集成哪个目标——请勿猜测
用户希望在同一目标中集成前端和后端（或服务端 + 浏览器）双SDK方案：两个包、两个入口点、两次初始化；实施必须完成两个集成流程
单体仓库阻塞型（D5）： 使用问题工具询问用户集成哪个包/服务——请勿默认根目录
未检测到包管理器阻塞型（D5）： 使用问题工具询问用户安装哪个SDK；提供SDK参考示例中的手动安装说明
配套旗标技能已安装（步骤3）跳过重新运行
npx skills add
安装这些技能
中断后恢复或新代理会话读取
LAUNCHDARKLY_ONBOARDING.md
（步骤0）；从下一步继续；更新日志
MCP配置失败或用户拒绝使用MCP按照mcp-configure使用ldcli/API/控制台继续步骤5；记录旗标工具的限制
用户/仓库已完全接入从步骤0日志和仓库总结当前状态；提供下一步建议，无需重复已完成步骤

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).
  • 未完成项目探索和技术栈检测（步骤1和5）前请勿安装SDK；更新步骤0日志。
  • 未获得明确用户批准前，请勿升级、固定或添加非LaunchDarkly依赖项（ peer依赖、锁文件变更、“最新版本”升级）以安装或编译SDK——参见实施——修改其他依赖项前需获得许可。
  • 请勿在源代码中硬编码SDK密钥——始终使用环境变量（参见实施代码变更）。
  • 请勿重构用户项目或修改无关代码。
  • 步骤5（SDK安装）完成前请勿创建旗标。
  • 请勿将决策点问题以聊天文本形式写出——使用结构化问题工具（参见决策点）。

References

参考资料

Continuity
  • Step 0 -- 
    LAUNCHDARKLY_ONBOARDING.md
    (working log; see Step 0)
Step 4 -- MCP (nested skill is primary)
  • 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
Step 5 -- SDK install (nested skills)
  • sdk-install/SKILL.md -- orchestrates detect -> plan -> apply (follow this first)
  • Detect repository stack
  • Generate integration plan
  • Apply code changes
First flag (Step 6)
  • Create first feature flag
Default follow-through
  • Onboarding Summary -- template for 
    LAUNCHDARKLY.md
  • Editor Rules and Skills
SDK index
  • SDK recipes
  • SDK snippets
Public flag skills (install via Step 3)
连续性
  • 步骤0 -- 
    LAUNCHDARKLY_ONBOARDING.md
    （工作日志；参见步骤0）
步骤4 -- MCP（嵌套技能为主要参考）
  • mcp-configure/SKILL.md——托管式MCP、验证、边缘情况（优先遵循此文档）
  • MCP UI链接——HTTPS + 
    command:
    链接，用于打开对应编辑器的MCP设置
  • MCP配置模板——按代理分类的JSON配置；当托管式MCP不可用时，通过
    npx
    运行本地服务器
步骤5 -- SDK安装（嵌套技能）
  • sdk-install/SKILL.md——编排检测 -> 规划 -> 实施流程（优先遵循此文档）
  • 检测仓库技术栈
  • 生成集成方案
  • 实施代码变更
首个旗标（步骤6）
  • 创建首个功能旗标
默认后续工作
  • 接入总结——
    LAUNCHDARKLY.md
    模板
  • 编辑器规则与技能
SDK索引
  • SDK参考示例
  • 代码片段
公共旗标技能（通过步骤3安装）