Most teams treat flags as throwaway if-statements. This skill treats them as a controlled lifecycle with measurable debt — and ships the tools to enforce it.

What's inside

3 stdlib Python tools — flag debt scanner, rollout planner, kill-switch auditor
4 reference docs — taxonomy, provider comparison, rollout strategies, lifecycle
/flag-cleanup slash command — runs the full quarterly cleanup workflow
Asset template — feature flag request form

Install

Claude Code

# Via Claude Code marketplace
/plugin install feature-flags-architect

# Or clone the repo
git clone https://github.com/alirezarezvani/claude-skills.git
cd claude-skills/engineering/feature-flags-architect

Other tools (Codex CLI, Cursor, Antigravity, OpenCode, Gemini CLI)

The skill ships with a context: fork SKILL.md, so it loads via the standard skill mechanism each tool supports. See cross-tool compatibility in the SKILL.md frontmatter.

Quick start

SKILL=engineering/feature-flags-architect/skills/feature-flags-architect

# Audit your repo for stale flags
python "$SKILL/scripts/flag_debt_scanner.py" --repo . --max-age-days 90

# Plan a phased rollout
python "$SKILL/scripts/rollout_planner.py" --population 100000 --target-percent 100 --duration-days 14 --strategy ring

# Verify every flag has a kill switch
python "$SKILL/scripts/kill_switch_audit.py" --repo . --flag-doc docs/feature-flags.md

When to use

Adding a new flag and need a rollout plan
Auditing a codebase for orphaned or stale flags
Choosing a flag provider (LaunchDarkly vs GrowthBook vs Statsig vs Unleash vs Flipt vs DIY)
Designing a kill-switch path for a risky launch
Cleaning up flag debt before a release freeze

Key principles

Flags are a lifecycle, not an if-statement: request → design → ship → ramp → cleanup → archive
4 flag types with different lifespans: Release / Experiment / Operational / Permission
Every flag has a documented kill switch — owner, type, trigger, dashboard
Rollout strategy by risk, not preference (ring for risky, linear for medium, log for low)
Quarterly cleanup is non-negotiable — debt compounds

Skill structure

feature-flags-architect/
├── README.md                              # this file
├── .claude-plugin/plugin.json             # 8-field plugin manifest
└── skills/feature-flags-architect/
    ├── SKILL.md                           # main skill spec
    ├── scripts/
    │   ├── flag_debt_scanner.py           # find stale flags
    │   ├── rollout_planner.py             # generate phased schedule
    │   └── kill_switch_audit.py           # verify documentation
    ├── references/
    │   ├── flag_taxonomy.md               # 4 types decision tree
    │   ├── provider_comparison.md         # LD/GB/Statsig/Unleash/Flipt/DIY
    │   ├── rollout_strategies.md          # ring/linear/log/cohort
    │   └── flag_lifecycle.md              # 6-phase lifecycle
    └── assets/
        └── flag_request_template.md       # PR template

Verifiable success

A team using this skill should achieve:

100% of new flags pass kill_switch_audit.py at merge time
flag_debt_scanner.py --max-age-days 90 returns ≤5 stale flags repo-wide
Every flag has a documented owner, type, kill switch, and dashboard
Mean time to retire a Release flag: <60 days from 100% rollout

License

MIT — see repo root LICENSE.