Index of every page on this site: llms.txt
All skills
launchdarkly avatar

/configs-targeting

@f0ee110 official
Run it yourself

Configure config targeting rules to control which variations serve to different users. Enable percentage rollouts, attribute-based rules, segment targeting, and guarded rollouts.

Use this Skill: https://skilld.dev/gh/launchdarkly/ai-tooling/configs-targeting

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈49 tokens for metadata: the name and description. ≈4.1k when used: this file. ≈339 more on demand in 1 file.

Description uses 2.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈198 characters, or 2.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Config Targeting

Configure targeting rules for configs to control which variations serve to different contexts. Works the same for both completion and agent mode.

Prerequisites

  • LaunchDarkly account with AgentControl enabled
  • Project key and environment key
  • Existing config with variations (use configs-create skill)

API Access

Use the LaunchDarkly MCP server tools: they authenticate via OAuth and need no token. The REST examples under Scripting without MCP are for code that runs without the agent; if the user wants one run in this session, ask them to paste an API access token and substitute it for {api_token}. Do not search environment variables, .env files, or agent/MCP config files for credentials.

Core Concepts

Evaluation Order

Targeting rules evaluate in this order (same as feature flags):

  1. Individual targets - Specific context keys (highest priority)
  2. Segment rules - Pre-defined segments
  3. Custom rules - Attribute-based conditions (evaluated in order)
  4. Default rule - Fallthrough for all others
  5. Off variation - When targeting is disabled

Key Concepts

  • Variations: MCP targetingInstructions and fallthrough take variationKey (a variation key or name) or variationId (a UUID from the targeting read). Raw REST needs the UUID.
  • Weights: Thousandths (50000 = 50%, 100000 = 100%)
  • Clause logic: Multiple clauses = AND, multiple values = OR
  • Null attributes: Rules with null/missing attributes are skipped

Workflow

Every write below is one update-agent-config call with resource: "targeting" and requires confirm: true. Show the user the change and pass it only after they agree. A single call may combine on, fallthrough, and targetingInstructions.

Step 1: Get Targeting

Call get-agent-configs with projectKey, configKey, section: "targeting", and env. The response lists the variations (key, name, and _id), the rules with their _ids, individual targets, and the current fallthrough.

Step 2: Edit the Default Rule

Set the default rule to the variation you created with fallthrough:

{
  "projectKey": "my-project",
  "configKey": "chat-assistant",
  "resource": "targeting",
  "env": "production",
  "fallthrough": {"variationKey": "default"},
  "confirm": true
}

For a percentage split, pass fallthrough as {"weights": [{"variationKey": "default", "percent": 80}, {"variationKey": "experimental", "percent": 20}]}; the percents sum to 100. Add contextKind or bucketBy beside weights to change what is bucketed.

Important: The turnTargetingOn instruction does not work for configs. A new config serves its disabled variation until you set the default rule.

Step 3: Add Targeting Rules

Use targetingInstructions. It accepts addRule, removeRule, replaceRules, reorderRules, updateRuleDescription, addClauses, removeClauses, addValuesToClause, removeValuesFromClause, and updateClause.

Attribute-based rule:

{
  "projectKey": "my-project",
  "configKey": "model-selector",
  "resource": "targeting",
  "env": "production",
  "targetingInstructions": [{
    "kind": "addRule",
    "clauses": [{
      "contextKind": "user",
      "attribute": "selectedModel",
      "op": "contains",
      "values": ["sonnet"],
      "negate": false
    }],
    "variationKey": "sonnet"
  }],
  "comment": "Route sonnet requests",
  "confirm": true
}

Percentage rollout on a rule: send an addRule instruction with percentageRolloutConfig in place of variationKey, as in the Manual Percentage Rollout shape below.

Segment rule: a clause with attribute: "segmentMatch", op: "segmentMatch", an empty contextKind, and the segment keys as values.

Step 4: Target Individuals

Use targetingInstructions with addTargets, removeTargets, replaceTargets, or clearTargets. addTargets and removeTargets require contextKind and values:

{
  "projectKey": "my-project",
  "configKey": "chat-assistant",
  "resource": "targeting",
  "env": "production",
  "targetingInstructions": [{"kind": "addTargets", "contextKind": "user", "variationKey": "experimental", "values": ["user-123"]}],
  "confirm": true
}

Step 5: Verify

Call get-agent-configs with section: "targeting" again and confirm the fallthrough, rules, and targets match what the user approved.

Scripting without MCP

For CI or scripts that can't use the MCP server, the same steps go through the REST API's semantic patch endpoint:

PATCH /api/v2/projects/{projectKey}/ai-configs/{configKey}/targeting
Content-Type: application/json; domain-model=launchdarkly.semanticpatch
import requests
import os
from typing import Dict, List, Optional

class AIConfigTargeting:
    """Manager for config targeting rules"""

    def __init__(self, api_token: str, project_key: str):
        self.api_token = api_token
        self.project_key = project_key
        self.base_url = "https://app.launchdarkly.com/api/v2"

    def get_targeting(self, config_key: str) -> Optional[Dict]:
        """Get current targeting with variation IDs."""
        url = f"{self.base_url}/projects/{self.project_key}/ai-configs/{config_key}/targeting"

        response = requests.get(url, headers={
            "Authorization": self.api_token,
            "LD-API-Version": "beta"
        })

        if response.status_code == 200:
            return response.json()
        print(f"[ERROR] {response.status_code}: {response.text}")
        return None

    def get_variation_id(self, config_key: str, variation_key: str) -> Optional[str]:
        """Look up variation UUID from key or name."""
        targeting = self.get_targeting(config_key)
        if targeting:
            for var in targeting.get("variations", []):
                if var.get("key") == variation_key or var.get("name") == variation_key:
                    return var.get("_id")
        return None

    def update_targeting(self, config_key: str, environment: str,
                         instructions: List[Dict], comment: str = "") -> Optional[Dict]:
        """Send semantic patch instructions."""
        url = f"{self.base_url}/projects/{self.project_key}/ai-configs/{config_key}/targeting"

        payload = {"environmentKey": environment, "instructions": instructions}
        if comment:
            payload["comment"] = comment

        response = requests.patch(url, headers={
            "Authorization": self.api_token,
            "Content-Type": "application/json; domain-model=launchdarkly.semanticpatch",
            "LD-API-Version": "beta"
        }, json=payload)

        if response.status_code == 200:
            return response.json()
        print(f"[ERROR] {response.status_code}: {response.text}")
        return None

    def enable_config(self, config_key: str, environment: str,
                      variation_key: str = "default") -> bool:
        """
        Enable a config by setting fallthrough to an enabled variation.

        Note: turnTargetingOn doesn't work for configs. Instead, set the
        fallthrough from the disabled variation (index 0) to an enabled one.
        """
        variation_id = self.get_variation_id(config_key, variation_key)
        if not variation_id:
            print(f"[ERROR] Variation '{variation_key}' not found")
            return False
        return self.set_fallthrough(config_key, environment, variation_id)

    def add_rule(self, config_key: str, environment: str,
                 clauses: List[Dict], variation: int,
                 description: str = "") -> bool:
        """Add targeting rule serving a specific variation index."""
        instruction = {
            "kind": "addRule",
            "clauses": clauses,
            "variation": variation
        }
        if description:
            instruction["description"] = description

        result = self.update_targeting(config_key, environment,
            [instruction], f"Add rule: {description}")
        if result:
            print(f"[OK] Rule added")
            return True
        return False

    def add_rollout_rule(self, config_key: str, environment: str,
                         clauses: List[Dict],
                         weights: List[Dict],
                         bucket_by: str = "key") -> bool:
        """
        Add percentage rollout rule.

        weights: [{"variation": 0, "weight": 50000}, {"variation": 1, "weight": 50000}]
        """
        result = self.update_targeting(config_key, environment, [{
            "kind": "addRule",
            "clauses": clauses,
            "percentageRolloutConfig": {
                "contextKind": "user",
                "bucketBy": bucket_by,
                "variations": weights
            }
        }], "Add percentage rollout")
        if result:
            print(f"[OK] Rollout rule added")
            return True
        return False

    def set_fallthrough(self, config_key: str, environment: str,
                        variation_id: str) -> bool:
        """Set default (fallthrough) variation by UUID."""
        result = self.update_targeting(config_key, environment, [{
            "kind": "updateFallthroughVariationOrRollout",
            "variationId": variation_id
        }], "Set fallthrough")
        if result:
            print(f"[OK] Fallthrough set")
            return True
        return False

    def target_individuals(self, config_key: str, environment: str,
                          context_keys: List[str], variation: int,
                          context_kind: str = "user") -> bool:
        """Target specific context keys."""
        result = self.update_targeting(config_key, environment, [{
            "kind": "addTargets",
            "variation": variation,
            "contextKind": context_kind,
            "values": context_keys
        }], f"Target {len(context_keys)} individuals")
        if result:
            print(f"[OK] Individual targets added")
            return True
        return False

    def target_segment(self, config_key: str, environment: str,
                      segment_keys: List[str], variation: int) -> bool:
        """Target a segment."""
        result = self.update_targeting(config_key, environment, [{
            "kind": "addRule",
            "clauses": [{
                "attribute": "segmentMatch",
                "contextKind": "",  # Leave blank for segments
                "op": "segmentMatch",
                "values": segment_keys,
                "negate": False
            }],
            "variation": variation
        }], f"Target segments: {segment_keys}")
        if result:
            print(f"[OK] Segment targeting added")
            return True
        return False

    def clear_rules(self, config_key: str, environment: str) -> bool:
        """Remove all targeting rules."""
        result = self.update_targeting(config_key, environment,
            [{"kind": "replaceRules", "rules": []}], "Clear all rules")
        if result:
            print(f"[OK] All rules cleared")
            return True
        return False

Instruction Reference

Note: turnTargetingOn and turnTargetingOff do not work for configs. Configs have targeting enabled by default. To "enable" a config, set the fallthrough to an enabled variation using updateFallthroughVariationOrRollout.

Rules

Kind Description
addRule Add rule with clauses and variation/rollout
removeRule Remove by ruleId
replaceRules Replace all rules
reorderRules Change evaluation order
updateRuleVariationOrRollout Update what a rule serves

Fallthrough

Kind Description
updateFallthroughVariationOrRollout Set default variation or rollout

Individual Targets

Kind Description
addTargets Target specific context keys
removeTargets Remove specific targets
replaceTargets Replace all targets

Operators Reference

Operator Description Example
in Value in list ["premium", "enterprise"]
contains String contains ["sonnet"]
startsWith String prefix ["user-"]
endsWith String suffix [".edu"]
matches Regex match ["^user-\\d+$"]
greaterThan / lessThan Numeric comparison [100]
before / after Date comparison ["2024-12-31T00:00:00Z"]
semVerEqual / semVerGreaterThan Version comparison ["2.0.0"]
segmentMatch Segment membership ["beta-testers"]

Clause Structure

{
  "contextKind": "user",
  "attribute": "email",
  "op": "endsWith",
  "values": [".edu"],
  "negate": false
}
  • Multiple clauses = AND (all must match)
  • Multiple values = OR (any can match)
  • negate: true inverts the operator

Rollout Types

Manual Percentage Rollout

{
  "percentageRolloutConfig": {
    "contextKind": "user",
    "bucketBy": "key",
    "variations": [
      {"variation": 0, "weight": 50000},
      {"variation": 1, "weight": 50000}
    ]
  }
}

Progressive Rollout

{
  "progressiveRolloutConfig": {
    "contextKind": "user",
    "controlVariation": 1,
    "endVariation": 0,
    "steps": [
      {"rolloutWeight": 1000, "duration": {"quantity": 4, "unit": "hour"}},
      {"rolloutWeight": 5000, "duration": {"quantity": 4, "unit": "hour"}},
      {"rolloutWeight": 10000, "duration": {"quantity": 4, "unit": "hour"}}
    ]
  }
}

Guarded Rollout

{
  "guardedRolloutConfig": {
    "randomizationUnit": "user",
    "stages": [
      {"rolloutWeight": 1000, "monitoringWindowMilliseconds": 17280000},
      {"rolloutWeight": 5000, "monitoringWindowMilliseconds": 17280000}
    ],
    "metrics": [{
      "metricKey": "error-rate",
      "onRegression": {"rollback": true},
      "regressionThreshold": 0.01
    }]
  }
}

Common Patterns

Model Routing by Attribute

# Route based on selectedModel context attribute
targeting.add_rule(
    config_key="model-selector",
    environment="production",
    clauses=[{
        "contextKind": "user",
        "attribute": "selectedModel",
        "op": "contains",
        "values": ["sonnet"],
        "negate": False
    }],
    variation=0,  # Sonnet variation index
    description="Route sonnet requests"
)

Tier-Based Variation

targeting.add_rule(
    config_key="chat-assistant",
    environment="production",
    clauses=[{
        "contextKind": "user",
        "attribute": "tier",
        "op": "in",
        "values": ["premium", "enterprise"],
        "negate": False
    }],
    variation=0  # Premium model variation
)

Segment Targeting

targeting.target_segment(
    config_key="chat-assistant",
    environment="production",
    segment_keys=["beta-testers"],
    variation=1  # Experimental variation
)

Error Handling

Status Cause Solution
400 Invalid semantic patch Check instruction format, ops must be lowercase
403 Insufficient permissions Check API token
404 Config not found Verify projectKey and configKey
422 Invalid variation Use index (0, 1, 2...) or UUID from targeting response

Next Steps

After configuring targeting:

  1. Provide config URL:
    https://app.launchdarkly.com/projects/{projectKey}/ai-configs/{configKey}
  2. Monitor performance with built-in-metrics
  3. Attach judges with online-evals
  4. Set up guarded rollouts for automatic regression detection

Related Skills

  • configs-create - Create configs with variations
  • configs-variations - Manage variations
  • online-evals - Attach judges
  • segments - Create segments for targeting

Other Resources

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts11d3 checks · Risk SAFE
  • Gen Agent Trust Hub15d

    The skill facilitates managing LaunchDarkly configuration targeting rules. It interacts exclusively with official LaunchDarkly API endpoints and includes explicit instructions to avoid scraping local credentials, requiring user confirmation for all write operations.

  • Socket11d

    No alerts

  • Snyk15d

    Risk: LOW · No issues

Signed by skilld at f0ee110. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 weeks ago
metadata
{
  "author": "launchdarkly",
  "version": "0.1.0"
}
Other metadata
compatibility
Requires the remotely hosted LaunchDarkly MCP server. Scripted setup without MCP needs an API access token with ai-configs:write permission.
  • API
  • launchdarkly
  • feature-flags
  • targeting
  • rollouts
  • segments
  • config-management
  • semantic-patch

README badge

README badge for launchdarkly/ai-tooling/configs-targeting

Configures targeting rules for LaunchDarkly AI configs to control which variations serve to different contexts via percentage rollouts, attribute-based rules, and segment targeting. Uses the LaunchDarkly semantic patch API with individual targets, custom rules, and fallthrough defaults evaluated in order.

Generated from the current SKILL.md.

Does this skill work with LaunchDarkly feature flags or only configs?
This skill targets LaunchDarkly configs (AI-specific targeting) only, not feature flags. The semantic patch API and instruction set are specific to the ai-configs endpoint.
Do I need to fetch variation IDs before setting up targeting rules?
Yes. The skill requires variation UUIDs (not keys) to configure rules. You must call the GET targeting endpoint first to retrieve the _id field for each variation.
Can I use turnTargetingOn to enable a config?
No. The turnTargetingOn instruction does not work for configs. Instead, use updateFallthroughVariationOrRollout to set the fallthrough to an enabled variation.
What permissions does my API token need?
Your LaunchDarkly API token must have ai-configs:write permission to modify targeting rules.
Does this support percentage rollouts and segment targeting?
Yes. The skill supports percentage rollouts via percentageRolloutConfig, attribute-based rules, individual context targeting, and segment targeting via segmentMatch clauses.

Generated from the current SKILL.md. These answers refresh after source changes.