Claude Skill

api-flags-posthog-flags

PostHog feature flags, rollouts, A/B testing. Use when implementing gradual rollouts, A/B tests, kill switches, remote configuration, beta features, or user targeting with PostHog.

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_api-flags-posthog-flags_skills_api-flags-posthog-flags-707467a.zip · 14 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/api-flags-posthog-flags/skills/api-flags-posthog-flags
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git git clone https://github.com/agents-inc/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Feature Flags with PostHog

Quick Guide: Use PostHog feature flags for gradual rollouts, A/B testing, and remote configuration. Client-side: useFeatureFlagEnabled hook. Server-side: posthog-node with local evaluation. Always pair useFeatureFlagPayload with useFeatureFlagEnabled for experiments. Handle the undefined loading state on every flag check.


<critical_requirements>

CRITICAL: Before Using This Skill

(You MUST always pair useFeatureFlagPayload with useFeatureFlagEnabled or useFeatureFlagVariantKey for experiments - payload hooks don't send exposure events)

(You MUST use the feature flags secure API key (phs_*) for server-side local evaluation - personal API keys are deprecated for this use)

(You MUST handle the undefined state when flags are loading - never assume a flag is immediately available)

(You MUST include flag owner and expiry date in flag metadata - flags without owners become orphaned debt)

(You MUST wrap flag usage in a single function when used in multiple places - prevents orphaned flag code on cleanup)

</critical_requirements>


Auto-detection: PostHog feature flags, useFeatureFlagEnabled, useFeatureFlagPayload, useFeatureFlagVariantKey, PostHogFeature, isFeatureEnabled, getFeatureFlag, gradual rollout, A/B test, experiment, multivariate flag

When to use:

  • Gradual rollouts (deploy to 10% users, then 50%, then 100%)
  • A/B testing with experiments (measure impact of changes)
  • Kill switches (instantly disable features without deploy)
  • Remote configuration (change behavior without code changes)
  • Beta features opt-in (let users try new features)
  • User targeting (show features to specific cohorts)

When NOT to use:

  • Simple on/off switches that never change (use environment variables)
  • Configuration that must be compile-time (use build flags)
  • Secrets or sensitive data (use secret management)
  • Features that should always be on (just ship the code)

Key patterns covered:

  • Client-side flag evaluation with React hooks
  • Server-side local evaluation for performance
  • Boolean vs multivariate flags
  • Gradual rollouts with percentage targeting
  • A/B testing and experiments
  • Payloads for remote configuration
  • Local development overrides
  • Flag cleanup and lifecycle management

Detailed Resources:




<red_flags>

RED FLAGS

High Priority Issues:

  • Using useFeatureFlagPayload alone for experiments (no exposure tracking)
  • Exposing Feature Flags Secure API key (phs_*) on client (security violation)
  • No loading state handling (causes UI flash)
  • Flags without owners or expiry dates (becomes permanent debt)

Medium Priority Issues:

  • Magic string flag keys instead of constants (typos, hard to grep)
  • Complex targeting rules on high-traffic flags (performance hit)
  • Local evaluation in serverless/edge without external cache (cold start issues)
  • Not using PostHog toolbar for local testing (harder debugging)

Common Mistakes:

  • Checking flag in multiple places instead of wrapper function
  • Not bootstrapping flags for SSR (content flash on hydration)
  • Running experiments without defined primary metric
  • Peeking at experiment results before completion
  • Rolling out to 100% without cleanup plan

Gotchas & Edge Cases:

  • PostHog uses deterministic hashing - same user always gets same variant
  • Decreasing rollout percentage can remove users who were previously included
  • Local evaluation requires Feature Flags Secure API Key (phs_*) - personal API keys are deprecated
  • Flags load asynchronously - first render always has undefined
  • GeoIP targeting uses server IP by default in posthog-node v3+
  • Experiments need minimum 50 exposures per variant for results
  • Stale flag = 100% rollout + not evaluated in 30 days
  • onFeatureFlags callback receives three parameters: flags, flagVariants, { errorsLoading } (third parameter)
  • External cache providers (Redis, KV) are experimental - Node.js/Python SDKs only

</red_flags>


<critical_reminders>

CRITICAL REMINDERS

(You MUST always pair useFeatureFlagPayload with useFeatureFlagEnabled or useFeatureFlagVariantKey for experiments - payload hooks don't send exposure events)

(You MUST use the feature flags secure API key (phs_*) for server-side local evaluation - personal API keys are deprecated for this use)

(You MUST handle the undefined state when flags are loading - never assume a flag is immediately available)

(You MUST include flag owner and expiry date in flag metadata - flags without owners become orphaned debt)

(You MUST wrap flag usage in a single function when used in multiple places - prevents orphaned flag code on cleanup)

Failure to follow these rules will cause incorrect experiment results, security vulnerabilities, UI flashing, and technical debt.

</critical_reminders>


Sources

Files (skills)
  • examples
    • core.md 13.8 KB
      Loading…
    • development.md 3.3 KB
      Loading…
    • server-side.md 7.2 KB
      Loading…
  • reference.md 4 KB
    Loading…
  • SKILL.md 11.1 KB
    ---
    name: api-flags-posthog-flags
    description: PostHog feature flags, rollouts, A/B testing. Use when implementing gradual rollouts, A/B tests, kill switches, remote configuration, beta features, or user targeting with PostHog.
    ---
    
    # Feature Flags with PostHog
    
    > **Quick Guide:** Use PostHog feature flags for gradual rollouts, A/B testing, and remote configuration. Client-side: `useFeatureFlagEnabled` hook. Server-side: `posthog-node` with local evaluation. Always pair `useFeatureFlagPayload` with `useFeatureFlagEnabled` for experiments. Handle the `undefined` loading state on every flag check.
    
    ---
    
    <critical_requirements>
    
    ## CRITICAL: Before Using This Skill
    
    **(You MUST always pair `useFeatureFlagPayload` with `useFeatureFlagEnabled` or `useFeatureFlagVariantKey` for experiments - payload hooks don't send exposure events)**
    
    **(You MUST use the feature flags secure API key (phs\_\*) for server-side local evaluation - personal API keys are deprecated for this use)**
    
    **(You MUST handle the `undefined` state when flags are loading - never assume a flag is immediately available)**
    
    **(You MUST include flag owner and expiry date in flag metadata - flags without owners become orphaned debt)**
    
    **(You MUST wrap flag usage in a single function when used in multiple places - prevents orphaned flag code on cleanup)**
    
    </critical_requirements>
    
    ---
    
    **Auto-detection:** PostHog feature flags, useFeatureFlagEnabled, useFeatureFlagPayload, useFeatureFlagVariantKey, PostHogFeature, isFeatureEnabled, getFeatureFlag, gradual rollout, A/B test, experiment, multivariate flag
    
    **When to use:**
    
    - Gradual rollouts (deploy to 10% users, then 50%, then 100%)
    - A/B testing with experiments (measure impact of changes)
    - Kill switches (instantly disable features without deploy)
    - Remote configuration (change behavior without code changes)
    - Beta features opt-in (let users try new features)
    - User targeting (show features to specific cohorts)
    
    **When NOT to use:**
    
    - Simple on/off switches that never change (use environment variables)
    - Configuration that must be compile-time (use build flags)
    - Secrets or sensitive data (use secret management)
    - Features that should always be on (just ship the code)
    
    **Key patterns covered:**
    
    - Client-side flag evaluation with React hooks
    - Server-side local evaluation for performance
    - Boolean vs multivariate flags
    - Gradual rollouts with percentage targeting
    - A/B testing and experiments
    - Payloads for remote configuration
    - Local development overrides
    - Flag cleanup and lifecycle management
    
    ---
    
    **Detailed Resources:**
    
    - [examples/core.md](examples/core.md) - Boolean flags, multivariate flags, PostHogFeature component, payloads, experiments, rollouts, lifecycle management
    - [examples/server-side.md](examples/server-side.md) - Server-side evaluation, local evaluation setup, distributed environments
    - [examples/development.md](examples/development.md) - Local overrides, bootstrapping, onFeatureFlags callback
    - [reference.md](reference.md) - Decision frameworks and anti-patterns
    
    ---
    
    <philosophy>
    
    ## Philosophy
    
    Feature flags decouple deployment from release. You can ship code to production but control who sees it and when. This enables:
    
    1. **Safe releases** - Roll out to 1% first, monitor, then expand
    2. **Fast rollback** - Toggle off instantly without deploying
    3. **Data-driven decisions** - A/B test to measure impact
    4. **Progressive delivery** - Beta users first, then everyone
    
    **Core principles:**
    
    - Flags are temporary - plan for cleanup from day one
    - Flags have owners - someone is responsible for each flag
    - Simple flags are better - percentage rollouts over complex conditions
    - Handle undefined - flags load asynchronously
    
    **When to use feature flags:**
    
    - Risky features that need gradual rollout
    - Features requiring A/B testing for validation
    - Features that may need instant rollback
    - Beta programs with user opt-in
    
    **When NOT to use feature flags:**
    
    - Every feature (creates maintenance burden)
    - Permanent configuration (use config files)
    - Features that are ready for 100% release
    
    </philosophy>
    
    ---
    
    <patterns>
    
    ## Core Patterns
    
    ### Pattern 1: Client-Side Boolean Flags
    
    Use `useFeatureFlagEnabled` for simple on/off features. Always handle the `undefined` loading state -- treating it as `false` causes a flash of wrong UI.
    
    ```typescript
    const isNewCheckout = useFeatureFlagEnabled(FLAG_NEW_CHECKOUT);
    
    if (isNewCheckout === undefined) return <Skeleton />;   // Loading
    if (isNewCheckout) return <NewCheckout />;               // Enabled
    return <LegacyCheckout />;                               // Disabled
    ```
    
    Store flag keys as named constants in `lib/feature-flags.ts` to prevent typos and enable cleanup-by-grep.
    
    See [examples/core.md](examples/core.md#pattern-1-client-side-boolean-flags) for full good/bad examples.
    
    ---
    
    ### Pattern 2: Multivariate Flags and Variants
    
    Use `useFeatureFlagVariantKey` for A/B tests with multiple variants. Define variant constants alongside the flag key. Switch on variants with a default fallback to `control`.
    
    ```typescript
    const variant = useFeatureFlagVariantKey(FLAG_PRICING_PAGE);
    if (variant === undefined) return <Skeleton />;
    
    switch (variant) {
      case VARIANT_SIMPLE: return <SimplePricing />;
      case VARIANT_DETAILED: return <DetailedPricing />;
      default: return <ControlPricing />;
    }
    ```
    
    See [examples/core.md](examples/core.md#pattern-2-multivariate-flags-and-variants) for full example.
    
    ---
    
    ### Pattern 3: PostHogFeature Component
    
    The `PostHogFeature` component provides automatic exposure tracking and built-in fallback handling with less boilerplate. Use `match={true}` for boolean flags or `match={VARIANT_KEY}` for specific variants.
    
    ```typescript
    <PostHogFeature flag={FLAG_BETA} match={true} fallback={<Legacy />}>
      <NewFeature />
    </PostHogFeature>
    ```
    
    See [examples/core.md](examples/core.md#pattern-3-posthogfeature-component) for boolean and variant examples.
    
    ---
    
    ### Pattern 4: Payloads for Remote Configuration
    
    Use `useFeatureFlagPayload` for dynamic JSON configuration. **Always pair with `useFeatureFlagEnabled`** -- the payload hook alone does NOT send exposure events, breaking experiment tracking.
    
    ```typescript
    const isEnabled = useFeatureFlagEnabled(FLAG_BANNER); // Sends exposure event
    const payload = useFeatureFlagPayload(FLAG_BANNER); // Gets config
    const config = payload ?? DEFAULT_BANNER_CONFIG;
    ```
    
    See [examples/core.md](examples/core.md#pattern-4-feature-flag-payloads-for-remote-configuration) for full good/bad examples.
    
    ---
    
    ### Pattern 5: Server-Side Flag Evaluation
    
    Use `posthog-node` with the Feature Flags Secure API Key (`phs_*`) for local evaluation. This reduces latency from ~500ms (network call) to ~10-50ms (local). The `personalApiKey` config option takes the `phs_*` key despite its legacy name.
    
    ```typescript
    export const posthog = new PostHog(process.env.POSTHOG_API_KEY!, {
      host: process.env.POSTHOG_HOST || "https://us.i.posthog.com",
      personalApiKey: process.env.POSTHOG_FEATURE_FLAGS_KEY, // phs_* key
      featureFlagsPollingInterval: POSTHOG_POLL_INTERVAL_MS, // default 30s
    });
    ```
    
    See [examples/server-side.md](examples/server-side.md) for API handler usage, local-only evaluation, and distributed/serverless environments.
    
    ---
    
    ### Pattern 6: Flag Lifecycle and Cleanup
    
    Every flag needs an owner, a creation date, and an expected removal date. Wrap flag checks in a single helper function so cleanup is a one-file change.
    
    ```typescript
    /**
     * Owner: @john-doe | Created: 2025-01-15 | Remove by: 2025-02-15
     */
    export const FLAG_NEW_CHECKOUT = "new-checkout-flow";
    
    export function isNewCheckoutEnabled(flag: boolean | undefined): boolean {
      return flag === true; // When removing: change to `return true;`
    }
    ```
    
    See [examples/core.md](examples/core.md#pattern-7-flag-cleanup-and-lifecycle-management) for full documentation patterns and stale flag detection.
    
    </patterns>
    
    ---
    
    <red_flags>
    
    ## RED FLAGS
    
    **High Priority Issues:**
    
    - Using `useFeatureFlagPayload` alone for experiments (no exposure tracking)
    - Exposing Feature Flags Secure API key (`phs_*`) on client (security violation)
    - No loading state handling (causes UI flash)
    - Flags without owners or expiry dates (becomes permanent debt)
    
    **Medium Priority Issues:**
    
    - Magic string flag keys instead of constants (typos, hard to grep)
    - Complex targeting rules on high-traffic flags (performance hit)
    - Local evaluation in serverless/edge without external cache (cold start issues)
    - Not using PostHog toolbar for local testing (harder debugging)
    
    **Common Mistakes:**
    
    - Checking flag in multiple places instead of wrapper function
    - Not bootstrapping flags for SSR (content flash on hydration)
    - Running experiments without defined primary metric
    - Peeking at experiment results before completion
    - Rolling out to 100% without cleanup plan
    
    **Gotchas & Edge Cases:**
    
    - PostHog uses deterministic hashing - same user always gets same variant
    - Decreasing rollout percentage can remove users who were previously included
    - Local evaluation requires Feature Flags Secure API Key (`phs_*`) - personal API keys are deprecated
    - Flags load asynchronously - first render always has undefined
    - GeoIP targeting uses server IP by default in posthog-node v3+
    - Experiments need minimum 50 exposures per variant for results
    - Stale flag = 100% rollout + not evaluated in 30 days
    - `onFeatureFlags` callback receives three parameters: `flags`, `flagVariants`, `{ errorsLoading }` (third parameter)
    - External cache providers (Redis, KV) are experimental - Node.js/Python SDKs only
    
    </red_flags>
    
    ---
    
    <critical_reminders>
    
    ## CRITICAL REMINDERS
    
    **(You MUST always pair `useFeatureFlagPayload` with `useFeatureFlagEnabled` or `useFeatureFlagVariantKey` for experiments - payload hooks don't send exposure events)**
    
    **(You MUST use the feature flags secure API key (phs\_\*) for server-side local evaluation - personal API keys are deprecated for this use)**
    
    **(You MUST handle the `undefined` state when flags are loading - never assume a flag is immediately available)**
    
    **(You MUST include flag owner and expiry date in flag metadata - flags without owners become orphaned debt)**
    
    **(You MUST wrap flag usage in a single function when used in multiple places - prevents orphaned flag code on cleanup)**
    
    **Failure to follow these rules will cause incorrect experiment results, security vulnerabilities, UI flashing, and technical debt.**
    
    </critical_reminders>
    
    ---
    
    ## Sources
    
    - [PostHog React Integration](https://posthog.com/docs/libraries/react)
    - [PostHog Feature Flags](https://posthog.com/docs/feature-flags)
    - [PostHog Feature Flag Best Practices](https://posthog.com/docs/feature-flags/best-practices)
    - [PostHog Server-Side Local Evaluation](https://posthog.com/docs/feature-flags/local-evaluation)
    - [PostHog Creating Feature Flags](https://posthog.com/docs/feature-flags/creating-feature-flags)
    - [PostHog How to Do a Phased Rollout](https://posthog.com/tutorials/phased-rollout)
    - [PostHog Feature Flag Testing](https://posthog.com/docs/feature-flags/testing)
    - [PostHog Experiments](https://posthog.com/ab-testing)
    - [PostHog Feature Flag Overrides](https://posthog.com/docs/toolbar/override-feature-flags)
    - [Don't Make These Feature Flag Mistakes](https://posthog.com/newsletter/feature-flag-mistakes)
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.