GA4 Analytics

Google Analytics 4, Search Console, and Indexing API toolkit. Analyze website traffic, page performance, user demographics, real-time visitors, search queries, and SEO metrics. Use when the user asks to: check site traffic, analyze page views, see traffic sources, view user demographics, get real-time visitor data, check search console queries, analyze SEO performance, request URL re-indexing, inspect index status, compare date ranges, check bounce rates, view conversion data, or get e-commerce revenue. Requires a Google Cloud service account with GA4 and Search Console access.

Security Scan

The code implements the described GA4/Search Console/Indexing functionality and uses official Google client libraries, but the registry metadata omits the required Google service-account credentials and the skill asks you to store a sensitive private key in a .env and will auto-save results to disk — this mismatch and handling of secrets warrant caution.

Purpose & Capability

The skill's code and SKILL.md clearly require a Google service account (GA4_PROPERTY_ID, GA4_CLIENT_EMAIL, GA4_PRIVATE_KEY, SEARCH_CONSOLE_SITE_URL) and provide GA4/Search Console/Indexing functions which match the name/description. However the registry metadata lists no required environment variables or primary credential — that is an incoherence that could mislead users about the need to provide sensitive credentials.

Instruction Scope

Runtime instructions are explicit: run npm install, create a .env with service-account credentials, then call functions or run scripts. The code only reads environment variables and calls Google APIs; it also auto-saves API responses as timestamped JSON under results/*. There are no instructions or code that read unrelated system files or send data to third-party endpoints outside Google APIs, but storing the private key in .env and auto-saving results (which include propertyId metadata) increases the risk of accidental leakage if the project folder is shared or committed.

Install Mechanism

There is no custom binary download; installation is standard npm install as documented in SKILL.md and scripts/setup.sh. Dependencies are standard packages (@google-analytics/data, @googleapis/indexing, @googleapis/searchconsole, googleapis, dotenv, tsx, typescript) from npm, which is proportionate for the claimed functionality.

Credentials

The skill legitimately needs service-account credentials and a property/site identifier to operate, and the code expects GA4_PROPERTY_ID, GA4_CLIENT_EMAIL, GA4_PRIVATE_KEY and SEARCH_CONSOLE_SITE_URL in environment variables. Those are sensitive (private key) and are not declared in the registry metadata. The number and sensitivity of env vars is reasonable for the purpose but the missing metadata declaration and guidance to place the raw private key into .env is a notable risk.

Persistence & Privilege

The skill does not request always:true and does not modify other skills. It persists results locally to a results/ directory (JSON files with metadata that include propertyId). Saving outputs to disk is expected for analytics work, but you should be aware that results and metadata could expose site identifiers and should not be committed to public repositories; the skill also creates no other persistent system-wide configuration.

What to consider before installing

What to consider before installing: - Metadata mismatch: the registry metadata does not declare required env vars, but SKILL.md and the code require a Google service-account (GA4_PROPERTY_ID, GA4_CLIENT_EMAIL, GA4_PRIVATE_KEY, SEARCH_CONSOLE_SITE_URL). Treat this as a red flag and verify why metadata was omitted. - Secrets handling: the README instructs placing the service account private key in a .env file. If you use this skill, keep the project directory private, add .env to .gitignore, and rotate the key if it may have been exposed. - Least privilege: create a Google service account with the minimal scopes needed (GA4 Data API, Search Console read, Indexing limited as appropriate). Don't reuse broad or owner-level credentials. - Auto-saved data: the skill saves API responses and metadata (including propertyId) under results/. Review and restrict access to those files and avoid committing them to source control. - Review code locally: since code files are included, inspect scripts/src/* for any custom network endpoints or telemetry (none were found; only official Google client libraries are used). If you are unsure, run the project in an isolated environment (container or ephemeral VM). - Indexing/remove functions: the Indexing API functions can request reindexing or request removals. Only grant indexing permission if you trust the code and the environment, and be cautious when invoking removal operations. If these concerns are acceptable and you verify the code and credentials, the implementation itself aligns with the stated purpose. If you cannot verify the author or reason for the metadata omission, do not install or provide credentials until the issue is resolved.

GA4 Analytics Toolkit

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="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
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