Index of every page on this site: llms.txt
All skills
block avatar

/experimental-features

@77422a9
by Block Open Sourceblock/berd1.1k stars
137
Run it yourself

Use when adding, reviewing, configuring, graduating, or removing Berd experiments.

  • 1 file
  • 5.9 KB
  • Updated 3 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/block/berd/experimental-features

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈26 tokens for metadata: the name and description. ≈1.5k when used: this file.

Description uses 1.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈106 characters, or 1.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Experimental Features

Use experiments for opt-in, user-local in-progress Berd UI or workflow behavior. Do not use experiments for secrets, credentials, backend authority, packaged policy, or app state that should survive graduation as a normal preference.

When To Use Experiments

  • An individual user opts into unstable UI or workflow behavior.
  • Stable behavior can remain the default path.
  • Config is small, non-sensitive, typed, and user-editable.
  • The feature can be graduated or removed later.

When To Use distro.json

Use distro.json for packaged build policy and startup defaults, especially when the Tauri shell or sidecar needs bundled resources/config.

Good distro fits include providerAllowlist, kgoose, featureToggles.costTracking, bundled config.yaml, bin/, skills/, and agents/.

Do not use distro.json for normal app state, user preferences, dynamic runtime switches, ACP-backed data, or per-user experiments.

Registry Shape

Add experiments only in src/features/experiments/experimentDefinitions.ts.

Each definition needs:

  • id: stable kebab-case string
  • titleKey and descriptionKey: settings i18n keys
  • config: optional typed controls

Experiments without a manual per-experiment override follow the global autoEnable preference. That preference defaults on in dev builds and off in production builds. Users can force an experiment on/off or reset it back to auto from settings.

Config entries under an experiment are settings for that experiment, not nested experiments or independent feature flags. Keep them stored with the parent experiment and gate their runtime effect on the parent experiment being enabled.

Supported config controls:

  • boolean: switch with a boolean default
  • select: fixed string options with a default
  • number: default plus optional min/max/step
  • text: default plus optional placeholder; never for secrets

Use getExperiment(id) or useExperiment(id) for callers. When an experiment is disabled, keep config stored but gate behavior as disabled.

Internal-Only Experiments

Internal-only experiments need build gates at every layer they touch:

  • Add a BuildFeature resolved from a positive-opt-in VITE_* variable in src/shared/profile/buildProfile.ts, and declare the variable in src/env.d.ts.
  • Map the experiment id to that feature in BUILD_FEATURE_GATED_EXPERIMENTS.
  • If the experiment has backing Tauri commands, gate them behind a matching block-* Cargo feature and map the VITE_* variable in scripts/block-feature-gates.sh; drift-guard tests in scripts/release/tests/release-scripts.test.mjs enforce this.
  • Set the gate to 0 in the public env in .github/workflows/release.yml.

Registry-level hiding stops stale per-user localStorage overrides from re-enabling internal surfaces in consumer builds (issue 168).

Storage Contract

Experiment preferences live in localStorage under goose:experimental-features:

{
  "version": 2,
  "autoEnable": false,
  "experiments": {
    "experiment-id": {
      "enabled": false,
      "config": {}
    }
  }
}
  • Treat version as real schema state. On newer stored versions, abort writes instead of overwriting; on older versions, migrate explicitly or discard.
  • Store autoEnable as the global default provider. Store enabled only for explicit per-experiment overrides; clearing enabled returns that experiment to auto behavior and must preserve config.
  • Keep config under the parent experiment. Do not migrate config keys into separate experiment ids or apply auto-enable behavior to individual settings.
  • Preserve unknown experiment ids when writing so branch switches do not erase local choices.
  • Write only the touched experiment/key and re-read latest storage immediately before saving to reduce cross-window clobbering.
  • Setters return boolean; callers must surface failed writes to users.
  • Use useSyncExternalStore for React subscriptions. Memoize only the current raw storage value per registry/id; do not retain historical snapshot keys.

Config UX

  • Boolean controls use switches.
  • Select controls use fixed options.
  • Number controls keep a string draft while editing, commit on blur, treat empty input as no write, commit on Enter, and clamp to min/max on commit.
  • Text controls are never for secrets.
  • Config controls may stay editable in storage while disabled, but UI should make disabled/inert behavior clear when the experiment is off.

Tauri Guardrails

Do not add Rust commands, capabilities, or permissions unless the experiment needs backend authority. If backend access is required, add the smallest typed command possible, validate all IPC input, return Result, and use async for heavy work so the UI does not freeze.

When adding commands, update capabilities with least privilege. If backend state is needed, use Tauri managed state deliberately and protect shared mutable state correctly.

Testing

Cover:

  • dev default-on and production default-off behavior
  • global auto-enable overrides and per-experiment explicit override precedence
  • resetting an explicit override back to auto while preserving config
  • enabled and disabled behavior for any gated caller
  • invalid localStorage fallback
  • unsupported storage version fallback or migration
  • typed config validation
  • number-control draft and clamp behavior
  • same-window preference updates
  • cross-window storage events
  • read and write storage failures
  • preserving unknown experiment ids when writing
  • injected test registry UI behavior without shipping fake experiments

Run focused Vitest tests and just check for frontend changes.

Graduation Cleanup

When graduating or removing an experiment, remove the registry entry, i18n keys, settings UI tests, storage assumptions, and all gated code paths. Keep migrations small and explicit if the final feature needs a real user preference.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 77422a9. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 3 months ago

README badge

README badge for block/berd/experimental-features