plausible-analytics - SKILL.md Agent Skill

name: plausible-analytics description: Adds Plausible Analytics to Astro sites with a Cloudflare Workers proxy for privacy and ad-blocker bypass. Requires a project deploying to Cloudflare Workers (uses `worker/index.js` route registration). Use when user requests "add Plausible", "add analytics", "add tracking", "page views", "visitor tracking", or privacy-friendly analytics. Skip if the project deploys to Vercel/Netlify/static-only — paste Plausible's standard `<script>` tag into Layout directly, no skill needed.

Plausible Analytics

Why a Worker proxy

Plausible's standard <script> tag works, but it's served from plausible.io — a domain in every ad blocker's default list. Routing the script and event endpoint through a same-origin Cloudflare Worker (/~/pla/...) makes the requests first-party: ad blockers don't recognize the path, the browser doesn't send third-party cookies (we strip what's left), and Cloudflare's edge caches the script so latency stays low. You get the privacy benefits Plausible already provides plus measurable lift in tracked sessions.

Workflow

Ask user for their Plausible site ID (e.g., pa-CU5TnHVZaYl2kUd7gcJAE) or have them paste their tracking script. The ID comes from Plausible's UI: Site Settings → Site Installation, where the script URL has the form https://plausible.io/js/pa-XXXXX.js. This is Plausible's modern per-site script (the URL itself encodes the site identity), not the legacy script.js + data-domain pattern.
Create worker/plausible.js from assets/plausible.js and replace the ProxyScript constant with the user's full script URL
Register the /~/pla route in worker/index.js
Add the tracking script to Layout.astro

Worker Setup

See step 2 above. Route registration in worker/index.js:

import { handlePlausible } from './plausible.js';

const ROUTES = {
  '/~/pla': { handler: handlePlausible, description: 'Plausible Analytics Proxy' },
  // ... other routes
};

Layout Integration

Add to src/layouts/Layout.astro at the bottom of <body>:

<!-- Privacy-friendly analytics by Plausible -->
<script async src="/~/pla/js/script.js"></script>
<script>
  window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};
  plausible.init({
    endpoint: "/~/pla/api/event"
  })
</script>

How It Works

/~/pla/js/script.js - Proxies and caches Plausible script
/~/pla/api/event - Proxies tracking events to Plausible API
Cookies stripped for privacy
Bypasses ad blockers by using first-party domain
Uses Cloudflare's edge caching

Getting Plausible Script URL

Sign up at plausible.io
Add your domain
Go to Site Settings → Site Installation
Copy the script URL: https://plausible.io/js/pa-XXXXX.js

Assets

assets/plausible.js - Worker handler example