Analytics skill

A Claude skill that answers plain-language questions about site analytics by reading live data from Google Analytics 4, Google Search Console, and Semrush — e.g. "how many active users last month", "top search queries this week", "how many organic keywords do we rank for".

It's packaged as a plugin so it can be distributed to a whole team: everyone authenticates as themselves (OAuth / Application Default Credentials — no shared keys), and each person does a one-time local setup.

Layout

analytics-skill/                 # plugin root
├── .claude-plugin/
│   └── plugin.json              # plugin manifest (name, version, author)
├── package-org-plugin.sh        # build analytics.plugin with the Semrush key injected
└── skills/
    └── analytics/
        ├── SKILL.md             # routes a question -> the right source, with examples
        ├── setup.sh             # one-time per-user setup (venv + auth steps)
        ├── defaults.json        # bundled shared config (Semrush key injected at org build)
        ├── config.example.json  # optional per-user override template
        ├── requirements.txt
        └── scripts/
            ├── analytics.py     # dispatcher:  analytics.py <ga4|gsc|semrush> ...
            ├── ga4.py           # GA4 Data API
            ├── gsc.py           # Search Console Search Analytics API
            ├── semrush.py       # Semrush Analytics API
            └── config.py

Mutable state (the Python venv, config.json, credentials) lives in a stable home, ~/.analytics-skill/, outside the plugin directory — so a plugin update/re-sync never wipes your setup.

Install

Org members (recommended): the plugin is published to the Causaly organisation, so it appears in your Claude app automatically — no cloning. Then do the one-time setup below.

Manual / development (clone the repo): add it as a plugin marketplace and install, or just run the setup script directly from a checkout.

One-time setup (each user)

For Google (GA4 + Search Console) everyone authenticates as themselves — no shared Google key, no downloadable service-account file; credentials live in your local gcloud config. The Semrush API key is a genuinely shared credential and ships bundled with the plugin, so there's nothing to paste.

1. Run the setup script — creates ~/.analytics-skill/ with a Python venv, installs dependencies, and scaffolds config.json:

skills/analytics/setup.sh

2. Authenticate with Google (ADC) — as printed by the script:

gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/cloud-platform"
gcloud auth application-default set-quota-project csly-marketing-analytics

The quota project matters: user-credential API calls must bill to one, and the marketing group has serviceUsageConsumer on csly-marketing-analytics for exactly this. The Google Analytics Data API and Search Console API are enabled there. You need GA4 Viewer and Search Console access under your own Google account (you likely already have it) — no per-user property changes required.

3. Nothing to configure. The shared settings — GA4 property ID, GSC site URL, quota project, and the Semrush API key — ship with the plugin as bundled defaults (skills/analytics/defaults.json; the Semrush key is injected into the org build, not this public repo). You only authenticate as yourself in step 2.

Advanced overrides: drop a ~/.analytics-skill/config.json to override any bundled value per key (it's deep-merged over the defaults). You can also set ga4.credentials_path / gsc.credentials_path to a service-account.json to use a key instead of ADC — ADC is the recommended path and needs neither.

Usage

In any Claude surface where the plugin is available, just ask:

• /analytics how many users were active last month
• "top 10 search queries last week" → Search Console
• "how many organic keywords do we rank for" → Semrush

The skill picks the right source(s), computes the date range, runs the script, and answers in plain language.

Distributing to the team

This repo is a self-contained plugin (.claude-plugin/plugin.json). To publish it to the Causaly org so colleagues get it automatically — the same way the content plugin is distributed — see PUBLISHING.md.

Notes

• GA4 / Search Console data lags ~1–3 days.
• Search Console keeps ~16 months of history.
• Each Semrush call spends paid API units, so avoid speculative loops.

Troubleshooting

• GA4 PERMISSION_DENIED → your Google account isn't a Viewer on the GA4 property (or, if using a service-account key, that account isn't a Viewer).
• Search Console error → your account isn't a user on the Search Console property.
• Reauthentication is needed / invalid_grant → re-run gcloud auth application-default login.
• SERVICE_DISABLED / quota-project errors → run gcloud auth application-default set-quota-project csly-marketing-analytics and confirm you have serviceUsageConsumer on it.
• Missing config file → run skills/analytics/setup.sh, or create ~/.analytics-skill/config.json.
• Semrush ERROR 50/120 → bad API key or no units remaining.
• Skill not showing up → for org installs, confirm the plugin is published to your org and you're signed in; for a checkout, confirm the plugin is installed/enabled.