Claude Skill

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

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download dif-sh-dif-skills_dif-docs-a8d1495.zip · 1 KB

Install

skills CLI npx skills add https://github.com/dif-sh/dif/tree/main/skills/dif-docs
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install dif-sh-dif@llmmart
Git 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)

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.

No comments yet.

Reviews (0)

No reviews yet.