Matomo Analytics

Query, analyze, and manage Matomo Analytics with API integration, custom reports, and goal tracking.

Security Scan

The skill's requirements and instructions are consistent with its stated purpose (querying a user's Matomo instance) and it is an instruction-only skill that asks for no unexpected privileges.

Purpose & Capability

Name/description match the instructions: all guidance and examples focus on calling the user's Matomo API and storing only local configuration under ~/matomo/. The skill requests no unrelated binaries, credentials, or config paths.

Instruction Scope

Runtime instructions are narrowly scoped to querying the user's Matomo instance and maintaining local memory under ~/matomo/. The SKILL.md repeatedly warns not to store tokens in plaintext and to reference tokens by name. One operational note: the provided examples use token_auth in query strings (URL) which is standard for Matomo but can expose tokens in logs or intermediary proxies; the document does recommend env var/keychain storage but enforcement is left to the agent and user.

Install Mechanism

No install spec and no code files — this is instruction-only, which minimizes risk because nothing is downloaded or written by an installer.

Credentials

The skill declares no required environment variables or credentials. It suggests (optionally) using MATOMO_TOKEN or a system keychain to store a token, which is proportional to the task of calling a Matomo API.

Persistence & Privilege

always is false, user-invocable is true, and the skill only proposes to write under ~/matomo/. It does not request system-wide changes or access to other skills' configs.

Assessment

This skill appears coherent and does what it says, but keep these precautions in mind before installing or using it: - Confirm the Matomo URL you provide is your own self-hosted instance; the skill will send API requests only to that URL. - Do NOT paste your token into chat. Follow the guidance to store the token in an environment variable (e.g., MATOMO_TOKEN) or the system keychain and reference it by name. - Be aware that including token_auth in a query string (the examples use ?token_auth=...) can expose the token in server logs, proxies, or shell history. Use HTTPS and prefer secure storage; if possible avoid pasting tokens into command lines that might be recorded. - Periodically inspect ~/matomo/ (memory.md, reports) to ensure no credentials were accidentally saved in plaintext. - Because this is instruction-only (no code installed), the agent and you are responsible for following the documented rules; if you need stronger guarantees, prefer a skill that includes vetted code or an installable package from a trusted source. - If you share access with others, rotate the token and limit its scope where Matomo supports that. If you want, I can list the exact places the skill will write (files and directories), or suggest safer command patterns for calling Matomo so tokens are less likely to leak.

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

Topic	File
Setup process	setup.md
Memory template	memory-template.md
API reference	api.md
Report templates	reports.md

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

Period	Date Format	Example
day	YYYY-MM-DD	2025-01-15
week	YYYY-MM-DD	Week containing that date
month	YYYY-MM	2025-01
year	YYYY	2025
range	YYYY-MM-DD,YYYY-MM-DD	2025-01-01,2025-01-31

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

Endpoint	Data Sent	Purpose
{user_matomo_url}/index.php	API method, site ID, date range, auth token	Query analytics data

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