GO Feature Flag Skill | Agent Skills

GO Feature Flag

When to Use This Skill

| Use this skill when... | Use a sibling skill instead when... | |---|---| | You need GOFF-specific configuration — flags.goff.yaml, relay proxy, targeting rules | You only need the vendor-agnostic OpenFeature SDK API — use openfeature | | You are deploying or operating the self-hosted GOFF backend | You want to scaffold the full feature-flag stack including provider selection — use configure-feature-flags | | Another skill needs the canonical GOFF flag-file shape | You are evaluating which feature-flag provider to adopt — start with configure-feature-flags |

Open-source feature flag solution with file-based configuration and OpenFeature integration. Use when setting up self-hosted feature flags, configuring flag files, or deploying the relay proxy.

Activation triggers

User mentions "GO Feature Flag", "GOFF", or "gofeatureflag"
Project has @openfeature/go-feature-flag-provider dependency
Project has flags.goff.yaml or similar flag configuration
User asks about self-hosted feature flags
Docker/K8s configuration includes gofeatureflag/go-feature-flag image

Related skills:

openfeature - OpenFeature SDK usage patterns
container-development - Docker/K8s deployment

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     Application                              │
│                         │                                    │
│                   OpenFeature SDK                            │
│                         │                                    │
│              GO Feature Flag Provider                        │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                 GO Feature Flag Relay Proxy                  │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    Retriever                            ││
│  │  (File, S3, GitHub, HTTP, K8s ConfigMap, etc.)         ││
│  └─────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    Exporter                             ││
│  │  (Webhook, S3, Kafka, PubSub, etc.)                    ││
│  └─────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────┐│
│  │                   Notifier                              ││
│  │  (Slack, Discord, Teams, Webhook)                      ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   Flag Configuration                         │
│                    (flags.goff.yaml)                         │
└─────────────────────────────────────────────────────────────┘

Flag Configuration Format

Basic Structure

# flags.goff.yaml
flag-name:
  variations:       # All possible values
    variation1: value1
    variation2: value2
  defaultRule:      # Rule when no targeting matches
    variation: variation1
  targeting:        # Optional: targeting rules
    - name: rule-name
      query: 'expression'
      variation: variation2

Boolean Flags

# Simple on/off flag
new-feature:
  variations:
    enabled: true
    disabled: false
  defaultRule:
    variation: disabled

For String, Number, and Object/JSON flag examples, see REFERENCE.md.

Targeting Rules

Query Syntax

GO Feature Flag uses a CEL-like query syntax for targeting:

targeting:
  - name: beta-users
    query: 'groups co "beta"'  # contains
    variation: enabled

  - name: specific-user
    query: 'targetingKey eq "user-123"'  # equals
    variation: enabled

  - name: email-domain
    query: 'email ew "@company.com"'  # ends with
    variation: enabled

  - name: premium-tier
    query: 'plan in ["pro", "enterprise"]'  # in list
    variation: enabled

Operators

| Operator | Description | Example | |----------|-------------|---------| | eq | Equals | email eq "test@example.com" | | ne | Not equals | plan ne "free" | | co | Contains | groups co "admin" | | sw | Starts with | email sw "admin" | | ew | Ends with | email ew "@company.com" | | in | In list | country in ["US", "CA"] | | gt, ge, lt, le | Comparisons | age gt 18 | | and, or | Logical | plan eq "pro" and country eq "US" |

Priority

Rules are evaluated top-to-bottom. First matching rule wins:

targeting:
  # Highest priority: specific user override
  - name: test-user
    query: 'targetingKey eq "test-user-id"'
    variation: enabled

  # Second: admin group
  - name: admins
    query: 'groups co "admin"'
    variation: enabled

  # Third: beta users
  - name: beta
    query: 'groups co "beta"'
    variation: enabled

  # Fallback is defaultRule
defaultRule:
  variation: disabled

Rollout Strategies

Percentage Rollout

new-checkout:
  variations:
    enabled: true
    disabled: false
  defaultRule:
    percentage:
      enabled: 20   # 20% of users
      disabled: 80  # 80% of users

For Progressive Rollout, Scheduled Changes, and A/B Testing patterns, see REFERENCE.md.

Relay Proxy Configuration

The relay serves the API on port 1031 and health/metrics on 1032. Choose a retriever with RETRIEVER_KIND (file, s3, http, github, gitlab, googlecloud, azureblob, k8s) and tune refresh with POLLING_INTERVAL_MS.

For the Docker Compose service definition and the full retriever/polling/server environment variables, see references/relay-proxy.md — read it when standing up or reconfiguring the relay.

For Kubernetes deployment configuration, see REFERENCE.md.

Exporters

Export flag evaluation data for analytics. Supported kinds: webhook, s3, googlecloud, kafka, pubsub, log.

For detailed exporter environment variable configuration, see REFERENCE.md.

Notifiers

Send notifications on flag changes. Supported: Slack, Discord, Microsoft Teams, Webhook.

For webhook URL configuration, see REFERENCE.md.

CLI Tools

Validate flag files with goff lint --config flags.goff.yaml and test evaluation against a local relay via POST /v1/feature/<flag>/eval. Install commands, the docker run invocation, and the curl evaluation call are in references/cli-and-troubleshooting.md.

Best Practices

1. Flag Naming Convention

# Namespace by feature/team
checkout.new-payment-form
dashboard.beta-widgets
api.v2-endpoints

# Use consistent suffixes
*.enabled      # boolean toggles
*.config       # object/JSON config
*.percentage   # rollout percentage

2. Track Flag Lifecycle

# Add metadata comments (YAML supports comments)
new-feature:
  # Created: 2024-11-01
  # Owner: team-checkout
  # Jira: PROJ-123
  # Target removal: 2025-01-15
  variations:
    enabled: true
    disabled: false

3. Monitor and Clean Up

Export evaluation data to track usage
Set up alerts for flags at 100% (ready for removal)
Review flags quarterly for cleanup

For GitOps CI/CD workflow and environment-specific flag patterns, see REFERENCE.md.

Troubleshooting

For diagnostic commands covering flags not evaluating correctly, provider connection issues (timeout and PROVIDER_READY/PROVIDER_ERROR events), and configuration not updating, see references/cli-and-troubleshooting.md — read it when a flag misbehaves at runtime.

Documentation

Official Docs: https://gofeatureflag.org/docs
Flag Format: https://gofeatureflag.org/docs/configure_flag/flag_format
Relay Proxy: https://gofeatureflag.org/docs/relay-proxy
OpenFeature SDKs: https://gofeatureflag.org/docs/sdk

Related Commands

/configure:feature-flags - Set up complete feature flag infrastructure
/configure:dockerfile - Container configuration best practices

Agent Skills: GO Feature Flag

Install this agent skill to your local

Skill Files