> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traffical.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Skill
> Install the Traffical Agent Skill so your AI coding agent sets up Traffical, parametrizes your code, wires the SDK, and places events correctly — across Claude Code, Cursor, and 40+ other agents.
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](/tools/cli), links a project, authors [config-as-code](/tools/config-file), installs the matching [SDK](/sdks/overview), parametrizes your code, and places [events](/concepts/events-and-metrics) where conversions actually happen.
It's open source ([github.com/traffical/skills](https://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
```bash theme={null}
npx skills add traffical/skills
```
The installer auto-detects the agents you have and adds the skill to each. Common options:
```bash theme={null}
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
Installs the CLI, logs in (device flow), finds or creates a project, and scaffolds `.traffical/` — including a browser-safe SDK key.
Installs the right `@traffical/*` package and wires the provider/client for your framework — React, Next.js, Svelte, Node, React Native, and more.
Lifts hardcoded values — prices, copy, thresholds, colors — into typed parameters you can control without a deploy.
Edits `.traffical/config.yaml`, runs `push`, and keeps generated types in sync — without inventing CLI commands or keys.
Adds `track()` at the real conversion point (not on click or render), with the right signature for each SDK.
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](/concepts/parameters) buys you on/off **and every value in between** — controllable and experimentable forever, from the [dashboard](/dashboard/parameters) 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](/experimentation/rollouts), bandit [optimization](/experimentation/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:**
```yaml theme={null}
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.
```yaml theme={null}
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](/experimentation/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](/sdks/ssr), 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
The config-as-code commands the skill drives.
Every field in `config.yaml`, `project.yaml`, and `metrics.yaml`.
Typed values with defaults — what the skill parametrizes into.
Resolve a parameter and track an event by hand.