diff --git a/skills/ai-configs/aiconfig-projects/README.md b/skills/ai-configs/aiconfig-projects/README.md index 2c65b01..e48531f 100644 --- a/skills/ai-configs/aiconfig-projects/README.md +++ b/skills/ai-configs/aiconfig-projects/README.md @@ -61,7 +61,7 @@ aiconfig-projects/ ## Related -- [LaunchDarkly AI Configs](https://docs.launchdarkly.com/home/ai-configs) — Create AI Configs after setting up projects +- [LaunchDarkly AI Configs](https://docs.launchdarkly.com/home/ai-configs): Create AI Configs after setting up projects - [LaunchDarkly Docs](https://docs.launchdarkly.com) - [Agent Skills Specification](https://agentskills.io/specification) diff --git a/skills/ai-configs/aiconfig-projects/SKILL.md b/skills/ai-configs/aiconfig-projects/SKILL.md index 7c9ffd1..623873a 100644 --- a/skills/ai-configs/aiconfig-projects/SKILL.md +++ b/skills/ai-configs/aiconfig-projects/SKILL.md @@ -22,15 +22,15 @@ You're using a skill that will guide you through setting up LaunchDarkly project 1. **Understand First**: Explore the codebase to understand the stack and patterns. 2. **Choose the Right Fit**: Select an approach that matches your architecture. 3. **Follow Conventions**: Respect existing code style and structure. -4. **Verify Integration**: Confirm the setup works — the agent performs checks and reports results. +4. **Verify Integration**: Confirm the setup works: the agent performs checks and reports results. ## API Key Detection Before prompting the user for an API key, try to detect it automatically: -1. **Check environment variables** — Look for `LAUNCHDARKLY_API_KEY`, `LAUNCHDARKLY_API_TOKEN`, or `LD_API_KEY` -2. **Check MCP config** — If using Claude, read `~/.claude/config.json` for `mcpServers.launchdarkly.env.LAUNCHDARKLY_API_KEY` -3. **Prompt user** — Only if detection fails, ask the user for their API key +1. **Check environment variables**: Look for `LAUNCHDARKLY_API_KEY`, `LAUNCHDARKLY_API_TOKEN`, or `LD_API_KEY` +2. **Check MCP config**: If using Claude, read `~/.claude/config.json` for `mcpServers.launchdarkly.env.LAUNCHDARKLY_API_KEY` +3. **Prompt user**: Only if detection fails, ask the user for their API key See [Quick Start](references/quick-start.md) for API usage patterns. diff --git a/skills/feature-flags/launchdarkly-flag-targeting/SKILL.md b/skills/feature-flags/launchdarkly-flag-targeting/SKILL.md index a315ced..2eec9eb 100644 --- a/skills/feature-flags/launchdarkly-flag-targeting/SKILL.md +++ b/skills/feature-flags/launchdarkly-flag-targeting/SKILL.md @@ -25,6 +25,9 @@ This skill requires the remotely hosted LaunchDarkly MCP server to be configured **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 @@ -74,7 +77,12 @@ Based on what the user wants and what you found, choose the right tool and strat Before applying changes, especially in production, run through the [Safety Checklist](references/safety-checklist.md). The key checks: 1. **Right environment?** Double-check you're targeting the intended environment. -2. **Approval required?** Some environments require approval workflows. If `toggle-flag` or other tools return `requiresApproval: true`, surface this to the user with the approval URL. +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](references/approval-workflows.md) 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. @@ -100,6 +108,16 @@ After applying changes, confirm the result: - "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](references/approval-workflows.md) 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. @@ -112,3 +130,4 @@ After applying changes, confirm the result: - [Targeting Patterns](references/targeting-patterns.md): Rollout strategies, rule construction, individual targeting, and cross-environment copying - [Safety Checklist](references/safety-checklist.md): Pre-change verification, approval workflows, environment awareness +- [Approval Workflows](references/approval-workflows.md): Creating, checking, and applying approval requests diff --git a/skills/feature-flags/launchdarkly-flag-targeting/marketplace.json b/skills/feature-flags/launchdarkly-flag-targeting/marketplace.json index 39d46cf..1b123a6 100644 --- a/skills/feature-flags/launchdarkly-flag-targeting/marketplace.json +++ b/skills/feature-flags/launchdarkly-flag-targeting/marketplace.json @@ -1,6 +1,6 @@ { "name": "launchdarkly-flag-targeting", - "description": "Control LaunchDarkly feature flag targeting including toggling, rollouts, rules, individual targets, and cross-environment copying", + "description": "Control LaunchDarkly feature flag targeting including toggling, rollouts, rules, individual targets, cross-environment copying, and approval workflows", "version": "1.0.0-experimental", "author": "LaunchDarkly", "repository": "https://github.com/launchdarkly/agent-skills", diff --git a/skills/feature-flags/launchdarkly-flag-targeting/references/approval-workflows.md b/skills/feature-flags/launchdarkly-flag-targeting/references/approval-workflows.md new file mode 100644 index 0000000..ca88f03 --- /dev/null +++ b/skills/feature-flags/launchdarkly-flag-targeting/references/approval-workflows.md @@ -0,0 +1,116 @@ +# 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": "", "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: "" + 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` diff --git a/skills/feature-flags/launchdarkly-flag-targeting/references/safety-checklist.md b/skills/feature-flags/launchdarkly-flag-targeting/references/safety-checklist.md index 267a4c5..138f8fd 100644 --- a/skills/feature-flags/launchdarkly-flag-targeting/references/safety-checklist.md +++ b/skills/feature-flags/launchdarkly-flag-targeting/references/safety-checklist.md @@ -24,9 +24,15 @@ Run through this checklist before applying any targeting changes, especially in Some environments require approval for changes. -- [ ] If the API returns `requiresApproval: true`, inform the user -- [ ] Provide the approval URL so they can follow the workflow -- [ ] Do NOT attempt to bypass approval +- [ ] 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](approval-workflows.md) for the complete reference. ### 5. Audit Trail