Add post-creation workflow and rollout type guidance to flag targeting skill

[Copilot]

Agents were missing two critical patterns: newly created flags have targeting OFF by default, and 100% rollouts should use rolloutType: "variation" not percentage with [0,0,0,100].

Changes

• New section: "Working with Newly Created Flags" — Documents that targeting defaults to OFF and must be explicitly enabled. Provides 4-step post-creation workflow.

• Enhanced "Common scenarios" table — Clarifies when to use percentage rollout ("splitting traffic between variations") vs variation rollout ("100% to single variation"). Adds anti-pattern warning against [0,0,100].

• New section: "Choosing Between Variation and Percentage Rollout" — Explains performance and clarity benefits of variation rollout for 100% cases. Includes detection logic for agents: use variation when user says "enable the flag" or "roll out to everyone"; use percentage only when explicitly splitting traffic.

• Updated "Important Context" — Adds reminders to check flag state and choose correct rollout type, with cross-reference to detailed guidance.

Impact

Prevents two common mistakes:

1. Configuring targeting rules but forgetting to turn the flag ON
2. Using inefficient percentage rollouts for 100% scenarios

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[nieblara]

Original prompt to Copilot:
Please update the feature flag targeting skill with the following bits:

Add a new section after "Core Concept: Evaluation Order" about post-creation workflow:
Code

Working with Newly Created Flags

Important: When a flag is first created, targeting is OFF by default. This means:

• The flag will serve the offVariation to everyone, regardless of any configured rules or targets
• You must explicitly turn targeting ON using toggle-flag before the flag will evaluate any targeting logic

Typical post-creation workflow:

1. Verify the flag exists and check its initial state with get-flag
2. Configure the default rule (fallthrough) if needed with update-rollout
3. Turn targeting ON with toggle-flag to activate the flag
4. Optionally add rules or individual targets to refine targeting

If a user mentions they just created a flag and want to configure it, always check the current state first and remind them that targeting needs to be explicitly enabled.
Update the "Common scenarios" table in Step 2 to clarify rollout types:
Code

User wants	Tool	Notes
"Turn it on"	toggle-flag with on: true	Simplest change
"Turn it off"	toggle-flag with on: false	Serves offVariation to everyone
"Roll out to X%"	update-rollout with rolloutType: "percentage"	Use only when splitting traffic between variations. Weights must sum to 100
"Serve variation X to everyone"	update-rollout with rolloutType: "variation"	Most efficient for 100% rollouts. Do NOT use percentage with [0,0,100]
"Enable for beta users"	update-targeting-rules — add a rule with clause	Rules are ANDed within, ORed between
"Add specific users"	update-individual-targets	Highest priority, overrides all rules
"Copy from staging"	copy-flag-config	Promote tested config to production
Add a new section in "Important Context" about choosing the right rollout type:
Code

Choosing Between Variation and Percentage Rollout

Critical decision: When updating the default rule (fallthrough), choose the most efficient approach:

• Use rolloutType: "variation" when you want to serve a single variation to 100% of users

  • More performant
  • Clearer intent in the flag configuration
  • Example: {"rolloutType": "variation", "variationIndex": 2}

• Use rolloutType: "percentage" ONLY when you need to split traffic between multiple variations

  • For canary releases (e.g., 5% new, 95% old)
  • For A/B tests (e.g., 50/50 split)
  • For gradual rollouts (e.g., 25% new, 75% old)
  • Example: {"rolloutType": "percentage", "weights": [25, 75]}

Anti-pattern to avoid: Do NOT use percentage rollout with weights like [0, 0, 0, 100] to serve a single variation. This is inefficient and unclear. Always use rolloutType: "variation" instead.

Detection logic: If the user asks to "enable the flag" or "roll out to everyone" or "serve variation X to all users," this is a 100% rollout and should use rolloutType: "variation". Only use percentage rollout when the user explicitly mentions splitting traffic or percentages less than 100%.
Update the "Important Context" section to reinforce this:
Code

Important Context

• Newly created flags start with targeting OFF. Always use get-flag to check the current state, and use toggle-flag to turn targeting on when needed.
• Choose the right rollout type. Use rolloutType: "variation" for 100% rollouts, not percentage with [0,0,0,100]. See "Choosing Between Variation and Percentage Rollout" above.
• 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.Please update the feature flag targeting skill with the following bits:

Add a new section after "Core Concept: Evaluation Order" about post-creation workflow:
Code

Working with Newly Created Flags

Important: When a flag is first created, targeting is OFF by default. This means:

• The flag will serve the offVariation to everyone, regardless of any configured rules or targets
• You must explicitly turn targeting ON using toggle-flag before the flag will evaluate any targeting logic

Typical post-creation workflow:

1. Verify the flag exists and check its initial state with get-flag
2. Configure the default rule (fallthrough) if needed with update-rollout
3. Turn targeting ON with toggle-flag to activate the flag
4. Optionally add rules or individual targets to refine targeting

If a user mentions they just created a flag and want to configure it, always check the current state first and remind them that targeting needs to be explicitly enabled.
Update the "Common scenarios" table in Step 2 to clarify rollout types:
Code

User wants	Tool	Notes
"Turn it on"	toggle-flag with on: true	Simplest change
"Turn it off"	toggle-flag with on: false	Serves offVariation to everyone
"Roll out to X%"	update-rollout with rolloutType: "percentage"	Use only when splitting traffic between variations. Weights must sum to 100
"Serve variation X to everyone"	update-rollout with rolloutType: "variation"	Most efficient for 100% rollouts. Do NOT use percentage with [0,0,100]
"Enable for beta users"	update-targeting-rules — add a rule with clause	Rules are ANDed within, ORed between
"Add specific users"	update-individual-targets	Highest priority, overrides all rules
"Copy from staging"	copy-flag-config	Promote tested config to production
Add a new section in "Important Context" about choosing the right rollout type:
Code

Choosing Between Variation and Percentage Rollout

Critical decision: When updating the default rule (fallthrough), choose the most efficient approach:

• Use rolloutType: "variation" when you want to serve a single variation to 100% of users

  • More performant
  • Clearer intent in the flag configuration
  • Example: {"rolloutType": "variation", "variationIndex": 2}

• Use rolloutType: "percentage" ONLY when you need to split traffic between multiple variations

  • For canary releases (e.g., 5% new, 95% old)
  • For A/B tests (e.g., 50/50 split)
  • For gradual rollouts (e.g., 25% new, 75% old)
  • Example: {"rolloutType": "percentage", "weights": [25, 75]}

Anti-pattern to avoid: Do NOT use percentage rollout with weights like [0, 0, 0, 100] to serve a single variation. This is inefficient and unclear. Always use rolloutType: "variation" instead.

Detection logic: If the user asks to "enable the flag" or "roll out to everyone" or "serve variation X to all users," this is a 100% rollout and should use rolloutType: "variation". Only use percentage rollout when the user explicitly mentions splitting traffic or percentages less than 100%.
Update the "Important Context" section to reinforce this:
Code

Important Context

• Newly created flags start with targeting OFF. Always use get-flag to check the current state, and use toggle-flag to turn targeting on when needed.
• Choose the right rollout type. Use rolloutType: "variation" for 100% rollouts, not percentage with [0,0,0,100]. See "Choosing Between Variation and Percentage Rollout" above.
• 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.