dif-docs
Reference for dif.sh — feature flags and A/B experiments stored as Markdown files in the repo and compiled by `dif build` into a typed TypeScript client. Use when adding feature flags, a percentage rollout, or an A/B test to a JavaScript or TypeScript app (Next.js, React, SvelteK
Install
npx skills add https://github.com/dif-sh/dif/tree/main/skills/dif-docs
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install dif-sh-dif@llmmart
git clone https://github.com/dif-sh/dif.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole dif-sh/dif collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
dif.sh reference
dif keeps each feature flag or A/B experiment as one .md file under dif/experiments/, checked into git with the code it gates. dif validate checks the files, dif build compiles them to dif/generated/client.ts, and @dif.sh/sdk (zero dependencies) assigns variants locally at runtime. No signup, no network call to evaluate a flag.
Add dif to an app
npm install -D @dif.sh/cli # or: curl -fsSL https://dif.sh/install.sh | sh
npm install @dif.sh/sdk
npx @dif.sh/cli init # scaffolds dif/, config, agent files
npx @dif.sh/cli new new-checkout --surface home
# edit dif/experiments/active/new-checkout.md: variants, weights, status: active
npx @dif.sh/cli validate
npx @dif.sh/cli build
dif/generated/ is gitignored, so add "prebuild": "dif build" (and "predev": "dif build") to package.json, or CI and deploys ship without a client.
The flag file
---
id: new-checkout
status: active
owner: sam@acme.com
surface: checkout
hypothesis: >
Inlining the address form lifts completed checkouts on mobile.
variants:
- id: "off"
weight: 90
- id: "on"
weight: 10
metrics:
primary: completed_checkout
created: 2026-07-01
---
A flag is an experiment you ramp toward 100%; an experiment holds a split. Same schema. The first variant is the fallback. Weights must sum to 100.
The call site
import "./dif/generated/client"; // once, at boot: registers every active flag
import { attributes } from "./dif/generated/audiences";
import { dif } from "@dif.sh/sdk";
dif.init({ userId: () => currentUser?.id ?? null, attributes: () => attributes() });
const checkout = dif("new-checkout", {
off: () => <OldCheckout />,
on: () => <NewCheckout />,
});
dif validate warns (W001) when a call site names an id that isn't an active experiment. At runtime, an unknown id or a variant with no matching branch renders the first branch and fires no exposure. For server rendering, use the pure assign(id, { userId, attributes }) export instead of dif(); @dif.sh/react and @dif.sh/svelte wrap both.
Docs (markdown)
- Overview, install, workspace layout: https://dif.sh/docs.md
- File format (frontmatter, audiences, exclusion groups): https://dif.sh/docs/format.md
- CLI (init, connect, new, validate, build, qa, conclude, scaffold-audiences): https://dif.sh/docs/cli.md
- SDK (
dif(),assign(), React and Svelte adapters,dif.track()): https://dif.sh/docs/sdk.md dif/config.yaml: https://dif.sh/docs/config.md- Events (cloud vs custom delivery): https://dif.sh/docs/events.md
- Validation codes (E001–E010, W001–W005): https://dif.sh/docs/troubleshooting.md
- dif cloud MCP server and read API (tools, REST endpoints, read tokens, verdicts): https://dif.sh/docs/mcp.md
- Full index: https://dif.sh/llms.txt
- Source: https://github.com/dif-sh/dif
Workflow skills
Install the workflow skills with npx skills add dif-sh/dif: dif-author-experiment (draft and validate a flag or experiment), dif-conclude-experiment (get the result from dif cloud, check the verdict, record the decision and archive), dif-triage-experiments (review every active experiment in the dif cloud overview, then ramp, turn off or conclude the ones that need action, with one PR each in autonomous mode), dif-generate-surfaces (propose dif/surfaces/ from the app's routes). dif init also writes them into .claude/skills/. The conclude and triage skills read dif cloud through its MCP server at https://cloud.dif.sh/mcp (set up with a read token) or a read token in DIF_TOKEN. Setup: https://dif.sh/docs/mcp.md
Files (dif)
-
SKILL.md 4 KB
--- name: dif-docs description: Reference for dif.sh — feature flags and A/B experiments stored as Markdown files in the repo and compiled by `dif build` into a typed TypeScript client. Use when adding feature flags, a percentage rollout, or an A/B test to a JavaScript or TypeScript app (Next.js, React, SvelteKit, plain TS), when the user wants flags as code instead of a dashboard, or when the user mentions dif, dif/config.yaml, dif build, dif validate, or @dif.sh/sdk. --- # dif.sh reference dif keeps each feature flag or A/B experiment as one `.md` file under `dif/experiments/`, checked into git with the code it gates. `dif validate` checks the files, `dif build` compiles them to `dif/generated/client.ts`, and `@dif.sh/sdk` (zero dependencies) assigns variants locally at runtime. No signup, no network call to evaluate a flag. ## Add dif to an app ```sh npm install -D @dif.sh/cli # or: curl -fsSL https://dif.sh/install.sh | sh npm install @dif.sh/sdk npx @dif.sh/cli init # scaffolds dif/, config, agent files npx @dif.sh/cli new new-checkout --surface home # edit dif/experiments/active/new-checkout.md: variants, weights, status: active npx @dif.sh/cli validate npx @dif.sh/cli build ``` `dif/generated/` is gitignored, so add `"prebuild": "dif build"` (and `"predev": "dif build"`) to `package.json`, or CI and deploys ship without a client. ## The flag file ```md --- id: new-checkout status: active owner: sam@acme.com surface: checkout hypothesis: > Inlining the address form lifts completed checkouts on mobile. variants: - id: "off" weight: 90 - id: "on" weight: 10 metrics: primary: completed_checkout created: 2026-07-01 --- ``` A flag is an experiment you ramp toward 100%; an experiment holds a split. Same schema. The first variant is the fallback. Weights must sum to 100. ## The call site ```ts import "./dif/generated/client"; // once, at boot: registers every active flag import { attributes } from "./dif/generated/audiences"; import { dif } from "@dif.sh/sdk"; dif.init({ userId: () => currentUser?.id ?? null, attributes: () => attributes() }); const checkout = dif("new-checkout", { off: () => <OldCheckout />, on: () => <NewCheckout />, }); ``` `dif validate` warns (W001) when a call site names an id that isn't an active experiment. At runtime, an unknown id or a variant with no matching branch renders the first branch and fires no exposure. For server rendering, use the pure `assign(id, { userId, attributes })` export instead of `dif()`; `@dif.sh/react` and `@dif.sh/svelte` wrap both. ## Docs (markdown) - Overview, install, workspace layout: https://dif.sh/docs.md - File format (frontmatter, audiences, exclusion groups): https://dif.sh/docs/format.md - CLI (init, connect, new, validate, build, qa, conclude, scaffold-audiences): https://dif.sh/docs/cli.md - SDK (`dif()`, `assign()`, React and Svelte adapters, `dif.track()`): https://dif.sh/docs/sdk.md - `dif/config.yaml`: https://dif.sh/docs/config.md - Events (cloud vs custom delivery): https://dif.sh/docs/events.md - Validation codes (E001–E010, W001–W005): https://dif.sh/docs/troubleshooting.md - dif cloud MCP server and read API (tools, REST endpoints, read tokens, verdicts): https://dif.sh/docs/mcp.md - Full index: https://dif.sh/llms.txt - Source: https://github.com/dif-sh/dif ## Workflow skills Install the workflow skills with `npx skills add dif-sh/dif`: `dif-author-experiment` (draft and validate a flag or experiment), `dif-conclude-experiment` (get the result from dif cloud, check the verdict, record the decision and archive), `dif-triage-experiments` (review every active experiment in the dif cloud overview, then ramp, turn off or conclude the ones that need action, with one PR each in autonomous mode), `dif-generate-surfaces` (propose `dif/surfaces/` from the app's routes). `dif init` also writes them into `.claude/skills/`. The conclude and triage skills read dif cloud through its MCP server at `https://cloud.dif.sh/mcp` (set up with a read token) or a read token in `DIF_TOKEN`. Setup: https://dif.sh/docs/mcp.md
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.