Agent skills (prompts)
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 (like PostHog posthog-setup): quick install (vt.init, page-load identify, vt.capture), Debug View verification, and a resource map of which other slash commands to pull next. 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 provider pattern — server component passes user to client island; vt.init() once, vt.identify() on every render; optional Node SDK for webhooks. |
/vtilt:identify | The three moments to call identify() (page load, login, logout), the SSR / cookie gotcha, and alias() vs resetUser(). |
/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, event-destinations-list / event-destination-get 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, memory-ask vs person-memory-get vs query-run. |
#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 prompts (and not just docs)
The same content is on the public docs site — /docs/browser/identify, /docs/browser/event-tracking, the integration guides. The difference is how the agent consumes it:
- Reading docs through
docs-searchcosts 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 docs-search.
#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.