Skip to main content

​
Claude Code Skill

An optional skill that enables AI agents to manage your Superflag feature flags through natural language commands. Use it with Claude Code or any compatible AI coding assistant.

​
Overview

The Superflag skill allows AI agents to execute CLI commands on your behalf, making it easy to create, update, and manage feature flags through conversation instead of typing commands manually. The skill is available at .claude/skills/superflag in the superflag-cli repository.

​
Installation

If you’re using Claude Code in the superflag-mono directory, the skill is automatically available. For standalone usage:
  1. Copy the skill directory to your project: 
    cp -r /path/to/superflag-mono/.claude/skills/superflag .claude/skills/
  2. The skill will be available in your Claude Code session

​
How It Works

When you ask Claude to manage your flags, the skill:
  1. Executes CLI commands from the superflag-cli directory
  2. Uses bun run dev to run commands in development mode
  3. Maintains context throughout your session
All commands use the same Superflag CLI under the hood, so the behavior is identical to using the CLI directly.

​
Example Usage

Here’s how you can interact with the skill through natural language:

​
Create a Feature Flag

You: “Create a new feature flag called ‘dark-mode’ set to false” Claude: [executes] bun run dev flags upsert --key dark-mode --type bool --value false Result: ✓ Flag created

​
Toggle a Flag

You: “Toggle the beta-features flag” Claude: [executes] bun run dev flags toggle --key beta-features Result: ✓ Flag toggled

​
Check Flag Value

You: “What’s the current value of dark-mode?” Claude: [executes] bun run dev get dark-mode Result: false

​
Set Context

You: “Set the context to my-app production” Claude: [executes] bun run dev use my-app production Result: ✓ Context set to my-app/production

​
Available Operations

The skill can perform all CLI operations:
  • Set context - Configure app and environment for subsequent commands
  • Create/update flags - Add new flags or modify existing ones
  • Get flag values - Check current flag values
  • Toggle boolean flags - Flip true/false flags
  • Manage apps - Create apps and list environments
  • Manage API keys - Create and revoke SDK/client keys
  • Dump config - Get full configuration as JSON

​
Command Reference

Here are the commands the skill executes behind the scenes:
OperationCommandNotes
Set contextbun run dev use <app> <env>Required before using quick commands
Get flagbun run dev get <key>Uses saved context
Set flagbun run dev set <key> <value>Uses saved context
Create/update flagbun run dev flags upsert --key <k> --type <t> --value <v>Full syntax
Toggle flagbun run dev flags toggle --app <app> --env <env> --key <key>Boolean flags only
Dump configbun run dev configOutputs JSON
List appsbun run dev apps listShows all your apps
Create appbun run dev apps create <name>Creates app with dev/staging/prod
List keysbun run dev keys list --app <app> --env <env>Shows API keys
Create keybun run dev keys create --app <app> --env <env> --type <sdk|pub>Generates new key

​
Flag Types

When creating flags, you can use these types:
TypeExample ValueUse Case
booltrue, falseFeature toggles, enable/disable
string"dark", "v2"Theme names, API versions, modes
number100, 3.14Limits, timeouts, thresholds
json'{"theme":"dark","size":"large"}'Complex configuration objects

​
Flag Visibility

All flags are available to both client and server keys: 
# Client-side flag (visible in browser/mobile app)
bun run dev flags upsert --key dark-mode --type bool --value true

# Another flag
bun run dev flags upsert --key api-url --type string --value https://api.example.com
All flags are returned by both /api/v1/public-config (client keys) and /api/v1/config (server keys). Server keys additionally receive rules and overrides.

​
Context Management

The skill uses context saved to ~/.superflag/context.json. Set it once per session: 
# Set context
bun run dev use my-app production

# Now quick commands work
bun run dev get feature-name
bun run dev set feature-name true
Context persists between commands in the same session.

​
Authentication

The skill requires authentication. Make sure you’re logged in: 
bun run dev status
# Output: Auth: Logged in as you@example.com
If not logged in: 
bun run dev login
Your credentials are stored in ~/.superflag/credentials.json.

​
Exit Codes

The skill respects standard CLI exit codes:
CodeMeaning
0Success
1Error (invalid command, network issue, etc.)
2Not authenticated
3Resource not found

​
Troubleshooting

​
Skill Not Available

If Claude doesn’t recognize Superflag commands:
  • Verify the skill directory exists at .claude/skills/superflag/
  • Check that SKILL.md is present in the skill directory
  • Restart your Claude Code session

​
Authentication Errors

Error: Not authenticated
Solution: Log in with bun run dev login

​
Context Not Set

Error: No context set. Use 'superflag use <app> <env>' first
Solution: Set context with bun run dev use <app> <env>

​
Commands Not Found

Error: bun: command not found
Solution: Install Bun from https://bun.sh or use npm instead by modifying the skill commands

​
Next Steps

Commands Reference

Complete CLI command documentation

API Reference

Use the HTTP API directly