Agent Skill

The Traffical Agent Skill teaches AI coding agents how to use Traffical in your codebase. Instead of reading the docs and wiring everything by hand, your agent does the work the right way: it installs and drives the CLI, links a project, authors config-as-code, installs the matching SDK, parametrizes your code, and places events where conversions actually happen. It’s open source (github.com/traffical/skills), validated against the real SDK so it doesn’t drift, and works with 40+ coding agents — Claude Code, Cursor, Codex, Windsurf, Cline, and more.

Install

npx skills add traffical/skills

The installer auto-detects the agents you have and adds the skill to each. Common options:

npx skills add traffical/skills -a claude-code   # one specific agent
npx skills add traffical/skills -g               # globally (all projects)
npx skills add traffical/skills --list           # preview without installing

Once it’s installed, just talk to your agent normally — it pulls the skill in whenever you do something Traffical can help with: adding a feature, changing UI, pricing, or copy, auditing a repo, wiring event tracking, or any time it sees a .traffical/ directory.

What it does

Set up from zero

Installs the CLI, logs in (device flow), finds or creates a project, and scaffolds .traffical/ — including a browser-safe SDK key.

Wire the SDK

Installs the right @traffical/* package and wires the provider/client for your framework — React, Next.js, Svelte, Node, React Native, and more.

Parametrize code

Lifts hardcoded values — prices, copy, thresholds, colors — into typed parameters you can control without a deploy.

Author config-as-code

Edits .traffical/config.yaml, runs push, and keeps generated types in sync — without inventing CLI commands or keys.

Place events correctly

Adds track() at the real conversion point (not on click or render), with the right signature for each SDK.

Audit a codebase

Finds the product decisions frozen in your code — hardcoded values, hand-rolled flags (env toggles, if (FLAG), LaunchDarkly/Split/Unleash), model/prompt choices — and proposes a small ranked set of parameters, with a reviewable state file so dismissed findings stay dismissed.

Parametrize, don’t flag

The skill is built around one core habit, and it’s the one that pays off the most: parametrize the real values — don’t just wrap them in on/off flags. A boolean feature flag only buys you on/off. A typed parameter buys you on/off and every value in between — controllable and experimentable forever, from the dashboard or via the API, without another code change. This is the “parametrize once, control forever” idea: the moment a value lives in Traffical, anyone — an engineer, a PM in the dashboard, or an automated optimizer — can change it, ramp it, or test it.

	Boolean flag	Typed parameter
What it controls	on / off	on/off and any value
Change without a deploy	toggle only	every value (copy, price, threshold, color…)
Experiment	A/B the flag	A/B/n, gradual rollouts, bandit optimization on the value
Who can change it	an engineer + a deploy	anyone, from the dashboard or API

Example — a “free shipping this weekend” banner:

Flag-first (weak)
Parametrize the substance (what the skill does)

parameters:
  feature.promo_banner:
    type: boolean
    default: false

You can show or hide the banner. The copy, the threshold, and the CTA are all still frozen in code — every tweak is a code change and a deploy.

parameters:
  ui.promo_banner.visible:
    type: boolean
    default: false
  copy.promo_banner.headline:
    type: string
    default: "Free shipping all weekend!"
  copy.promo_banner.cta_text:
    type: string
    default: "Shop now"
  ui.promo_banner.background_color:
    type: string
    default: "#1E6EFB"

The same surface now supports a kill switch, a copy test, a threshold sweep, and bandit optimization — all from outside the code.

The skill reserves feature.* booleans for things that are genuinely binary — a true kill switch, or a feature that’s simply present or absent — and reaches for a typed value parameter everywhere else. When it sees a boolean about to gate a block of hardcoded values, it lifts those values into parameters instead. See Feature flags for where booleans still fit.

How it helps with the work

New features, built experiment-ready

When you ask the agent to build something new, the skill makes it build it parametrized and rollout-ready by default — typed parameters with in-code defaults, read through the SDK, with a conversion event wired in. You can ship it dark, ramp it, or A/B test it later without revisiting the code.

Existing codebases

Point the agent at code you already have:

Audit — it inspects the repo and proposes a small, ranked set of product decisions worth managing (capped at ~10) — hand-rolled flags, revenue levers, ranking weights, model/prompt choices — each with file:line evidence, a ready-to-paste parameter block whose default equals the current value (so nothing changes on day one), and the outcome metric that would measure it, or the missing event to define first. It changes no code and writes two artifacts: TRAFFICAL_AUDIT.md (the report — including untracked conversions, what it deliberately did not flag, and a suggested order) and .traffical/audit.yaml (review state — mark findings accepted or dismissed with a reason, and re-audits respect those decisions instead of re-proposing them).
Parametrize — it turns a specific hardcoded value into a parameter: defines it in config with the default equal to the current value (so behavior is unchanged on day one), runs push, then replaces the literal with an SDK read.
Migrate flags — it converts env-var toggles or third-party flags into Traffical parameters, usually richer than a 1:1 boolean (e.g. a NEXT_PUBLIC_NEW_HERO env flag becomes a ui.hero.variant enum plus copy.hero.headline, so you can test layouts and copy, not just on/off).

Wiring and correctness

The skill knows the per-framework provider setup, the exact track() signature for each SDK, identity binding (unitKeyFn / identify() for logged-in users), SSR hydration, and how to keep config-as-code in sync. Because it’s checked against the real SDK, it doesn’t drift into wrong package names, exports, or key formats.

Example prompts

The skill triggers on natural requests — you don’t name it. A few examples:

You say	The agent does
”Set us up with Traffical and put the checkout button color behind it.”	Logs in, inits the project, installs `@traffical/react`, defines `checkout.button.color`, wires the provider, reads it via the SDK, and pushes.
”Go through this repo and tell me what we should move into Traffical.”	Writes a ranked `TRAFFICAL_AUDIT.md` — hand-rolled flags, revenue levers, untracked conversions — plus `.traffical/audit.yaml` review state, so you can accept or dismiss each finding and re-audit later. No code changed.
”Make the pricing card’s discount, CTA, and highlight color controllable without a redeploy.”	Lifts each value into a typed parameter (number with constraints, strings), reads them via the SDK with in-code defaults, and pushes.
”We’re flying blind on checkout — nothing fires when an order completes.”	Defines a `purchase` currency event and fires `track()` at the success point (with `flushEvents()` before navigation, where relevant).

Benefits

Right the first time — convention-following parameter names, correct event placement, correct SDK wiring.
Parametrize-first — your code becomes controllable and experimentable without redeploys, by design.
Faster — setup, SDK wiring, and config authoring that would take several docs pages happen in one pass.
Safe — config-as-code stays the source of truth; the skill never fabricates keys or commands and respects the boundary (it parametrizes and tracks; experiments and policies stay in the dashboard).
Consistent — every parameter and event follows the same conventions across your team.

Next steps

CLI

The config-as-code commands the skill drives.

Configuration file

Every field in config.yaml, project.yaml, and metrics.yaml.

Parameters

Typed values with defaults — what the skill parametrizes into.

Quickstart

Resolve a parameter and track an event by hand.

Getting started

Core concepts

Experimentation

Statistics

Guides

Dashboard

Governance

Warehouse connectors

Developer tools

Reference

Install

What it does

Set up from zero

Wire the SDK

Parametrize code

Author config-as-code

Place events correctly

Audit a codebase

Parametrize, don’t flag

How it helps with the work

New features, built experiment-ready

Existing codebases

Wiring and correctness

Example prompts

Benefits

Next steps

CLI

Configuration file

Parameters

Quickstart

​Install

​What it does

Set up from zero

Wire the SDK

Parametrize code

Author config-as-code

Place events correctly

Audit a codebase

​Parametrize, don’t flag

​How it helps with the work

​New features, built experiment-ready

​Existing codebases

​Wiring and correctness

​Example prompts

​Benefits

​Next steps

CLI

Configuration file

Parameters

Quickstart

Install

What it does

Parametrize, don’t flag

How it helps with the work

New features, built experiment-ready

Existing codebases

Wiring and correctness

Example prompts

Benefits

Next steps