# Agent skills

`npx splithub init` (and `npx splithub skills`) installs nine skills into the project. A skill is a Markdown file with a front-matter description that a coding agent loads when the task matches. They go to `.claude/skills/<name>/SKILL.md` for Claude Code, to `.cursor/rules/splithub.mdc` for Cursor, and a short section in `AGENTS.md` (or an existing `CLAUDE.md`) points Codex and other agents at them.

| Skill | Loaded when | Teaches |
|---|---|---|
| `splithub` | the user asks to A/B test something, asks which variant wins, or wants notes, alerts, short links or allowed domains | where things live (config, credentials, results), how to create each kind of experiment, how to read a verdict and its slices, what never to do |
| `splithub-analytics` | the user wants traffic numbers, page or source reports, event tracking or funnels, or asks to add analytics | setting up a property with `analytics connect`, sending pageviews, events and `identify`, every report, archiving, allowed domains, billing |
| `splithub-apps` | the project has React Native, Expo, an Xcode project or an Android Gradle build, or the user asks to test or measure an app | install per platform, screens as pages, why app experiments start in the dashboard, `app_version` targeting, platform breakdowns, retention |
| `ab-testing` | before creating an experiment or interpreting results | hypothesis and primary metric, sample size rule of thumb, SRM, peeking, guardrails, when to stop, vocabulary |
| `splithub-api` | writing a server, a script or a non-JS client | the HTTP API: public-key ingest, API keys and scopes, project endpoints for experiments, analytics, notes, links and alerts, errors |
| `splithub-mcp` | connecting SplitHub to Claude Code, Cursor or Codex | how to register the MCP server, the tools, working rules |
| `splithub-self-hosted` | the user wants data in their infra, asks about tables or reports | the events table, the Store interface, Postgres/MySQL/Prisma/Drizzle/Supabase notes, attribution SQL, pulling cloud summaries into a warehouse |
| `splithub-ship` | an experiment has a verdict and the user says ship it, roll out the winner or remove the experiment | finish first, then keep only the winning value, component or page, delete the losers, clean the config, verify, never reuse the id |
| `splithub-loop` | the user asks to run an experiment end to end, or to pick one up where it stands | the whole loop, step by step with the MCP tools and CLI `--json` fields: plan, create, implement, check, push, read results, finish, ship |

## What the main skills say, in short

- `splithub.config.ts` is the source of truth; it ships to the browser, so no secrets.
- Credentials come from `npx splithub login` (a link the human approves). Never ask the user to paste keys.
- One install covers analytics and experiments: `npx splithub analytics connect` names a property on the provider; the same `track()` feeds reports and experiments.
- An experiment's goal can be any event the app tracks; nothing to declare first.
- Prefer `value` experiments (data only) over `component` ones; `redirect` for whole pages; `mvt` only with enough traffic.
- Create the experiment (running by default), wire the code, run `doctor` and `push`. Then always tell the user it goes live when they deploy, and that Pause in the dashboard or `npx splithub pause <id>` holds it.
- To check a draft before it starts: `runDraftsInDev: true` in the config (development only), `?sh_force=<id>:<variant>` on any page, `?sh_debug=1` for the decisions.
- Report `verdict.message` verbatim with the numbers behind it, plus sample quality and stars. `srm_detected` means fix the setup first. A slice or a segment never decides.
- A finished experiment still has its variants in the code: ask which one to keep and whether to remove it, then follow `splithub-ship`.
- Analytics counts are never an experiment result.
- In an app the config ships inside the binary, so new experiments start in the dashboard; gate them on the `app_version` that has their code.
- Never change `seed`, weights or variants of a running experiment; never nest experiments; keep 2–3 experiments per page at most.

## Reading the full text

The skills are plain files in your project after `init`. They are also what the dashboard's "Copy for your agent" prompt refers to, and this documentation covers the same ground page by page. For a single file with everything: [llms-full.txt](/llms-full.txt).

## Updating

`npx splithub skills` rewrites the skill files with the current text from SplitHub Cloud, or with the copies bundled in the installed CLI when the cloud cannot be reached. A file at one of those paths that does not mention SplitHub is left alone unless you pass `--force`. They are safe to commit; agents on the team get the same rules.