Plausible Analytics Agent

Track pageviews and custom events via the Plausible Events API, and query stats (top pages, top sources, countries, realtime visitors). Use when you need to...

Security Scan

The skill's code, instructions, and requested environment variables are coherent with a Plausible Analytics integration; nothing in the bundle indicates hidden or unrelated behavior.

Purpose & Capability

Name and description match the scripts and behavior: the scripts call Plausible Events and Stats APIs and require PLAUSIBLE_SITE_DOMAIN and PLAUSIBLE_API_KEY. Minor inconsistency: the skill bundle does not declare required binaries, but the scripts use curl and jq — these should be documented as required.

Instruction Scope

SKILL.md and the scripts limit actions to building and sending requests to the Plausible base URL (default plausible.io) and printing JSON. They read only the declared env vars (plus the optional PLAUSIBLE_BASE_URL). No unrelated filesystem reads, local secrets, or external endpoints are hard-coded. Note: PLAUSIBLE_BASE_URL is user-configurable, so if set to an arbitrary URL it would direct events/stats to that host (this is expected but should be chosen carefully).

Install Mechanism

No install spec or remote downloads are present; this is an instruction-only skill with included shell scripts. No archives or external installers are fetched, which is low-risk.

Credentials

The skill requires PLAUSIBLE_SITE_DOMAIN and PLAUSIBLE_API_KEY which are appropriate for Plausible Stats calls. PLAUSIBLE_BASE_URL is used but optional and not listed in required env vars — that's acceptable but could be documented. The API key is used only in Authorization headers for stats/realtime/top-pages endpoints; the Events API is intentionally used unauthenticated per Plausible design.

Persistence & Privilege

always:false (default) and the skill does not request to modify other skills or system-wide settings. It does not persist credentials or install background services.

Assessment

This skill appears to do exactly what it says: call Plausible's Events and Stats APIs. Before installing, make sure: 1) you provide a Plausible API key with minimal required scope and rotate it regularly; 2) PLAUSIBLE_BASE_URL is set only to your Plausible instance or plausible.io (don't point it at unknown hosts, or events/stats could be sent elsewhere); 3) the agent environment has curl and jq available (the scripts use them but the bundle doesn't declare them); and 4) avoid including PII in custom event props since those are sent to the configured endpoint. If any of these are unacceptable, don't enable the skill or run the scripts in a controlled environment first.

Plausible Analytics

Track events and query stats from Plausible Analytics (self-hosted or plausible.io).

Configuration

Set these environment variables before use:

# Your site domain (e.g. example.com)
export PLAUSIBLE_SITE_DOMAIN="example.com"

# Your Plausible API key (for stats endpoints)
export PLAUSIBLE_API_KEY="your-api-key"

# Plausible base URL (default: https://plausible.io for hosted)
# For self-hosted, set to your instance URL
export PLAUSIBLE_BASE_URL="https://plausible.io"

Track Pageview

bash skills/plausible-analytics/scripts/track.sh \
  --domain "$PLAUSIBLE_SITE_DOMAIN" \
  --url "https://example.com/blog/post-1" \
  --referrer "https://google.com"

Options:

• --domain — Site domain (default: $PLAUSIBLE_SITE_DOMAIN)
• --url — Page URL being viewed (required)
• --referrer — Referring URL (optional)
• --base-url — Plausible base URL (default: $PLAUSIBLE_BASE_URL)

Track Custom Event

bash skills/plausible-analytics/scripts/track.sh \
  --domain "$PLAUSIBLE_SITE_DOMAIN" \
  --event "Signup" \
  --props "{\"plan\":\"pro\",\"source\":\"newsletter\"}"

Options:

• --domain — Site domain
• --event — Custom event name (e.g. "Signup", "Button Click")
• --props — JSON object with event properties (optional)
• --base-url — Plausible base URL

Get Stats Summary

bash skills/plausible-analytics/scripts/stats.sh \
  --domain "$PLAUSIBLE_SITE_DOMAIN" \
  --period "30d" \
  --compare "previous_period"

Options:

• --domain — Site domain
• --period — Time period: 6mo, 12mo, day, 7d, 30d, month (default: 30d)
• --compare — Compare to previous period: previous_period (optional)
• --base-url — Plausible base URL (default: $PLAUSIBLE_BASE_URL)

Returns: pageviews, unique visitors, bounce rate, visit duration, total pageviews

Get Top Pages

bash skills/plausible-analytics/scripts/top-pages.sh \
  --domain "$PLAUSIBLE_SITE_DOMAIN" \
  --period "30d" \
  --limit 10

Options:

• --domain — Site domain
• --period — Time period (default: 30d)
• --limit — Number of pages to return (default: 10)
• --base-url — Plausible base URL

Get Realtime Visitors

bash skills/plausible-analytics/scripts/realtime.sh \
  --domain "$PLAUSIBLE_SITE_DOMAIN"

Options:

• --domain — Site domain
• --base-url — Plausible base URL

Returns: current visitors on site, pageviews in last 30 min, top pages currently viewed

Notes

• The Events API (/api/event) is used without authentication for tracking
• The Stats API (/api/v1/stats) requires PLAUSIBLE_API_KEY set in the request header
• For self-hosted Plausible, set PLAUSIBLE_BASE_URL to your instance
• All scripts output JSON or plain text depending on the endpoint