Setup

On first use, read setup.md for integration guidelines. The skill stores configuration in ~/matomo/.

When to Use

User needs to query Matomo analytics, generate reports, track goals, or manage their self-hosted analytics. Agent handles API queries, data analysis, visitor insights, and conversion tracking.

Architecture

Memory lives in ~/matomo/. See memory-template.md for structure.

~/matomo/
├── memory.md         # Sites, credentials ref, preferences
├── reports/          # Saved report templates
└── queries/          # Reusable API query templates

Quick Reference

Core Rules

1. Never Expose Credentials

• Token is stored in system keychain or env var, never in memory files
• Refer to credentials by reference name only
• If user pastes token in chat, warn and suggest secure storage

2. Use Reporting API for Reads

# Base pattern
curl -s "https://{matomo_url}/index.php?module=API&method={method}&idSite={site_id}&period={period}&date={date}&format=json&token_auth={token}"

Common methods:

• VisitsSummary.get — visitors, visits, pageviews
• Actions.getPageUrls — top pages
• Referrers.getWebsites — traffic sources
• Goals.get — conversion data

3. Understand Date Ranges

Special dates: today, yesterday, last7, last30, lastMonth, lastYear

4. Handle Multi-Site Setups

• Always confirm which site before querying
• Store site list in memory.md with idSite mappings
• Default to most-used site if configured

5. Format Data for Humans

• Round percentages to 1 decimal
• Use K/M suffixes for large numbers
• Compare periods when context helps (vs last week/month)
• Highlight significant changes (>10% delta)

6. Respect Rate Limits

• Batch related queries into single date range when possible
• Cache recent results in memory for follow-up questions
• Avoid querying same data repeatedly in conversation

7. Use Segments for Deeper Insights

Segments filter data by visitor attributes. Add &segment= to any query:

# Mobile visitors only
&segment=deviceType==smartphone

# From specific country
&segment=countryCode==US

# Returning visitors who converted
&segment=visitorType==returning;goalConversionsSome>0

# Combine with AND (;) or OR (,)
&segment=browserCode==CH;operatingSystemCode==WIN

Common segment dimensions:

• deviceType — smartphone, tablet, desktop
• browserCode — CH (Chrome), FF (Firefox), SF (Safari)
• countryCode — ISO 2-letter code
• visitorType — new, returning
• referrerType — direct, search, website, campaign

Matomo Traps

• Wrong idSite → querying wrong property, misleading data. Always confirm site first.
• Forgetting token_auth → 403 or empty response. Token required for all non-public methods.
• date vs period mismatch → confusing results. period=range requires date=start,end format.
• Expecting GA terminology → Matomo uses "visits" not "sessions", "actions" not "events". Translate mentally.
• Ignoring segments → missing the real insight. Segments filter data by visitor attributes.

External Endpoints

No other data is sent externally. All requests go to user's own Matomo instance.

Security & Privacy

Data that leaves your machine:

• API queries sent to user's Matomo instance only
• Auth token included in requests (user-controlled)

Data that stays local:

• Site configurations in ~/matomo/
• Report templates
• No data sent to third parties

This skill does NOT:

• Store auth tokens in plain text
• Send data to any service except user's Matomo
• Access files outside ~/matomo/

Related Skills

Install with clawhub install <slug> if user confirms:

• analytics — general analytics patterns
• umami — privacy-focused analytics
• api — REST API integration

Feedback

• If useful: clawhub star matomo
• Stay updated: clawhub sync