How do I install the Umami skill?

Run npx skillmds add modbender/umami in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Umami skill do?

Deploy Umami analytics avoiding data loss, tracking failures, and integration issues. It is listed under DevOps & Infra on SkillMD.

Is Umami safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Umami?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Umami free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

modbender (@modbender) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Umami by modbender — Agent Skill

Name: Umami
Rating: 4.2 (5 reviews)
Author: modbender

File contents

Critical Configuration

HASH_SALT must never change — changing it invalidates all existing data, essentially a reset
SQLite is not supported — despite being Node.js, Umami requires PostgreSQL or MySQL
Database contains everything — all tracking data, config, users; backup only this

Tracking Script Traps

data-website-id must match Umami config exactly — wrong ID = zero data, no error shown
Script blocked by ad blockers — self-host on same domain as site to avoid blocking
Single Page Apps don't auto-track navigation — must call umami.track() on route changes
Script in <head> not <body> — late loading misses initial pageview

SPA Integration

React: call umami.track('pageview') in router effect or navigation handler
Next.js: use @umami/next package — handles app router and pages router
Vue/Nuxt: router afterEach hook with umami.track()
Check window.umami exists before calling — script may load after component mounts

Custom Events

Event names appear verbatim in dashboard — use consistent naming scheme
Properties only searchable via API — not visible in default dashboard
umami.track('event', { key: 'value' }) for properties

Self-Hosting Considerations

Low resources needed — 256MB RAM handles most sites
PostgreSQL needs more resources than Umami itself — plan accordingly
Reverse proxy required for HTTPS — Umami runs HTTP on port 3000
Backup strategy = database backup — no filesystem state to worry about

Multi-Site Setup

One Umami instance handles many sites — add in Dashboard > Settings > Websites
Each site needs unique tracking script — get from Websites settings
Share button available per site — generates public dashboard URL

Troubleshooting

Zero pageviews — check browser Network tab, verify script loads without error
Script 404 — verify CORS headers if cross-domain, or self-host on same domain
Events not appearing — check browser console for umami errors
Dashboard slow — check database performance, PostgreSQL query times

Common Mistakes

Using same website ID for dev and prod — pollutes analytics with test data
Not testing script after deploy — CDN caching or minification can break it
Expecting real-time updates — dashboard has slight delay, not instant

---name: umamidescription: Deploy Umami analytics avoiding data loss, tracking failures, and integration issues.--- ## Critical Configuration - `HASH_SALT` must never change — changing it invalidates all existing data, essentially a reset - SQLite is not supported — despite being Node.js, Umami requires PostgreSQL or MySQL - Database contains everything — all tracking data, config, users; backup only this ## Tracking Script Traps - `data-website-id` must match Umami config exactly — wrong ID = zero data, no error shown - Script blocked by ad blockers — self-host on same domain as site to avoid blocking - Single Page Apps don't auto-track navigation — must call `umami.track()` on route changes - Script in `<head>` not `<body>` — late loading misses initial pageview ## SPA Integration - React: call `umami.track('pageview')` in router effect or navigation handler - Next.js: use `@umami/next` package — handles app router and pages router - Vue/Nuxt: router afterEach hook with `umami.track()` - Check `window.umami` exists before calling — script may load after component mounts ## Custom Events - Event names appear verbatim in dashboard — use consistent naming scheme - Properties only searchable via API — not visible in default dashboard - `umami.track('event', { key: 'value' })` for properties ## Self-Hosting Considerations - Low resources needed — 256MB RAM handles most sites - PostgreSQL needs more resources than Umami itself — plan accordingly - Reverse proxy required for HTTPS — Umami runs HTTP on port 3000 - Backup strategy = database backup — no filesystem state to worry about ## Multi-Site Setup - One Umami instance handles many sites — add in Dashboard > Settings > Websites - Each site needs unique tracking script — get from Websites settings - Share button available per site — generates public dashboard URL ## Troubleshooting - Zero pageviews — check browser Network tab, verify script loads without error - Script 404 — verify CORS headers if cross-domain, or self-host on same domain - Events not appearing — check browser console for `umami` errors - Dashboard slow — check database performance, PostgreSQL query times ## Common Mistakes - Using same website ID for dev and prod — pollutes analytics with test data - Not testing script after deploy — CDN caching or minification can break it - Expecting real-time updates — dashboard has slight delay, not instant

Frequently asked questions