On this page
Agent skills (prompts)
Last updated
Slash-command prompts the vTilt MCP server exposes — curated walkthroughs and data-model conventions an AI agent can pull on demand so it sets up the SDK and queries data the right way without copy-pasting docs.
vTilt's MCP server exposes more than tools. It also ships a small catalog of prompts — curated markdown bundles the server hands back to your AI client (Cursor / Claude Desktop / Codex / VS Code) when you invoke a slash command. They give the agent the exact context it needs to install the SDK, identify users on every page load, and reason about data the way the platform expects.
Prompts are the MCP equivalent of "agent skills" — short, focused instructions targeted at the model rather than at a human reader. The vTilt catalog mirrors PostHog's posthog:posthog-setup entry point plus its multi-phase basic-integration workflow, scoped to the things our SDK exposes.
#Available prompts
All prompts are surfaced by clients as /vtilt:<slug> slash commands. Type / in Cursor / Claude Desktop / Codex / VS Code to see them once the server is connected.
| Prompt | What it teaches the agent |
|---|---|
/vtilt:setup | Entry point: inline script stub (preferred), vt.init(), page-load identify(), logout-only resetUser(), Debug View verification, and a resource map of other slash commands. Optional stack arg ("nextjs", "vue", …). Returns user + assistant messages. |
/vtilt:setup-workflow | Deep instrumentation (PostHog basic-integration phases): plan events in .vtilt-events.json → implement browser + Node capture → verify → write vtilt-setup-report.md. Use when the user wants full event tracking, not just init. |
/vtilt:setup-nextjs | Next.js App Router — inline script via next/script, server-passed user, page-load identify; SPA logout-only resetUser when using client session hooks. |
/vtilt:identify | Auth-model decision table + copy-paste examples: Next.js server prop vs client session, React useAuth, Vue Pinia, Laravel Blade, Django, signup alias(). |
/vtilt:reverse-proxy | Route SDK traffic through the customer's domain (api_host, /api/e, /api/d, /api/s, /gt/*) to avoid ad blockers — includes Next.js rewrite example. |
/vtilt:event-forwarding | Forward captures to Google Tag, Meta CAPI, or PostHog — dashboard setup, proxied /gt/* mode, consent gating, list_event_destinations / get_event_destination MCP tools. |
/vtilt:conventions | Data-model reference: four-entity mental model, $set / $set_once, $initial_* on persons, $autocapture wire format, VQL recipes. |
/vtilt:analyze | Analysis workflow: read before any analytics question — schema verification loop, first-touch attribution on persons.$initial_* (not event $referrer), anti-patterns. |
/vtilt:ai-memory | AI memory surface: virtual tables, :embed('text') vector search, query_ai_memory vs get_person_memory vs run_query. |
/vtilt:site-knowledge | Site Knowledge surface: crawl→index→serve pipeline, storage families (latest/serving vs append-on-change history vs elements), the dual change signal (content_hash + elements_hash), the five VQL tables, the sixteen tools, and worked queries (change→impact attribution, CRO audit, funnel-gap, funnel diagnosis, ad creative, landing↔ad consistency, semantic enrichment, RAG). |
#When to invoke each prompt
| You're about to ask the agent to... | Invoke this prompt first |
|---|---|
| "Install vTilt in this project." | /vtilt:setup → then /vtilt:setup-workflow if they want deep instrumentation |
| "Instrument checkout / signup / key product events." | /vtilt:setup-workflow |
| "Wire vTilt into my Next.js app." | /vtilt:setup-nextjs (or /vtilt:setup with stack: "nextjs") |
| "Events blocked by ad blocker." | /vtilt:reverse-proxy |
| "Forward to Google Ads / GA4 / Meta." | /vtilt:event-forwarding (after /vtilt:setup-workflow or existing captures) |
| "Why are my users staying anonymous?" | /vtilt:identify |
| "Analyse our traffic." / "Where do our hottest leads come from?" | /vtilt:analyze |
| "Find users by their original referrer / UTM source." | /vtilt:analyze + /vtilt:conventions |
"What did the user click?" / $autocapture element shape | /vtilt:conventions |
| "Write VQL to count distinct users grouped by initial campaign." | /vtilt:conventions + /vtilt:analyze |
| "Find sessions semantically similar to …" | /vtilt:ai-memory |
| "Summarise everything we know about person X." | /vtilt:ai-memory |
| "Why does this page convert badly?" / "What does /pricing say?" | /vtilt:site-knowledge |
| "Did a site change move a metric?" / "What changed on /pricing?" | /vtilt:site-knowledge |
#Why prompts (and not just docs)
The same content is on the public docs site — /docs/getting-started/identify, /docs/getting-started/track-events, the integration guides. The difference is how the agent consumes it:
- Reading docs through
search_docscosts one round-trip per page, returns a snippet, and the agent has to assemble multiple pages itself. - Invoking a prompt costs one round-trip total and hands the agent a single curated, agent-targeted bundle covering the conventions it needs. No assembly, no missing context.
For setup and conventions, the prompt is faster and more reliable. For ad-hoc lookups ("what's the exact config option for the reverse-proxy plugin?"), use search_docs.
#Adding new skills
The prompt registry lives at app/src/shared/mcp/prompts/. To add a new prompt, drop a file in that folder, export it through app/src/shared/mcp/prompts/index.ts, and add a row to the EXPECTED_PROMPTS test in prompts/__tests__/registry.test.ts. The slash-command surfaces as /vtilt:<slug> automatically across every connected client.
Conventions for new prompts:
- One topic per prompt. Two short prompts beat one long one.
- Pure markdown. Handlers are sync and return curated text — they don't call the database or entity actions (that's what tools are for).
- Agent-targeted, not user-targeted. Write in the second person, focus on rules and patterns, lean on tables and short code samples. The audience is the model, not a developer scrolling a tutorial.
#Related
- MCP overview — server URL, supported tools, pinning, rate limits.
- Authentication — create a
vtu_personal API key. - Identify & alias — the human-readable companion to
/vtilt:identify. - Event tracking — the human-readable companion to
/vtilt:setup.