GA4 Analytics Toolkit

Google Analytics 4, Search Console, and Indexing API toolkit. Analyze website traffic, page performance, user demographics, real-time visitors, search querie...

Security Scan

The skill's code and runtime instructions align with its stated GA4/Search Console/Indexing purpose, but it requires sensitive Google service-account credentials and the registry metadata omits those env requirements — review credentials and npm deps before use.

Purpose & Capability

The skill implements GA4, Search Console, and Indexing API functionality and legitimately needs a Google service account, property ID, and site URL. However, the registry metadata declares no required env vars while SKILL.md and the code expect GA4_PROPERTY_ID, GA4_CLIENT_EMAIL, GA4_PRIVATE_KEY, and SEARCH_CONSOLE_SITE_URL — this mismatch is likely an oversight but should be corrected.

Instruction Scope

Runtime instructions are explicit: run npm install in scripts/, create a .env with the service account values, call functions that call Google APIs, and auto-save JSON results to results/*. The code reads only those environment vars and writes results to local files; it does not call unexpected third‑party endpoints or attempt to read unrelated system files.

Install Mechanism

The package is instruction-first with bundled source and a package.json; install is via 'cd scripts && npm install'. This is a normal install path but npm install will fetch third‑party dependencies and could run lifecycle scripts — review scripts and package.json before running npm install.

Credentials

Requested credentials (service account email and private key, GA4 property ID, Search Console site URL) are appropriate for the stated purpose. They are highly sensitive (private key) so the skill's need is proportional but you must protect those secrets and use a least‑privilege service account. The skill expects the private key in .env (dotenv) and replaces escaped newlines; ensure you store and handle the key securely.

Persistence & Privilege

always:false and model invocation is allowed (platform default). The skill auto-saves results to a local results/ directory it creates; it does not request persistent platform-wide privileges or modify other skills. Writing files to results/ is expected behavior for reporting tools.

Assessment

This package appears to do what it claims, but it needs Google service‑account credentials (including a private key) and will write results to disk and install npm dependencies. Before installing: (1) verify you trust the skill source (source/homepage unspecified), (2) inspect scripts/package.json for any postinstall or unexpected lifecycle scripts, (3) create a least‑privilege Google service account limited to the GA4, Search Console, and Indexing scopes, (4) never commit the .env or private key to source control, and (5) consider running npm install in an isolated environment (container/VM) if you are unsure. If the registry metadata will be shown to others, ask the publisher to update required env var declarations to avoid confusion.

Setup

Install dependencies:

cd scripts && npm install

Configure credentials by creating a .env file in the project root:

GA4_PROPERTY_ID=123456789
GA4_CLIENT_EMAIL=[e-mail]
GA4_PRIVATE_KEY="<your-service-account-private-key>"
SEARCH_CONSOLE_SITE_URL=https://your-domain.com
GA4_DEFAULT_DATE_RANGE=30d

Prerequisites: A Google Cloud project with the Analytics Data API, Search Console API, and Indexing API enabled. A service account with access to your GA4 property and Search Console.

Quick Start

User says	Function to call
"Show me site traffic for the last 30 days"	siteOverview("30d")
"What are my top search queries?"	searchConsoleOverview("30d")
"Who's on the site right now?"	liveSnapshot()
"Reindex these URLs"	reindexUrls(["https://example.com/page1", ...])
"Compare this month vs last month"	compareDateRanges({startDate: "30daysAgo", endDate: "today"}, {startDate: "60daysAgo", endDate: "31daysAgo"})
"What pages get the most traffic?"	contentPerformance("30d")

Execute functions by importing from scripts/src/index.ts:

import { siteOverview, searchConsoleOverview } from './scripts/src/index.js';

const overview = await siteOverview('30d');

Or run directly with tsx:

npx tsx scripts/src/index.ts

Workflow Pattern

Every analysis follows three phases:

1. Analyze

Run API functions. Each call hits the Google APIs and returns structured data.

2. Auto-Save

All results automatically save as timestamped JSON files to results/{category}/. File naming pattern: YYYYMMDD_HHMMSS__operation__extra_info.json

3. Summarize

After analysis, read the saved JSON files and create a markdown summary in results/summaries/ with data tables, trends, and recommendations.

High-Level Functions

GA4 Analytics

Function	Purpose	What it gathers
siteOverview(dateRange?)	Comprehensive site snapshot	Page views, traffic sources, demographics, events
trafficAnalysis(dateRange?)	Traffic deep-dive	Sources, sessions by source/medium, new vs returning
contentPerformance(dateRange?)	Top pages analysis	Page views, landing pages, exit pages
userBehavior(dateRange?)	Engagement patterns	Demographics, events, daily engagement metrics
compareDateRanges(range1, range2)	Period comparison	Side-by-side metrics for two date ranges
liveSnapshot()	Real-time data	Active users, current pages, current events

Search Console

Function	Purpose	What it gathers
searchConsoleOverview(dateRange?)	SEO snapshot	Top queries, pages, device, country breakdown
keywordAnalysis(dateRange?)	Keyword deep-dive	Queries with device breakdown
seoPagePerformance(dateRange?)	Page SEO metrics	Top pages by clicks, country breakdown

Indexing

Function	Purpose
reindexUrls(urls)	Request re-indexing for multiple URLs
checkIndexStatus(urls)	Check if URLs are indexed

Utility

Function	Purpose
getAvailableFields()	List all available GA4 dimensions and metrics

Individual API Functions

For granular control, import specific functions from the API modules. See references/api-reference.md for the complete list of 30+ API functions with parameters, types, and examples.

Date Ranges

All functions accept flexible date range formats:

Format	Example	Description
Shorthand	"7d", "30d", "90d"	Days ago to today
Explicit	{startDate: "2024-01-01", endDate: "2024-01-31"}	Specific dates
GA4 relative	{startDate: "30daysAgo", endDate: "today"}	GA4 relative format

Default is "30d" (configurable via GA4_DEFAULT_DATE_RANGE in .env).

Results Storage

Results auto-save to results/ with this structure:

results/
├── reports/          # GA4 standard reports
├── realtime/         # Real-time snapshots
├── searchconsole/    # Search Console data
├── indexing/         # Indexing API results
└── summaries/        # Human-readable markdown summaries

Managing Results

import { listResults, loadResult, getLatestResult } from './scripts/src/index.js';

// List recent results
const files = listResults('reports', 10);

// Load a specific result
const data = loadResult(files[0]);

// Get most recent result for an operation
const latest = getLatestResult('reports', 'site_overview');

Common Dimensions and Metrics

Dimensions

pagePath, pageTitle, sessionSource, sessionMedium, country, deviceCategory, browser, date, eventName, landingPage, newVsReturning

Metrics

screenPageViews, activeUsers, sessions, newUsers, bounceRate, averageSessionDuration, engagementRate, conversions, totalRevenue, eventCount

Tips

1. Specify date ranges — "last 7 days" or "last 90 days" gives different insights than the default 30 days
2. Request summaries — After pulling data, ask for a markdown summary with tables and insights
3. Compare periods — Use compareDateRanges() to spot trends (this month vs last month)
4. Check real-time data — liveSnapshot() shows who's on the site right now
5. Combine GA4 + Search Console — Traffic data plus search query data gives the full picture