Contract
- Input: feature request, rollout constraints, targeting context, and operational requirements.
- Output: FeatureFlagArtifact in JSON and Markdown.
- Scope: stay within the skill's declared boundaries; do not broaden without explicit direction.
- Rule: documented standards override defaults; explicit project rules take precedence.
- Rule: if blocked by missing context or dependencies, surface the blocker before proceeding.
Provenance
| Question |
Answer |
| What is the source of truth? |
The user's request, originating spec/issue, and the skill's declared outputs |
| What is in scope? |
Work covered by the skill's acceptance criteria and completion rules |
| What is explicitly out of scope? |
Files, behaviors, and decisions outside the skill's declared boundary |
| Who or what consumes this artifact afterward? |
The next skill in the workflow or the user |
| What evidence proves it is done? |
Completion criteria met, artifact saved, validation passed |
| What risk remains? |
Subjective judgment calls, missing context, or external dependency failures |
Artifact
Emit FeatureFlagArtifact as both:
- JSON:
.agents/skills/platform/artifacts/feature-flag/{identifier}.json
- Markdown view: same filename with
.md extension
Feature Flag
Why
Short-lived flags prevent tech debt because they force the team to retire the switch at the same time the feature ships. A flag with a 4-week cleanup deadline is a contract, not a suggestion. When flags outlive their purpose they become zombie switches: hidden branching logic that bloats code paths, complicates testing, and obscures intent. By tying every flag to a cleanup deadline and an owner, the team maintains a tight feedback loop between rollout and retirement, keeping the codebase navigable and the deployment pipeline honest.
Use this skill when a project needs to introduce a new feature flag, plan a safe rollout, or retire an existing flag. It keeps flags short-lived, well-targeted, and observable so the codebase does not accumulate dead switches.
Provenance
| Dimension |
Bar |
| Correctness |
flag purpose is unambiguous; targeting rules are testable |
| Completeness |
cleanup deadline, owner, metrics, and dependencies are recorded |
| Consistency |
naming follows project conventions; type taxonomy matches usage |
| Timeliness |
flags are retired within the declared cleanup deadline |
| Safety |
kill switches are reversible without deploy; rollout limits are enforced |
Artifact
Emit a FeatureFlagArtifact as JSON and a human-readable Markdown summary.
Observability: the artifact must include traceId, owner, and cleanupOwner fields so that flag state changes are auditable. Each flag state transition must emit a record to the observability pipeline with timestamp, actor, and previous state.
FeatureFlagArtifact Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "FeatureFlagArtifact",
"type": "object",
"required": ["name", "purpose", "type", "targetingRules", "rolloutPercentage", "cleanupDeadline", "status", "dependencies"],
"properties": {
"name": {
"type": "string",
"description": "Unique flag identifier"
},
"purpose": {
"type": "string",
"description": "Why this flag exists"
},
"type": {
"type": "string",
"enum": ["release", "experiment", "kill-switch"],
"description": "Flag purpose category"
},
"targetingRules": {
"type": "array",
"items": {"type": "string"},
"description": "Explicit targeting conditions"
},
"rolloutPercentage": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Percentage of users exposed when active"
},
"cleanupDeadline": {
"type": "string",
"format": "date",
"description": "Maximum date before the flag must be retired"
},
"status": {
"type": "string",
"enum": ["draft", "active", "completed", "cleaned"],
"description": "Current lifecycle state"
},
"dependencies": {
"type": "array",
"items": {"type": "string"},
"description": "Flags or services this flag depends on"
}
}
}
Markdown Summary
# Feature Flag: {name}
**Purpose:** {purpose}
**Type:** {type}
**Status:** {status}
**Rollout:** {rolloutPercentage}%
**Cleanup Deadline:** {cleanupDeadline}
## Targeting Rules
{targetingRules}
## Dependencies
{dependencies}
## Rollout Plan
1. Start at {rolloutPercentage}% with explicit targeting rules.
2. Observe metrics and error rates for 24-48 hours.
3. Increase in stages to 100% or retire at cleanup deadline.
## Cleanup Plan
- Remove flag code on or before {cleanupDeadline}.
- Delete flag configuration after full rollout is confirmed.
- Verify no dead code remains.
Process
- Identify flag purpose: classify as release flag, experiment, or operational kill switch.
- Define targeting rules and rollout plan: specify who gets the flag, at what percentage, and what gates must pass before expansion.
- Set cleanup deadline: max 4 weeks from activation; record owner and success criteria.
- Document flag in registry: emit FeatureFlagArtifact with JSON schema and Markdown summary.
- Verify flag state in gate-post-merge: confirm flag default is off, targeting rules are enforced, and observability is wired.
Completion
- the skill's completion criteria are explicitly checked
- the artifact is saved and validated
- any blockers or skipped validations are documented
- the next consumer is identified or the work is handed off
@include .agents/skills/platform/contract-base.xml
1---2name: "feature-flag"3category: "platform"4description: "Design and manage feature flags with short-lived flags, gradual rollouts, kill switches, A/B testing, and cleanup discipline."5capabilities:6 - apply feature flag methods within explicit platform boundaries7 - analyze design and manage feature flags with short-lived flags, gradual rollouts, kill switches, a/b testing, and cleanup discipline with assumptions, constraints, and failure modes8 - produce and validate a platform artifact with evidence, decisions, and next steps9license: "MIT"10artifactType: "feature-flag"11modelTier: "router"12tags: ["platform"]13compatibility: []14outputs: "FeatureFlagArtifact in JSON and Markdown."15stopCondition: "Feature flag design and management complete; FeatureFlagArtifact emitted; completion criteria checked."16risk: "low"17trustTier: "1"18maxIterations: "4"19fixturesPath: ".agents/skills/platform/fixtures/behavioral/feature-flag.json"20promptVersion: "2.0"21evaluators: ["behavioral", "regression"]22diataxis: "how-to"23approvalRequired: "false"24approvalFor: []25metadata:26 source: https://skillmd.com/skills/quantumquirkxyz/feature-flag27---2829## Contract3031- Input: feature request, rollout constraints, targeting context, and operational requirements.32- Output: FeatureFlagArtifact in JSON and Markdown.33- Scope: stay within the skill's declared boundaries; do not broaden without explicit direction.34- Rule: documented standards override defaults; explicit project rules take precedence.35- Rule: if blocked by missing context or dependencies, surface the blocker before proceeding.3637## Provenance3839| Question | Answer |40|---|---|41| What is the source of truth? | The user's request, originating spec/issue, and the skill's declared outputs |42| What is in scope? | Work covered by the skill's acceptance criteria and completion rules |43| What is explicitly out of scope? | Files, behaviors, and decisions outside the skill's declared boundary |44| Who or what consumes this artifact afterward? | The next skill in the workflow or the user |45| What evidence proves it is done? | Completion criteria met, artifact saved, validation passed |46| What risk remains? | Subjective judgment calls, missing context, or external dependency failures474849## Artifact5051Emit `FeatureFlagArtifact` as both:52- JSON: `.agents/skills/platform/artifacts/feature-flag/{identifier}.json`53- Markdown view: same filename with `.md` extension545556# 57# 58# Feature Flag5960## Why6162Short-lived flags prevent tech debt because they force the team to retire the switch at the same time the feature ships. A flag with a 4-week cleanup deadline is a contract, not a suggestion. When flags outlive their purpose they become zombie switches: hidden branching logic that bloats code paths, complicates testing, and obscures intent. By tying every flag to a cleanup deadline and an owner, the team maintains a tight feedback loop between rollout and retirement, keeping the codebase navigable and the deployment pipeline honest.6364Use this skill when a project needs to introduce a new feature flag, plan a safe rollout, or retire an existing flag. It keeps flags short-lived, well-targeted, and observable so the codebase does not accumulate dead switches.656667## Provenance6869| Dimension | Bar |70|---|---|71| Correctness | flag purpose is unambiguous; targeting rules are testable |72| Completeness | cleanup deadline, owner, metrics, and dependencies are recorded |73| Consistency | naming follows project conventions; type taxonomy matches usage |74| Timeliness | flags are retired within the declared cleanup deadline |75| Safety | kill switches are reversible without deploy; rollout limits are enforced |7677## Artifact7879Emit a `FeatureFlagArtifact` as JSON and a human-readable Markdown summary.8081Observability: the artifact must include `traceId`, `owner`, and `cleanupOwner` fields so that flag state changes are auditable. Each flag state transition must emit a record to the observability pipeline with timestamp, actor, and previous state.8283### FeatureFlagArtifact Schema8485```json86{87 "$schema": "http://json-schema.org/draft-07/schema#",88 "title": "FeatureFlagArtifact",89 "type": "object",90 "required": ["name", "purpose", "type", "targetingRules", "rolloutPercentage", "cleanupDeadline", "status", "dependencies"],91 "properties": {92 "name": {93 "type": "string",94 "description": "Unique flag identifier"95 },96 "purpose": {97 "type": "string",98 "description": "Why this flag exists"99 },100 "type": {101 "type": "string",102 "enum": ["release", "experiment", "kill-switch"],103 "description": "Flag purpose category"104 },105 "targetingRules": {106 "type": "array",107 "items": {"type": "string"},108 "description": "Explicit targeting conditions"109 },110 "rolloutPercentage": {111 "type": "integer",112 "minimum": 0,113 "maximum": 100,114 "description": "Percentage of users exposed when active"115 },116 "cleanupDeadline": {117 "type": "string",118 "format": "date",119 "description": "Maximum date before the flag must be retired"120 },121 "status": {122 "type": "string",123 "enum": ["draft", "active", "completed", "cleaned"],124 "description": "Current lifecycle state"125 },126 "dependencies": {127 "type": "array",128 "items": {"type": "string"},129 "description": "Flags or services this flag depends on"130 }131 }132}133```134135### Markdown Summary136137```markdown138# Feature Flag: {name}139140**Purpose:** {purpose}141**Type:** {type}142**Status:** {status}143**Rollout:** {rolloutPercentage}%144**Cleanup Deadline:** {cleanupDeadline}145146## Targeting Rules147{targetingRules}148149## Dependencies150{dependencies}151152## Rollout Plan1531. Start at {rolloutPercentage}% with explicit targeting rules.1542. Observe metrics and error rates for 24-48 hours.1553. Increase in stages to 100% or retire at cleanup deadline.156157## Cleanup Plan158- Remove flag code on or before {cleanupDeadline}.159- Delete flag configuration after full rollout is confirmed.160- Verify no dead code remains.161```162163## Process1641651. Identify flag purpose: classify as release flag, experiment, or operational kill switch.1662. Define targeting rules and rollout plan: specify who gets the flag, at what percentage, and what gates must pass before expansion.1673. Set cleanup deadline: max 4 weeks from activation; record owner and success criteria.1684. Document flag in registry: emit FeatureFlagArtifact with JSON schema and Markdown summary.1695. Verify flag state in gate-post-merge: confirm flag default is off, targeting rules are enforced, and observability is wired.170171## Completion172173- the skill's completion criteria are explicitly checked174- the artifact is saved and validated175- any blockers or skipped validations are documented176- the next consumer is identified or the work is handed off177---178@include .agents/skills/platform/contract-base.xml