GA4 Deep Dive

Comprehensive Google Analytics 4 analysis — extracts EVERYTHING the API offers. Health scores, scroll depth, cohorts, demographics, and more.

Security Scan

The skill largely does what its GA4-focused description promises, but there are multiple coherence issues (undeclared environment variables, missing dependency in requirements, hard-coded property/recipient values, and a prompt-injection indicator) that warrant caution before installing or running it.

Purpose & Capability

The name/description match the code: scripts call the GA4 Data API and implement deep analysis (v3/v4) and email reporting. However, some items requested/used by the code are not declared in the registry metadata: send_report_email.py requires AGENTMAIL-related environment variables and GA4 report recipient addresses (documented in SKILL.md) but the skill metadata lists no required env vars. There are also many pre-populated PROPERTIES (other property IDs) and a couple of hard-coded recipient addresses in the shell script — these are unusual but not by themselves malicious.

Instruction Scope

SKILL.md instructs users to create Google OAuth credentials and store them at ~/.config/ga-deep-dive/credentials.json (expected). It also documents environment variables (GA4_REPORT_RECIPIENTS, AGENTMAIL_INBOX, AGENTMAIL_API_KEY) needed for emailing, and cron setup. The runtime instructions and scripts will store tokens at ~/.config/ga-deep-dive/token.json and run subprocesses to execute the report scripts. The SKILL.md contains a detected prompt-injection pattern (unicode-control-chars). The instructions are not overly broad, but they do direct output to external recipients via AgentMail — the recipients and API key control who receives the reports, and those values are not enforced/declared in registry metadata.

Install Mechanism

No install spec in the registry (instruction-only). The SKILL.md instructs creating a virtualenv and running pip install -r requirements.txt. requirements.txt lists google-analytics-data and google-auth packages but does NOT include the AgentMail library referenced by send_report_email.py. That mismatch means following the written install steps will likely produce ImportError when attempting to send emails.

Credentials

Registry metadata claims no required environment variables, but the code and SKILL.md require GA4_REPORT_RECIPIENTS, AGENTMAIL_INBOX, and AGENTMAIL_API_KEY for email reports. These are sensitive (API key) and are not declared in the skill manifest. Additionally, weekly_email_report.sh contains hard-coded recipient email addresses. The number and nature of env vars is reasonable for an email feature, but the manifest omission is an incoherence and increases risk because users won't be warned that they must supply an API key and recipients.

Persistence & Privilege

The skill stores OAuth tokens and credentials under the user's home config path (~/.config/ga-deep-dive), which is expected for a local OAuth flow. always:false and normal autonomous invocation settings are used. The skill does not request elevated system-wide privileges, and it does not modify other skills' configurations. Token storage and snapshots/reports under the skill's data directory are normal for this type of tool.

Scan Findings in Context

[unicode-control-chars] unexpected: Unicode control characters were detected in SKILL.md. This could be benign (formatting/artifacts) but these characters are a common vector for trying to hide or manipulate text for prompt-injection. Review the raw SKILL.md for hidden characters before trusting automated parsing.

What to consider before installing

This skill appears to implement a legitimate GA4 analysis tool, but several inconsistencies and red flags mean you should not run it blindly: - The registry declares no required environment variables, yet the email-reporting script requires AGENTMAIL_API_KEY, AGENTMAIL_INBOX, and GA4_REPORT_RECIPIENTS. The manifest should list these; assume the scripts will read/send sensitive data. Do not provide secrets until you trust the code. - requirements.txt lacks the AgentMail dependency referenced by the email sender. If you install and run following the README, email sending will fail (or you may manually install the missing package). Inspect send_report_email.py and add/verify the dependency before running. - The code writes OAuth credentials/tokens to ~/.config/ga-deep-dive — expect local persistent tokens. If you run this, audit and, if needed, revoke OAuth tokens from your Google account afterward. - There are hard-coded property IDs and some hard-coded recipient emails / cron examples in scripts. Ensure you are not accidentally generating reports for properties you don't own, or emailing reports to addresses you did not expect. - SKILL.md contains unicode-control-chars detected by a scanner. Open the file in a hex-capable editor or run a Unicode-sanitizer to confirm there are no hidden instructions or concealed endpoints. Recommended steps before installing/running: 1. Inspect the full code locally (you already have it). Grep for any unexpected network endpoints or obfuscated content. Confirm AgentMail usage and where emails would be sent. 2. Update requirements.txt to include any missing libs (e.g., agentmail) or install them in an isolated virtualenv. Run the scripts in an isolated environment (non-production) first. 3. Provide only OAuth credentials that are scoped minimally and that you can revoke. Prefer creating a dedicated Google Cloud project/service account with read-only analytics access for testing. 4. Do not set AGENTMAIL_API_KEY or recipients until you are sure the email flow is trustworthy — test with a dry-run (--dry-run) option first. 5. If you see any unexpected recipients or hidden text/characters, do not run cron jobs or scheduled scripts. Remove or edit hard-coded recipients before automating. If you want, I can: (a) list every place the code sends data out (network calls) and where secrets are read; (b) point to exact lines that reference environment variables, token paths, and hard-coded emails; or (c) suggest minimal changes to make the skill manifest coherent (declare env vars, add missing dependencies).

The Owner's War Room — Everything GA4 can tell you about your product.

What You Get

Script	Purpose
deep_dive_v3.py	Executive summary with 7 health scores
deep_dive_v4.py	THE FULL MONTY — scroll depth, cohorts, demographics
send_report_email.py	Bi-weekly email reports

Health Scores

• Engagement — Are users engaged?
• Traffic Diversity — Too reliant on one channel?
• Retention — Do users come back? (DAU/MAU)
• Growth — Are you growing?
• Content — Any problem pages?
• Mobile — Mobile-ready?
• Geo Diversity — Global reach?

Deep Analysis (v4)

• 📜 Scroll Depth — How far users actually READ
• 🔗 Outbound Links — Where users click out to
• 🔍 Site Search — What users search for
• 👥 Demographics — Age, gender, interests
• 🌐 Search Console — Organic search performance
• 📊 Cohort Retention — Week-over-week retention
• 🎯 Audiences — Custom audience performance

---

Quick Start

Ask your OpenClaw:

"Help me set up the ga-deep-dive skill for my website"

Your agent will guide you through:

1. Creating Google Cloud OAuth credentials
2. Getting your GA4 property ID
3. Running your first analysis

---

Manual Setup

1. Install Dependencies

cd ~/.openclaw/skills/ga-deep-dive
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Get Google OAuth Credentials

1. Go to Google Cloud Console
2. Create a project (or use existing)
3. Enable Google Analytics Data API
4. Create OAuth 2.0 Client ID (Desktop app)
5. Download JSON → save as ~/.config/ga-deep-dive/credentials.json

3. Get Your GA4 Property ID

1. Open Google Analytics
2. Go to Admin → Property Settings
3. Copy the Property ID (9-digit number)

4. First Run (Auth)

source ~/.openclaw/skills/ga-deep-dive/.venv/bin/activate
python3 scripts/deep_dive_v3.py YOUR_PROPERTY_ID

It will open a browser for OAuth consent. Approve and you're set!

---

Usage

Run Analysis

# By property ID
python3 scripts/deep_dive_v3.py 123456789

# By name (if configured)
python3 scripts/deep_dive_v3.py mysite

# Full monty
python3 scripts/deep_dive_v4.py 123456789

# Custom period
python3 scripts/deep_dive_v3.py mysite --days 60

Configure Property Names

Edit scripts/deep_dive_v3.py and add to PROPERTIES:

PROPERTIES = {
    'mysite': '123456789',
    'blog': '987654321',
}

Email Reports (Optional)

Configure via environment variables:

# Required for email functionality
export GA4_REPORT_RECIPIENTS="[e-mail],[e-mail]"
export AGENTMAIL_INBOX="[e-mail]"
export AGENTMAIL_API_KEY="am_your_key_here"

Run with:

# Generate and send report
python3 scripts/send_report_email.py mysite --days 14

# Dry run (generate report only, no email)
python3 scripts/send_report_email.py mysite --dry-run

Set up cron for bi-weekly reports:

# Mondays & Thursdays at 9am (adjust env vars path)
0 9 * * 1,4 source ~/.ga4-env && cd ~/.openclaw/skills/ga-deep-dive && .venv/bin/python3 scripts/send_report_email.py mysite

---

GA4 Setup Tips

For best results, enable these in GA4 Admin:

Feature	Where	Why
Google Signals	Data Settings → Data Collection	Demographics
Search Console	Product Links → Search Console	Organic search data
Enhanced Measurement	Data Streams → Web → Enhanced	Scrolls, outbound clicks
Key Events	Events → Mark as key event	Track conversions

---

Example Output

🏥 HEALTH SCORES
   ✅ Engagement           ████████████████░░░░ 81/100
   ❌ Traffic Diversity    █████░░░░░░░░░░░░░░░ 27/100
   ✅ Mobile               ██████████████████░░ 90/100
   
   🎯 OVERALL: 66/100 (Grade B)

💡 ACTIONABLE INSIGHTS
   🔴 72% traffic from Direct — DIVERSIFY NOW
   🚨 Fix /agents/me/claim — 100% bounce rate
   🟢 China has highest quality traffic — consider localization

---

Troubleshooting

"Token expired"

rm ~/.config/ga-deep-dive/token.json
# Run again to re-auth

"No demographic data"

• Enable Google Signals in GA4
• Need 50+ users per segment (privacy threshold)

"No Search Console data"

• Link Search Console in GA4 Admin → Product Links
• Wait 24-48h for data sync

---

License

MIT — Built by ClaudiusThePirateEmperor 🏴‍☠️

Repository: https://github.com/fcavalcantirj/ga-deep-dive