Feature Flags
Debug or extend React’s internal feature-flag matrix and gate failing or channel-specific tests in the React monorepo.
Overview
Feature-flags is an agent skill for the Ship phase that explains React’s shared flag files, @gate test pragmas, and how to add or debug channel-specific feature-flag tests.
Install
npx skills add https://github.com/facebook/react --skill feature-flagsWhat is this skill?
- Documents flag sources: ReactFeatureFlags.js plus www, native-fb, and test-renderer forks with __VARIANT__ and __EXPERIM
- Explains @gate pragma for tests skipped when a flag is off vs gate() for dual behavior assertions
- Covers adding a new flag: default in ReactFeatureFlags.js then each fork file
- Targets channel-specific failures (canary, www, React Native) rather than app-level feature toggles
- Maps debugging workflow when feature flag tests fail or @gate usage is unclear
- 4 documented flag file roles (default, www, native-fb, test-renderer)
- 3-step checklist for adding a new flag (default + each fork)
Adoption & trust: 923 installs on skills.sh; 246k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
React CI fails or skips tests around feature flags and you do not know which fork file or gating style (@gate vs gate()) applies to your change.
Who is it for?
Open-source contributors patching react packages/shared flags or debugging gated tests in facebook/react.
Skip if: Application feature toggles, remote config, or gradual rollouts in a SaaS product codebase unrelated to React core.
When should I use this skill?
Feature flag tests fail, flags need updating, understanding @gate pragmas, debugging channel-specific test failures, or adding new flags to React.
What do I get? / Deliverables
You align new flags across ReactFeatureFlags.js and fork variants and fix tests with the correct gating pattern so channel builds behave as intended.
- Correct flag entries across shared and fork files
- Tests gated with @gate or gate() matching flag semantics
Recommended Skills
Journey fit
Shelf is ship because the skill centers on test gating, fork-specific flag files, and fixing flag-related test failures before merge. Testing subphase matches @gate pragmas, inline gate() assertions, and adding flags across www, native, and test-renderer forks.
How it compares
Monorepo maintainer reference for React internal flags—not a general-purpose feature-flag SaaS integration skill.
Common Questions / FAQ
Who is feature-flags for?
Developers working inside the React repository or a matching fork who need to change shared flags or understand gated test behavior.
When should I use feature-flags?
When feature flag tests fail, you add a flag to React, you debug www vs native channel differences, or you need @gate vs gate() guidance during ship/testing work.
Is feature-flags safe to install?
It describes upstream React internals only; review the Security Audits panel on this Prism page before installing skills from the registry.
SKILL.md
READMESKILL.md - Feature Flags
# React Feature Flags ## Flag Files | File | Purpose | |------|---------| | `packages/shared/ReactFeatureFlags.js` | Default flags (canary), `__EXPERIMENTAL__` overrides | | `packages/shared/forks/ReactFeatureFlags.www.js` | www channel, `__VARIANT__` overrides | | `packages/shared/forks/ReactFeatureFlags.native-fb.js` | React Native, `__VARIANT__` overrides | | `packages/shared/forks/ReactFeatureFlags.test-renderer.js` | Test renderer | ## Gating Tests ### `@gate` pragma (test-level) Use when the feature is completely unavailable without the flag: ```javascript // @gate enableViewTransition it('supports view transitions', () => { // This test only runs when enableViewTransition is true // and is SKIPPED (not failed) when false }); ``` ### `gate()` inline (assertion-level) Use when the feature exists but behavior differs based on flag: ```javascript it('renders component', async () => { await act(() => root.render(<App />)); if (gate(flags => flags.enableNewBehavior)) { expect(container.textContent).toBe('new output'); } else { expect(container.textContent).toBe('legacy output'); } }); ``` ## Adding a New Flag 1. Add to `ReactFeatureFlags.js` with default value 2. Add to each fork file (`*.www.js`, `*.native-fb.js`, etc.) 3. If it should vary in www/RN, set to `__VARIANT__` in the fork file 4. Gate tests with `@gate flagName` or inline `gate()` ## Checking Flag States Use `/flags` to view states across channels. See the `flags` skill for full command options. ## `__VARIANT__` Flags (GKs) Flags set to `__VARIANT__` simulate gatekeepers - tested twice (true and false): ```bash /test www <pattern> # __VARIANT__ = true /test www variant false <pattern> # __VARIANT__ = false ``` ## Debugging Channel-Specific Failures 1. Run `/flags --diff <channel1> <channel2>` to compare values 2. Check `@gate` conditions - test may be gated to specific channels 3. Run `/test <channel> <pattern>` to isolate the failure 4. Verify flag exists in all fork files if newly added ## Common Mistakes - **Forgetting both variants** - Always test `www` AND `www variant false` for `__VARIANT__` flags - **Using @gate for behavior differences** - Use inline `gate()` if both paths should run - **Missing fork files** - New flags must be added to ALL fork files, not just the main one - **Wrong gate syntax** - It's `gate(flags => flags.name)`, not `gate('name')`