Agent Skills
Agent skills ship with Premium installations (v2.2.10+).
A skill is a set of instructions your AI assistant loads only when the task matches. Ask "backfill last March" and the assistant picks up the reprocessing procedure - the right variables, the cost estimate to show you first, the batching script for large ranges - instead of inventing an approach. The rest of the time those instructions stay out of the way.
Every installation ships ten of them, written against your actual project: the table names, the config files, the tags and the pitfalls are the real ones, not generic GA4 advice.
Where they live​
| Folder | Loaded automatically by |
|---|---|
.claude/skills/ | Claude Code, Cursor |
.agents/skills/ | Codex CLI, Gemini CLI |
Both folders contain the same ten skills - which one your tool reads is the only difference. Any other agent can be pointed at .claude/skills/README.md, which lists what each skill covers.
What is covered​
| Skill | Kicks in when you ask about |
|---|---|
ga4df-onboarding | Setting up a fresh install: "onboard me", "get me started", what to configure or enable first. A test mode rehearses the whole flow without changing anything |
ga4df-querying-data | Writing queries against the output tables - correct grain, partition filters, is_final, and why numbers differ from the GA4 interface |
ga4df-debugging-pipeline | Failed or stuck runs, stale or empty tables, failing assertions, schema mismatch errors |
ga4df-custom-params | Adding custom event parameters, user properties, session parameters or channel groupings - including the STRUCT schema patch an existing table needs |
ga4df-custom-models | Building your own tables and views in definitions/custom/, and the custom lineage templates that insert your logic between core tables |
ga4df-reprocessing | Backfilling or recomputing history, rebuilding tables, and splitting a large rebuild into batches |
ga4df-managing-runs | Triggering runs, running specific tags, scheduling the daily workflow, and pushing local edits back to the workspace |
ga4df-premium-guide | The Core→Premium upgrade, what Premium adds, and how to configure a specific module or ga4 option |
ga4df-cost-monitoring | Historical BigQuery cost: which jobs cost the most, why the bill moved, storage trends |
ga4df-skill-creator | Writing your own skill for a procedure your team repeats |
Working safely​
The skills are written to keep an assistant from doing expensive or destructive things on your behalf:
- Cost is estimated before it is spent. Anything that scans the raw export gets a dry run first, with the estimated bytes shown to you for approval.
- Configuration and data changes are confirmed with you, and scoped: runs use explicit tags rather than rebuilding everything.
- Managed folders are off limits.
definitions/core/andincludes/core/are replaced on every update, so the assistant is told to work in thecustom/folders instead. - Order of operations is spelled out where getting it wrong breaks a build - patching a STRUCT schema before reprocessing, recompiling the release before a run.
Bundled scripts​
Some procedures come with a script the assistant can run:
| Script | What it does |
|---|---|
.claude/skills/ga4df-custom-params/scripts/patch_struct_schema.sh | Adds a field inside an existing BigQuery STRUCT column so a new custom parameter can be introduced without a full rebuild |
.claude/skills/ga4df-managing-runs/scripts/recompile_release.py | Recompiles the release configuration from the command line |
.claude/skills/ga4df-managing-runs/scripts/push_dataform_workspace.py | Pushes a local copy of the workspace back through the Dataform API |
scripts/batch-reprocess.sh | Splits a large backfill into sequential batches to stay under BigQuery's 6-hour query limit |
Reference guides the assistant reads​
Longer reference material sits next to the skills and is opened only when needed - most usefully ga4df-premium-guide/references/ga4-setup.md, a complete reference for every ga4 module option: what it does, its default, whether changing it needs a schema patch, and what it does to existing history. There are matching setup guides for the attribution module and the Cloud Storage export.
Using them​
Open your workspace with one of the tools above and ask in plain language.
- Repository connected to GitHub or GitLab: clone it, work locally, push as usual.
- Installed without a git connection (the default): the repository cannot be cloned, so copy the workspace to a local folder through the Dataform API first - the copy script and the full walkthrough are in Onboarding with an AI Agent. Once you have that copy,
push_dataform_workspace.pysends your edits back - dry-run it first and it lists exactly what would change, and it refuses to overwrite anything that changed in the Dataform interface since you copied it.
Whichever route you take, remember that a pushed change only takes effect once the release is recompiled - the assistant knows this and will prompt you.
Fill in MY-COMPANY.md before leaning on the skills for analysis. It is where your conversions, KPIs and channel conventions live, and it turns generic answers into answers about your business. See AI-Ready Workspace.
Adding your own​
The ten ga4df-* skills are replaced on every update. Any skill you create under a different name is yours and survives updates, exactly like definitions/custom/.
Good candidates are the procedures your team repeats the same way every time: a weekly KPI report with its exact queries, how you investigate a traffic drop, an export routine for a BI tool. Ask your assistant to use ga4df-skill-creator - it covers where skills live, how to write a description that actually triggers, and the rules that keep a skill reliable (name real tables, read configuration values at runtime rather than copying them, gate anything that spends money).