flag-release
Start the release of an existing LaunchDarkly flag that guards a pull request's change, from the project's flag release plan, or from each environment's release plan when the project has none, so the change releases safely after the PR merges. Honors a stated release intent (release now / hold / notBefore / segment / prerequisite): it never starts a release that would release a held environment. Use as the release step once the guarding flag exists and its code is wired. Keywords: start release, flag release, flag release plan, environment release plan, guarded rollout, progressive rollout, release intent, hold release, dark launch.
How do I install this agent skill?
npx skills add https://github.com/launchdarkly/ai-tooling --skill flag-releaseIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The Flag Release skill is a secure, vendor-authored tool designed to manage feature flag rollouts in LaunchDarkly. It uses a structured workflow that emphasizes human confirmation and specific API tools, avoiding dangerous operations like arbitrary code execution or direct credential handling.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Start a Flag's Release
You're using a skill that takes an existing feature flag (created OFF) that guards a pull request's change, and starts its release so the change releases safely after the PR merges, with no human toggling a flag. There are two ways to start it:
- From a flag release plan, with
create-flag-release. A flag release plan is an optional project-level recipe: it lists environments in release order, and for each one it names an environment release plan (rollout steps and metrics) or says the environment releases immediately. - From each environment's release plan, with
create-automated-rollout-config. This is the normal path for a project with no flag release plan, and for a request that a flag release plan cannot express. It names the environments to release and each one's environment release plan.
A human-stated release intent sits above every plan.
This is the release step of the PR flag workflow, and it's deliberately atomic:
| Step | Owned by |
|---|---|
| Decide whether to flag | should-flag-change (advisory) |
| Create the flag + wire the code | launchdarkly-flag-create |
| Start the release | this skill |
By the time this skill runs, the flag exists (OFF) and the guarding code is wired and pushed. This skill only starts the release. It never creates flags or edits code. It can be driven directly by an automation harness, or as the final step of the flag-and-release-change orchestrator.
The deploy is not the release. The merge ships the control path (flag OFF). The release is the flag operation that LaunchDarkly performs afterward, governed by the plans.
Honoring a hold is the one thing you must get right. Each recorded environment releases by its
triggerType. There is no per-call field for a hold or a date. An environment is held only when it is left out of the release, or hastriggerType: "manual"(it waits for a person). Never record an environment that the user holds with a trigger that releases it on its own (flag_eval,webhook, orpromotionafter a released environment). When in doubt, hold.
Prerequisites
- The remotely hosted LaunchDarkly MCP server.
- The guarding flag already exists in LaunchDarkly, created OFF, with the agreed key/tags.
- A pull-request reference (
repoFullName+ PR number) so the release follows the right merge. If you have only the PR URL (https://github.com/<owner>/<name>/pull/<number>), takerepoFullNameand the number from it. Without a PR reference, see No pull request.
MCP tools this skill uses:
create-flag-release— start the release from a flag release plan. SendprojectKey,flagKey,flagReleasePlanKey,pullRequest: { repoFullName, number }, andconfirm: true. A boolean flag sends no variation IDs. A multi-variate flag sends bothstartingVariationIdandendingVariationId. Returnsconfig_id.create-automated-rollout-config— start the release from each environment's release plan: the environments in order, each with its environment release plan and trigger. See references/auto-release.md. Returnsconfig_id.get-flag-release-plans— list the project's flag release plans (default: truemarks the default). Read one withflagReleasePlanKeyfor its environments, each withtriggerTypeandenvironmentReleasePlanKeyorisImmediate.get-environment-release-plans— read an environment's release plans (environmentKey), or one plan (releasePlanKey).get-flags— confirm the flag exists and is OFF before you start the release.get-projects— list the projects when the user has not named one, or (withprojectKey) list the project's environments when you need their keys.update-automated-rollout-config— change a release that has not started releasing (read it withget-automated-rollout-configfirst, then sendprojectKey,configId, the wholeenvironmentslist, andconfirm: true). The read is snake_case and the write is camelCase: rebuild each environment as references/auto-release.md says, so a non-default plan is not reverted. Use it when the user asks to change a release, instead of recording a second one.
To edit or remove a flag release plan or an environment release plan (update- and delete- tools), use launchdarkly-release-plans. This skill does not change plans.
create-flag-release and get-flag-release-plans are preview tools on the hosted server. If either is not listed, or a call returns tool disabled, start the release from each environment's release plan. Do not say the account lacks flag releases.
Full release model, triggers, precedence, previewing, prerequisites, metric adequacy: references/auto-release.md.
Plan Phase
Start nothing in this phase.
-
Confirm the project and the flag. If the user has not named a project, list the projects with
get-projects. If exactly one exists, use it, and name it to the user for confirmation before any write. Otherwise ask which project. Do not guess. Then callget-flagsto verify the guarding flag exists and is OFF. If it doesn't exist yet, stop: creation islaunchdarkly-flag-create's job. -
Choose how to start the release. Call
get-flag-release-planswithprojectKey. WhenhasMoreis true, read the next page withnextOffsetasoffset, untilhasMoreis false.- The user names a flag release plan, or the project has one with
default: true: use it. Read it withflagReleasePlanKeyto get its environments in order. - The user asks for "the default flag release plan", the list is not empty, and no plan has
default: true: ask which plan to use, or offer to start from each environment's release plan. Never pick the first listed plan. - Otherwise (an empty list, no default and no named plan, or the tools are not listed): start from each environment's release plan. This is a normal path. Do not ask the user to create a flag release plan first. You can mention that a flag release plan can be set up later with
launchdarkly-release-plans.
- The user names a flag release plan, or the project has one with
-
Preview each environment. Find what each environment will do:
isImmediateserves the new variation to everyone at once; an environment release plan runs its steps. Read each plan withget-environment-release-plans(projectKey,environmentKey, andreleasePlanKeyfor a named plan). To find an environment's default plan, list its plans and read every page (hasMore,nextOffset). A plan with metrics is guarded (a regression rolls it back). A plan without metrics is progressive. For a guarded plan, check that its metrics can compare this change (see the metric-adequacy note in references/auto-release.md). Note each environment'striggerType.If a release plan read fails (for example a 403 or 5xx from
get-flag-release-plansorget-environment-release-plans, orget-environment-release-plansis not listed), start nothing and record nothing. Tell the user which read failed. Do not start a release without knowing the plan, steps, and metrics of each environment. -
Capture the human's release intent. Ask (briefly, only if not already stated): release on merge, hold, or wait until a
notBeforedate? A cohort/segment to target first? A prerequisite parent flag this must not precede? Intent sits above the plans in precedence and is honored or explicitly held, never silently dropped. -
Check that the flag release plan fits the intent (only when step 2 chose one). Sort each environment into RELEASE, HOLD, or EXCLUDED. When the request or harness names the target environments, every other environment is EXCLUDED. When it names none, an environment that the user does not mention follows the plan.
- A HOLD environment fits only if the plan leaves it out, gives it
triggerType: "manual", or gives itpromotionafter a held environment. - A RELEASE environment fits only if the plan includes it with a trigger that releases it (
flag_eval,webhook, orpromotionafter a released environment). Apromotionenvironment after amanualor left-out environment waits for that environment, so it does not release on merge. - An EXCLUDED environment fits only if the plan leaves it out.
create-flag-releasecannot release a subset of the plan. - A
notBeforedate fits no flag release plan. LaunchDarkly cannot enforce the date.
If the plan does not fit, start from each environment's release plan instead, and tell the user why (which environment the plan would release, or which date it cannot hold). Copy the flag release plan's environments, plans, and triggers, as references/auto-release.md says.
An environment that should release on merge but would wait in the plan is different: copying the plan keeps the wait. Record nothing and ask first, as references/auto-release.md step 3 says. Ask about the first such environment in release order. For a
manualenvironment, ask whether to release it on merge or keep it waiting for a person. For apromotionenvironment after a held ormanualenvironment, ask whether to release it on merge without the environment it waits for, or keep the wait. Apromotionenvironment after an EXCLUDED environment needs no question: the first recorded entry starts onflag_eval. - A HOLD environment fits only if the plan leaves it out, gives it
-
Present the per-environment plan. Say how the release starts (the flag release plan's name, or "each environment's release plan"). For each environment, state one of these, with the reason:
- It releases immediately, and when (its trigger).
- It releases with an environment release plan. Name the plan, its steps, and its metrics.
- It is held: left out, or waiting for a person (
manual). Give the date or the reason. For a date, say that LaunchDarkly does not enforce it: a person must start the environment on or after the date. A scheduled start is a planned follow-up. - It is not part of this release (EXCLUDED).
Wait for confirmation; revise on feedback.
If the user or harness already asked you to start the release and gave the intent for the environments, that request is the confirmation. Show the plan and go on to the implement phase in the same turn. An environment whose intent the user leaves unclear ("not sure yet") is HOLD. Stop for an answer when an environment that should release on merge would wait in the plan.
Implement Phase
Only after confirmation (or a request to start the release that already states the intent):
-
Start the release.
- From a flag release plan: call
create-flag-releasewithprojectKey,flagKey,flagReleasePlanKey,pullRequest: { repoFullName, number }, andconfirm: true. If the call returnstool disabled, start from each environment's release plan instead. - From each environment's release plan: call
create-automated-rollout-configas references/auto-release.md says.
Do not copy the plans' steps or metrics anywhere: the plans stay the source. If a prerequisite parent flag was agreed, wire it if the MCP surface supports it; otherwise report it as a manual step.
- From a flag release plan: call
-
Verify. The call returns
config_idand the release as read back. Recordconfig_id. If it returns an error that says the release was created but the read-back failed, inspect it withget-automated-rollout-configand do not start it again. Report only what you verified. -
Report how the release started and
config_id; per environment, what releases and how (plan name, steps, metrics), what is held (and why), and what is not part of the release; and what happens after the merge (for example: "staging serves true when the flag is first evaluated there; production then startsguarded-prod, 10% → 25% → 50%, and rolls back iferror-rateregresses; dev is not part of this release"). Name any trigger you changed (for example apromotionenvironment that now starts on first evaluation because the environment before it is not part of the release).
Edge Cases
| Situation | Action |
|---|---|
| Flag doesn't exist yet | Stop: creation is launchdarkly-flag-create. |
| No pull request | If any environment to record uses webhook or flag_eval (including a left-out trigger, which means flag_eval), stop and ask for the PR: without one, the release can start before the change is deployed. A release whose environments all wait for a person (manual, or promotion after a manual environment) can start without one. |
| The flag already has an active release | LaunchDarkly returns an error that names it. Don't archive it yourself. Point the user to the existing release. |
| A rollout config already exists for this flag + PR | Don't record a second one with create-automated-rollout-config: a duplicate confuses the scheduler. Point the user to the existing config. To change it before it starts releasing, use update-automated-rollout-config with confirm: true. |
A release plan read fails (403, 5xx, or get-environment-release-plans is not listed) | Start nothing and record nothing. Tell the user which read failed. |
| The project has no flag release plan (an empty list) | Start from each environment's release plan. Do not ask the user to create a flag release plan first. |
| The user asks for the default flag release plan, and no plan is the default | Ask which plan to use, or offer to start from each environment's release plan. Never pick the first listed plan. |
The flag release plan does not fit the intent (an environment that the request excludes or holds, or a notBefore date) | Start from each environment's release plan, with the flag release plan's environments, plans, and triggers. Tell the user why. |
An environment that should release on merge would wait in the flag release plan (manual, or promotion after a held or manual environment) | Record nothing and ask about the first such environment. manual: release it on merge, or keep it waiting for a person. promotion after a held or manual environment: release it on merge without the environment it waits for, or keep the wait. Copying the plan keeps the wait. A promotion environment after an excluded environment needs no question. |
create-flag-release or get-flag-release-plans is not listed, or returns tool disabled | Start from each environment's release plan. |
| An environment release plan has more than one phase, or targets an audience | A release starts the plan's one phase on the flag's default rule, for everyone, and a flag release plan accepts only plans with exactly one phase. Tell the user the plan cannot release there; offer another plan, a hold, or a change to the plan. |
| User wants to hold an environment (no date) | Leave it out of the release, or use a flag release plan that makes it manual. Report it as held with the reason. |
User sets a notBefore date for an environment | Record it with triggerType: "manual". Say that LaunchDarkly does not enforce the date: a person must start it on or after the date. A scheduled start is a planned follow-up. |
| Every environment is held or not part of the release | Record nothing. Report each environment and why. |
| An environment that needs a release plan has no default release plan, and neither the user nor the flag release plan names one | Hold it. Do not pick another plan, also when it is the only plan. Say that auto-release cannot run there until it has a default release plan, and point to launchdarkly-release-plans. |
| Change depends on a parent flag not yet live | Couple them with a prerequisite (set it if the MCP surface supports it); otherwise report the coupling as a required manual step. Don't let this flag release before its parent. |
| An environment release plan is guarded but has no relevant metric | Say so: a guarded rollout with no meaningful metric guards nothing. Offer a plan with an immediate release there, or point at metric setup. |
What NOT to Do
- Don't create the flag or edit code: that's
launchdarkly-flag-create. This skill only starts the release. - Don't turn the flag on yourself, or toggle it after the release starts. The release owns that.
- Don't record a held environment with a trigger that releases it. No call field holds an environment.
- Don't skip the plan reads. Starting a release without knowing what each environment does is guessing.
- Don't silently release against a stated hold/
notBefore. Honor intent or hold, never drop it. - Don't require a flag release plan. A project without one releases from each environment's release plan.
- Don't create, change, or delete release plans: environment and flag release plans are managed by
launchdarkly-release-plans(and bylaunchdarkly-release-autopilot-onboardingat setup). - Don't handle or print credentials. Use the MCP server's OAuth and the user's existing git access; never read tokens from the machine.
References
- references/auto-release.md: the release model, triggers, precedence (intent → flag release plan → environment release plan), previewing, starting from a flag release plan or from each environment's release plan, changing a recorded release, prerequisites, metric adequacy. (Core of this skill.)
launchdarkly-release-plans: read, create, and manage environment and flag release plans.launchdarkly-release-autopilot-onboarding: set up release plans for a project.launchdarkly-guarded-rollout: for a bespoke rollout that no release plan expresses: hold that environment here and drive the guarded rollout by hand after merge.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/launchdarkly/ai-tooling/flag-release">View flag-release on skillZs</a>