Launchdarkly Flag Targeting

LaunchDarkly Flag Targeting & Rollout

You're using a skill that will guide you through changing who sees what for a feature flag. Your job is to understand the current state of the flag, figure out the right targeting approach for what the user wants, make the changes safely, and verify the resulting state.

Prerequisites

This skill requires the remotely hosted LaunchDarkly MCP server to be configured in your environment.

Required MCP tools:

• get-flag: understand current state before making changes
• toggle-flag: turn targeting on or off for a flag in an environment
• update-rollout: change the default rule (fallthrough) variation or percentage rollout
• update-targeting-rules: add, remove, or modify custom targeting rules
• update-individual-targets: add or remove specific users/contexts from individual targeting

Optional MCP tools:

• copy-flag-config: copy targeting configuration from one environment to another
• create-approval-request: create an approval request when direct changes are blocked
• list-approval-requests: check on pending approval requests for a flag
• apply-approval-request: apply an already-approved approval request

Core Concept: Evaluation Order

Before making any targeting changes, understand how LaunchDarkly evaluates flags. This determines what your changes actually do:

1. Flag is OFF -> Serve the offVariation to everyone. Nothing else matters. 2. Individual targets -> If the context matches a specific target list, serve that variation. Highest priority. 3. Custom rules -> Evaluate rules top-to-bottom. First matching rule wins. 4. Default rule (fallthrough) -> If nothing else matched, serve this variation or rollout.

This means: if you add a targeting rule but the flag is OFF, nobody sees the change. If you set a percentage rollout on the default rule but there's an individual target, that targeted user bypasses the rollout.

Workflow

Step 1: Understand Current State

Before changing anything, check what's already configured.

1. Confirm the environment. "Turn it on" without specifying an environment is ambiguous. Always confirm which environment the user means. Default to asking rather than assuming. 2. Fetch the flag. Use get-flag with the target environment to see:

• on: Is targeting currently enabled?
• fallthrough: What's the default rule? (variation or percentage rollout)
• offVariation: What serves when the flag is off?
• rules: Any custom targeting rules?
• targets: Any individually targeted users/contexts?
• prerequisites: Any flags this depends on?

3. Assess complexity. A flag with no rules and no individual targets is simple. A flag with multiple rules, targets, and prerequisites needs more care.

Step 2: Determine the Right Approach

Based on what the user wants and what you found, choose the right tool and strategy. See Targeting Patterns for the full reference.

Common scenarios:

Step 3: Run the Safety Checklist

Before applying changes, especially in production, run through the Safety Checklist. The key checks:

1. Right environment? Double-check you're targeting the intended environment. 2. Approval required? Some environments require approval workflows. If any mutation tool returns requiresApproval: true:

• Inform the user that this environment requires approvals.
• Share the approvalUrl if provided.
• Offer to create an approval request using create-approval-request with the same instructions (returned in the instructions field of the response).
• Do NOT attempt to bypass approval or auto-approve.
• See Approval Workflows for the full process.

3. Prerequisite flags? If this flag has prerequisites, they must be met before targeting works as expected. 4. Rule ordering impact? If adding rules, consider where they fall in evaluation order. Rules evaluate top-to-bottom, first match wins. 5. Include a comment. Always add an audit trail comment, especially for production changes.

Step 4: Apply Changes

Use the appropriate tool for the change. Key notes:

• `toggle-flag`: Specify on: true or on: false, the env, and a comment.
• `update-rollout`: Use rolloutType: "percentage" with human-friendly weights (e.g., 80 for 80%) that sum to 100, or rolloutType: "variation" with a variationIndex.
• `update-targeting-rules`: Instructions support addRule, removeRule, updateRuleVariationOrRollout, addClauses, removeClauses, reorderRules.
• `update-individual-targets`: Instructions support addTargets, removeTargets, addContextTargets, removeContextTargets, replaceTargets.

See Targeting Patterns for detailed instruction examples.

Step 5: Verify

After applying changes, confirm the result:

1. Fetch the updated flag. Use get-flag again to verify the new state. 2. Confirm what the user expects. Describe the resulting targeting in plain language:

• "The flag is now ON in production, serving true to 25% of users and false to 75%."
• "Beta users now see variation A. Everyone else gets the default (variation B)."

3. Check for side effects. If there are rules or individual targets, make sure the change interacts correctly with them.

Handling Approval-Required Environments

When any mutation tool returns requiresApproval: true, the direct change was blocked because the environment requires approvals. Follow the Approval Workflows reference to:

1. Create an approval request with create-approval-request using the instructions from the blocked response 2. Inform the user about the pending approval and share the approval request details 3. Check on approval status later with list-approval-requests if requested 4. Apply the request with apply-approval-request once a reviewer has approved it (reviewStatus is "approved") 5. Verify the result with get-flag after applying

Important Context

• `update-rollout` uses human-friendly percentages. Pass 80 for 80%, not 80000. The tool handles the internal weight conversion.
• Weights must sum to 100. For percentage rollouts, the weights across all variations must total exactly 100.
• Rule ordering matters. Rules evaluate top-to-bottom. Reordering rules can change behavior without changing any individual rule.
• Individual targets are highest priority. They override all rules and the default. Adding someone as an individual target means rules don't apply to them.
• "Launched" flags are still ON. A flag with status "launched" is serving a single variation to everyone. If you want to remove the flag, use the cleanup skill, not targeting changes.

References

• Targeting Patterns: Rollout strategies, rule construction, individual targeting, and cross-environment copying
• Safety Checklist: Pre-change verification, approval workflows, environment awareness
• Approval Workflows: Creating, checking, and applying approval requests

LaunchDarkly Flag Targeting Skill

An Agent Skill for controlling feature flag targeting, rollouts, and rules in LaunchDarkly.

Overview

This skill teaches agents how to:

• Understand current flag targeting state before making changes
• Toggle flags on/off safely
• Set up percentage rollouts
• Add and manage targeting rules
• Manage individual user/context targets
• Copy targeting config between environments
• Follow safety practices for production changes

Installation (Local)

For now, install by placing this skill directory where your agent client loads skills.

Examples:

• Generic: copy skills/feature-flags/launchdarkly-flag-targeting/ into your client's skills path

Prerequisites

This skill requires the remotely hosted LaunchDarkly MCP server to be configured in your environment. The remote server provides higher-level, agent-optimized tools that orchestrate multiple API calls and return pruned, actionable responses.

Refer to your LaunchDarkly account settings for instructions on connecting to the remotely hosted MCP server.

Usage

Once installed, the skill activates automatically when you ask about flag targeting:

Turn on the new-checkout flag in staging

Roll out dark-mode to 25% of users in production

Target beta users for the new-pricing feature

Copy the staging config for checkout-v2 to production

Structure

launchdarkly-flag-targeting/
├── SKILL.md
├── marketplace.json
├── README.md
└── references/
    ├── targeting-patterns.md
    └── safety-checklist.md

Related

• LaunchDarkly Flag Create: Create flags before targeting them
• LaunchDarkly Flag Discovery: Audit flags and understand the landscape
• LaunchDarkly MCP Server
• LaunchDarkly Docs

License

Apache-2.0

Approval Workflows

Some LaunchDarkly environments require approval before changes take effect. This is an Enterprise feature configured per environment. When this happens, mutation tools like toggle-flag, update-rollout, update-targeting-rules, update-individual-targets, and copy-flag-config return requiresApproval: true instead of making the change directly.

Detecting Approval Requirements

Any mutation tool response may include these fields when a change is blocked:

• requiresApproval: true: the change was blocked and needs approval
• approvalUrl: a URL where the approval can be reviewed (if available)
• message: a human-readable explanation
• instructions: the semantic patch instructions that were attempted (use these to create an approval request)

Creating an Approval Request

When a change is blocked, use create-approval-request to submit the change for review:

1. Use the same instructions returned in the blocked response's instructions field 2. Provide a clear description explaining what the change does and why 3. Optionally notify specific team members (notifyMemberIds) or teams (notifyTeamKeys)

Example: Toggle flag with approval

If toggle-flag returns requiresApproval: true:

Tool: create-approval-request
Input:
  projectKey: "my-project"
  flagKey: "new-checkout"
  env: "production"
  instructions: [{"kind": "turnFlagOn"}]
  description: "Enable new checkout flow in production after successful staging test"

Example: Rollout with approval

If update-rollout returns requiresApproval: true with instructions:

Tool: create-approval-request
Input:
  projectKey: "my-project"
  flagKey: "new-checkout"
  env: "production"
  instructions: [{"kind": "updateFallthroughVariationOrRollout", "rolloutWeights": {"var-id-1": 25000, "var-id-2": 75000}}]
  description: "Roll out new checkout to 25% of users in production"

Example: Targeting rule with approval

If update-targeting-rules returns requiresApproval: true:

Tool: create-approval-request
Input:
  projectKey: "my-project"
  flagKey: "new-checkout"
  env: "production"
  instructions: [{"kind": "addRule", "clauses": [{"contextKind": "user", "attribute": "email", "op": "endsWith", "values": ["@company.com"]}], "variationId": "<variation-id>", "description": "Internal users"}]
  description: "Add targeting rule for internal users in production"

Checking Approval Status

Use list-approval-requests to see pending requests for a flag:

Tool: list-approval-requests
Input:
  projectKey: "my-project"
  flagKey: "new-checkout"
  env: "production"

The response shows:

• status: pending, completed, or failed
• reviewStatus: pending, approved, or declined
• reviews: list of reviewer actions with status and comments
• description: what the change does
• instructionCount: number of instructions in the request

Applying Approved Requests

Once a reviewer approves the request (reviewStatus is "approved"), use apply-approval-request:

Tool: apply-approval-request
Input:
  projectKey: "my-project"
  id: "<approval-request-id>"
  comment: "Applying approved production rollout"

After applying, verify the change with get-flag.

Important: The agent can apply already-approved requests but must NEVER approve requests itself. Approval is a human decision.

What the Agent Should NOT Do

• Do NOT auto-approve: The purpose of approvals is human oversight. Never try to approve a request.
• Do NOT retry the direct change: If a change was blocked, retrying the same mutation will also be blocked. Use the approval workflow.
• Do NOT skip informing the user: Always tell the user that approval is required and what the next steps are.
• Do NOT bypass approval: Never use workarounds or alternative API calls to skip the approval process.

Typical Flow

1. User asks for a targeting change (e.g., "turn on the flag in production") 2. Agent attempts the change using the mutation tool 3. Tool returns requiresApproval: true with instructions 4. Agent informs the user and offers to create an approval request 5. If the user agrees, agent creates the request with create-approval-request 6. Agent shares the approval request details (ID, approval URL if available) 7. A human reviewer approves or declines the request (outside the agent) 8. If approved, the user or agent can apply it with apply-approval-request 9. Agent verifies the change with get-flag

Targeting Safety Checklist

Run through this checklist before applying any targeting changes, especially in production.

Before Every Change

1. Right Environment?

• [ ] Confirmed the environment with the user (don't assume "production")
• [ ] If the user said "turn it on" without specifying, ask which environment

2. Right Flag?

• [ ] Confirmed the flag key matches what the user intends
• [ ] If the flag key could be ambiguous, verify with get-flag

3. Understand Current State

• [ ] Fetched the flag's current configuration in the target environment
• [ ] Noted the current on state, rules, and targets
• [ ] Identified any prerequisites that must be met

4. Approval Required?

Some environments require approval for changes.

• [ ] If any mutation tool returns requiresApproval: true, inform the user
• [ ] Provide the approval URL if one was returned
• [ ] Offer to create an approval request with create-approval-request using the returned instructions
• [ ] Include a clear description of the intended change in the approval request
• [ ] Do NOT attempt to bypass approval or auto-approve
• [ ] If checking on a previous request, use list-approval-requests
• [ ] Only apply a request (apply-approval-request) if reviewStatus is "approved"

See Approval Workflows for the complete reference.

5. Audit Trail

• [ ] Added a comment to the change explaining what and why
• [ ] This is especially important for production changes

For Percentage Rollouts

• [ ] Weights sum to exactly 100% (100000 in the API)
• [ ] The rollout is on the default rule (fallthrough) unless intentionally on a specific rule
• [ ] Individual targets and higher-priority rules aren't silently overriding the rollout for some users
• [ ] Consider starting small (1-5%) for high-risk features

For Targeting Rules

• [ ] New rules are placed at the correct position in evaluation order
• [ ] Clauses correctly express the targeting intent (AND within a rule, OR between rules)
• [ ] The negate field is set correctly (default false)
• [ ] The context kind matches what the codebase sends (e.g., user, device, organization)
• [ ] Attribute names match exactly what the SDK sends (case-sensitive)

For Individual Targets

• [ ] The values match exactly what the SDK sends as the user/context key
• [ ] Individual targets are intended to override rules (they always win)
• [ ] Using replaceTargets intentionally: it replaces ALL targets, not just adds

For Cross-Environment Copies

• [ ] Source environment is the one you tested in
• [ ] Target environment is correct
• [ ] You've selected the right included actions (don't accidentally copy ON state to production if you only meant to copy rules)
• [ ] Target environment's approval requirements are considered

Production-Specific Checks

For any change to a production environment:

• [ ] Change has been tested in a lower environment first (staging, dev)
• [ ] Rollback plan is clear (what to do if something goes wrong)
• [ ] Comment explains the change for audit trail
• [ ] If doing a percentage rollout, start with a small percentage first

After the Change

• [ ] Verified the new state with get-flag
• [ ] Described the resulting targeting to the user in plain language
• [ ] Confirmed the change achieves what the user asked for

Targeting Patterns

Reference for all targeting operations available through the LaunchDarkly API semantic patch system.

Toggle Flag On/Off

The simplest targeting change.

{"kind": "turnFlagOn"}

{"kind": "turnFlagOff"}

Notes:

• Turning a flag OFF makes it serve the offVariation to everyone, regardless of rules or targets.
• Turning a flag ON activates the full targeting evaluation (individual targets -> rules -> default rule).

Percentage Rollouts (Default Rule)

The default rule (fallthrough) is what applies when no individual targets or custom rules match.

Serve a single variation to everyone

{
  "kind": "updateFallthroughVariationOrRollout",
  "variationId": "<variation-id>"
}

Or by index:

{
  "kind": "updateFallthroughVariationOrRollout",
  "variationId": "<variation-id-of-index-0>"
}

Percentage rollout

{
  "kind": "updateFallthroughVariationOrRollout",
  "rolloutWeights": {
    "<variation-id-0>": 25000,
    "<variation-id-1>": 75000
  }
}

Note on weights: The API uses weights scaled by 1000. So:

• 25% = 25000
• 50% = 50000
• 75% = 75000
• 100% = 100000

Weights must sum to 100000.

Common rollout patterns

Custom Targeting Rules

Rules let you target specific segments of users based on context attributes.

Add a rule

{
  "kind": "addRule",
  "clauses": [
    {
      "contextKind": "user",
      "attribute": "email",
      "op": "endsWith",
      "values": ["@company.com"],
      "negate": false
    }
  ],
  "variationId": "<variation-id>",
  "description": "Internal users"
}

Rule clause operators

Multiple clauses (AND logic)

Clauses within a single rule are ANDed. All must match for the rule to apply:

{
  "kind": "addRule",
  "clauses": [
    {
      "contextKind": "user",
      "attribute": "plan",
      "op": "in",
      "values": ["enterprise"]
    },
    {
      "contextKind": "user",
      "attribute": "country",
      "op": "in",
      "values": ["US"]
    }
  ],
  "variationId": "<variation-id>",
  "description": "US enterprise users"
}

Rule with percentage rollout

Instead of serving a single variation, a rule can do a percentage rollout:

{
  "kind": "addRule",
  "clauses": [
    {
      "contextKind": "user",
      "attribute": "beta",
      "op": "in",
      "values": [true]
    }
  ],
  "rolloutWeights": {
    "<variation-id-0>": 50000,
    "<variation-id-1>": 50000
  },
  "description": "50/50 for beta users"
}

Remove a rule

{
  "kind": "removeRule",
  "ruleId": "<rule-id>"
}

The ruleId (also shown as _id) can be found in the flag's current configuration.

Reorder rules

{
  "kind": "reorderRules",
  "ruleIds": ["<rule-id-1>", "<rule-id-2>", "<rule-id-3>"]
}

Rule order matters: rules evaluate top to bottom, first match wins.

Update a rule's variation

{
  "kind": "updateRuleVariationOrRollout",
  "ruleId": "<rule-id>",
  "variationId": "<variation-id>"
}

Add/remove clauses on a rule

{
  "kind": "addClauses",
  "ruleId": "<rule-id>",
  "clauses": [
    {
      "contextKind": "user",
      "attribute": "country",
      "op": "in",
      "values": ["UK"]
    }
  ]
}

{
  "kind": "removeClauses",
  "ruleId": "<rule-id>",
  "clauseIds": ["<clause-id>"]
}

Individual Targets

Individual targets are the highest priority: they override all rules.

Add users to a variation

{
  "kind": "addTargets",
  "variationId": "<variation-id>",
  "values": ["user-key-1", "user-key-2"]
}

Remove users from a variation

{
  "kind": "removeTargets",
  "variationId": "<variation-id>",
  "values": ["user-key-1"]
}

Context-kind targets (non-user)

For custom context kinds (device, organization, etc.):

{
  "kind": "addContextTargets",
  "contextKind": "organization",
  "variationId": "<variation-id>",
  "values": ["org-123", "org-456"]
}

{
  "kind": "removeContextTargets",
  "contextKind": "organization",
  "variationId": "<variation-id>",
  "values": ["org-123"]
}

Replace all targets for a variation

{
  "kind": "replaceTargets",
  "variationId": "<variation-id>",
  "values": ["user-key-1", "user-key-2"]
}

Warning: This replaces ALL targets for the variation, not just adds to them.

Cross-Environment Config Copying

Copy targeting configuration from one environment to another.

This is a separate API call (not a semantic patch). Use the flag copy endpoint:

• Source: The environment to copy from
• Target: The environment to copy to
• Included actions: Selectively copy updateOn (toggle state), updateRules, updateFallthrough, updateOffVariation, updatePrerequisites, updateTargets

Common use case: promote staging to production

Copy the full targeting config from staging after testing:

source: "staging"
target: "production"
includedActions: ["updateOn", "updateRules", "updateFallthrough", "updateOffVariation", "updateTargets"]

Note: The target environment may have approval requirements. If so, the copy operation creates an approval request instead of applying immediately.

Batching Instructions

Multiple instructions can be batched. For example, turning on and setting a rollout in one call to toggle-flag and update-rollout, or sending multiple rule changes to update-targeting-rules:

{
  "environmentKey": "production",
  "instructions": [
    {"kind": "turnFlagOn"},
    {
      "kind": "updateFallthroughVariationOrRollout",
      "rolloutWeights": {
        "<variation-id-0>": 10000,
        "<variation-id-1>": 90000
      }
    }
  ],
  "comment": "Turning on with 10% rollout"
}

This is preferred over multiple separate calls: it's atomic (all changes apply together or none do).