Plausible

## Setup On first use, read `setup.md` for integration guidelines. ## When to Use User needs website traffic data from Plausible. Agent queries visitors, pageviews, referrers, goals, and custom events through the Plausible API. ## Architecture Memory lives in `~/plausible/`. See `memory-template.md` for structure. ``` ~/plausible/ ├── memory.md # Sites + preferences (no secrets stored) └── queries/ # Saved query templates (optional) ``` ## Quick Reference | Topic | File | |-------|------| | Setup process | `setup.md` | | Memory template | `memory-template.md` | ## Core Rules ### 1. API Key from Environment API key comes from `PLAUSIBLE_API_KEY` environment variable. Never hardcode or ask user to paste keys in chat. ### 2. Site ID Required Every query needs a site_id (domain). Check memory.md for configured sites before asking. ### 3. Time Periods Default to `30d` unless user specifies. Valid periods: `day`, `7d`, `30d`, `month`, `6mo`, `12mo`, `custom` (requires date/date_range). ### 4. Metrics Available | Metric | Description | |--------|-------------| | `visitors` | Unique visitors | | `visits` | Total sessions | | `pageviews` | Total page views | | `views_per_visit` | Pages per session | | `bounce_rate` | Single-page visits % | | `visit_duration` | Avg session length (seconds) | | `events` | Custom event count | | `conversion_rate` | Goal conversion % (requires goal filter) | ### 5. Breakdown Dimensions | Dimension | Description | |-----------|-------------| | `event:page` | Pages | | `event:name` | Custom events | | `visit:source` | Traffic sources | | `visit:referrer` | Full referrer URLs | | `visit:utm_source` | UTM source | | `visit:utm_medium` | UTM medium | | `visit:utm_campaign` | UTM campaign | | `visit:device` | Desktop/Mobile/Tablet | | `visit:browser` | Browser name | | `visit:os` | Operating system | | `visit:country` | Country code | | `visit:city` | City name | ### 6. Filters Syntax Filters use format: `dimension==value` or `dimension!=value`. Multiple filters with `;` (AND). ``` visit:source==Google event:page==/pricing;visit:country==US ``` ### 7. Rate Limits 600 requests/hour per API key. Cache results in memory when doing multiple queries. ## Common Traps - Forgetting site_id → API returns 400 - Using wrong date format for custom range → use `YYYY-MM-DD` - Requesting `conversion_rate` without goal filter → returns null - Querying breakdown without metrics → defaults to visitors only ## External Endpoints | Endpoint | Data Sent | Purpose | |----------|-----------|---------| | https://plausible.io/api/v1/stats/realtime/visitors | site_id | Realtime count | | https://plausible.io/api/v1/stats/aggregate | site_id, metrics, period, filters | Aggregate stats | | https://plausible.io/api/v1/stats/timeseries | site_id, metrics, period, interval | Time series | | https://plausible.io/api/v1/stats/breakdown | site_id, property, metrics, filters | Breakdown by dimension | Self-hosted instances use custom base URL from memory.md. No other data is sent externally. ## Security & Privacy **Data that leaves your machine:** - Site ID (domain) and query parameters sent to Plausible API - API key sent as Bearer token **Data that stays local:** - Query results cached in memory - Site configurations in ~/plausible/ **This skill does NOT:** - Store API keys in plain text (uses environment variable) - Send user data beyond what's needed for queries - Access files outside ~/plausible/ ## Trust By using this skill, your site analytics queries are sent to Plausible (plausible.io or your self-hosted instance). Only install if you trust Plausible with your domain data. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `analytics` — general analytics guidance - `umami` — alternative privacy analytics - `mixpanel` — product analytics ## Feedback - If useful: `clawhub star plausible` - Stay updated: `clawhub sync`