diff --git a/readme.md b/readme.md
index 327d9be..1938707 100644
--- a/readme.md
+++ b/readme.md
@@ -15,6 +15,16 @@ A highly typed, zero-dependency, provider-agnostic analytics library for TypeScr
 - 🔌 [Providers](https://stacksee-analytics.vercel.app/docs/providers)
 - 💡 [Core Concepts](https://stacksee-analytics.vercel.app/docs/core-concepts)
 
+## Agent Skill
+
+Give your coding agent Trakoo-specific integration guidance for typed events, client/server boundaries, providers, and framework setup:
+
+```bash
+npx skills add multiplehats/trakoo --skill trakoo
+```
+
+The source is [`skills/trakoo/SKILL.md`](./skills/trakoo/SKILL.md) and follows the portable Agent Skills format used by skills.sh-compatible agents. See the [Agent Skill docs](https://stacksee-analytics.vercel.app/docs/agent-skill) for agent targeting, global installs, and manual setup.
+
 ## Features
 
 - 🎯 **Type-safe events**: Define your own strongly typed events with full IntelliSense support
diff --git a/skills/trakoo/SKILL.md b/skills/trakoo/SKILL.md
new file mode 100644
index 0000000..c309148
--- /dev/null
+++ b/skills/trakoo/SKILL.md
@@ -0,0 +1,201 @@
+---
+name: trakoo
+description: Use when adding, configuring, or troubleshooting Trakoo analytics in TypeScript applications, including typed or validated events, browser or server tracking, PostHog, OpenPanel, Bento, Pirsch, EmitKit, Visitors, Proxy, provider routing, user identification, or framework integration.
+---
+
+# Trakoo Integration
+
+Trakoo is a typed, provider-agnostic analytics library. Define one runtime event registry, pass it to every analytics factory, and preserve the browser/server boundary.
+
+## Inspect the application first
+
+Detect the package manager, framework, installed `trakoo` version, browser/server entry points, analytics dependencies, and verification commands. Decide whether each event is a browser interaction, an authoritative server outcome, or both.
+
+Use the consuming project's installed Trakoo declarations as the source of truth. Consult the current documentation at https://trakoo.co. If the installed declarations differ, explain the version mismatch instead of silently upgrading or inventing an API.
+
+- Read [references/events-and-validation.md](references/events-and-validation.md) when defining events, adding Zod or another Standard Schema validator, configuring validation failures, or using propertyless events and custom traits.
+- Read [references/providers.md](references/providers.md) when choosing providers, routing events, using Proxy, or building a custom provider.
+- Read only the matching section of [references/frameworks.md](references/frameworks.md) for Next.js, SvelteKit, TanStack Start, Astro, or framework-neutral integration.
+
+## Integration workflow
+
+1. Install `trakoo`, the selected providers' optional SDKs, and a validator only when runtime validation is wanted.
+2. Define and export one shared registry with `defineEvents()`.
+3. Put client and server analytics in separate modules and pass `events: appEvents` to each factory.
+4. Track where the event becomes true: interactions in browser handlers; payments, signups, jobs, and other authoritative outcomes on the server.
+5. Apply identity, validation, and delivery lifecycle rules.
+6. Run the consuming project's formatter, type checker, relevant tests, and production build.
+
+## Shared event registry
+
+Root helpers are environment-neutral and safe to import from shared code:
+
+```ts
+import { defineEvents, noProperties, typed } from "trakoo";
+
+export const appEvents = defineEvents({
+	ctaClicked: {
+		name: "cta_clicked",
+		category: "engagement",
+		properties: typed<{ location: "hero" | "pricing" }>(),
+	},
+	purchaseCompleted: {
+		name: "purchase_completed",
+		category: "conversion",
+		properties: typed<{
+			orderId: string;
+			amount: number;
+			currency: string;
+		}>(),
+	},
+	sessionStarted: {
+		name: "session_started",
+		category: "user",
+		properties: noProperties(),
+	},
+});
+```
+
+Registry keys organize application source; each `name` is the stable value emitted to providers. Use a Standard Schema-compatible validator directly for runtime validation and transformation. See the event reference for a complete Zod example.
+
+## Browser module
+
+```ts
+import { typed } from "trakoo";
+import { createClientAnalytics } from "trakoo/client";
+import { PostHogClientProvider } from "trakoo/providers/client";
+import { appEvents } from "./events";
+
+interface BrowserUserTraits {
+	email: string;
+	plan: "free" | "pro";
+}
+
+export const analytics = createClientAnalytics({
+	events: appEvents,
+	userTraits: typed<BrowserUserTraits>(),
+	providers: [
+		new PostHogClientProvider({
+			// Browser-public PostHog project key (phc_...), never a personal API key.
+			token: import.meta.env.VITE_POSTHOG_PROJECT_KEY,
+		}),
+	],
+});
+
+const analyticsReady = analytics.initialize();
+
+export async function identifyUser(userId: string, traits: BrowserUserTraits) {
+	await analyticsReady;
+	analytics.identify(userId, traits);
+}
+```
+
+Every factory call creates a fresh, registry-bound instance owned by the application. Retain its initialization promise and await readiness before the first `identify()` or identity-sensitive event because some providers ignore identity calls before their SDK is ready. Login, signup, and restored-session/bootstrap flows must await the identity helper; call `analytics.reset()` on logout.
+
+At restored-session bootstrap, identify before enabling identity-sensitive events:
+
+```ts
+const restoredSession = await restoreSession();
+
+if (restoredSession.user) {
+	await identifyUser(restoredSession.user.id, {
+		email: restoredSession.user.email,
+		plan: restoredSession.user.plan,
+	});
+}
+
+// Enable identity-sensitive events only after this bootstrap completes.
+```
+
+`track()` returns `Promise<void>`. Await work whose completion matters; use `void analytics.track(...)` for explicitly non-critical browser analytics rather than blocking navigation.
+
+## Server module and critical event
+
+```ts
+import { typed } from "trakoo";
+import { createServerAnalytics } from "trakoo/server";
+import { PostHogServerProvider } from "trakoo/providers/server";
+import { appEvents } from "./events";
+
+interface ServerUserTraits {
+	plan: "free" | "pro";
+}
+
+function createRequestAnalytics() {
+	return createServerAnalytics({
+		events: appEvents,
+		userTraits: typed<ServerUserTraits>(),
+		providers: [
+			new PostHogServerProvider({
+				// PostHog project capture key (phc_...), not a personal API key.
+				apiKey: process.env.POSTHOG_PROJECT_KEY!,
+			}),
+		],
+	});
+}
+
+export async function trackPurchase(input: {
+	orderId: string;
+	amount: number;
+	currency: string;
+	userId: string;
+	email: string;
+	plan: "free" | "pro";
+}) {
+	const analytics = createRequestAnalytics();
+	try {
+		await analytics.track(
+			"purchase_completed",
+			{
+				orderId: input.orderId,
+				amount: input.amount,
+				currency: input.currency,
+			},
+			{
+				userId: input.userId,
+				user: {
+					email: input.email,
+					traits: { plan: input.plan },
+				},
+			},
+		);
+	} finally {
+		await analytics.shutdown();
+	}
+}
+```
+
+Server analytics is stateless across users: pass user context with each event and await critical events. For a fresh request-scoped provider/analytics pair, shut down that same pair in `finally`. A reusable instance shuts down only at application or process teardown. Some providers flush buffered events during shutdown; others only clear state. Inspect the selected provider's installed implementation before choosing the lifecycle. Use the platform's `waitUntil` only for explicitly non-critical work.
+
+## Imports and ownership
+
+| Concern | Correct pattern |
+|---|---|
+| Event helpers and shared types | `trakoo` (environment-neutral) |
+| Browser factory | `trakoo/client` |
+| Server factory | `trakoo/server` |
+| Browser providers | `trakoo/providers/client` |
+| Server providers | `trakoo/providers/server` |
+| Browser identity | Await initialization before first identity transition; reset on logout |
+| Server identity | Pass request user context on every call |
+| Critical server delivery | Await `track()`; shutdown follows provider behavior and instance ownership |
+
+Never import a server provider, secret, or unprefixed server environment variable into browser code. Do not use a nonexistent `trakoo/providers` aggregate.
+
+## Verification
+
+Run the consuming project's type checker and narrowest relevant tests. Run its production build when client/server bundling or environment variables changed. Recheck installed declarations when an import, option, event property, or provider constructor fails.
+
+**Maintainer release gate:** This skill must not be published until PR #32's migrated implementation lands and representative consumer fixtures are compiled and typechecked against the real built package, not fabricated declarations. Fixtures must cover root helpers and registry; direct Zod transformation and distinct input/output types; Valibot or ArkType; client and server factories sharing `events`; browser identify traits and nested server traits; a propertyless client call; a propertyless server-options call; and validation `"drop"` and `"throw"`.
+
+## Common mistakes
+
+- Defining calls before the shared runtime registry.
+- Forgetting `events: appEvents` in either factory.
+- Repeating event generics instead of allowing registry inference.
+- Using `typed<T>()` when untrusted runtime input needs a validator.
+- Sharing stateful browser identity logic with stateless server analytics.
+- Sending all methods and events to providers with different requirements instead of routing them.
+- Installing every optional SDK instead of only the selected provider and validator packages.
+- Calling `identify()` before client provider initialization or forgetting logout reset.
+- Pairing a reusable server instance with per-event shutdown.
diff --git a/skills/trakoo/references/events-and-validation.md b/skills/trakoo/references/events-and-validation.md
new file mode 100644
index 0000000..c3b05b3
--- /dev/null
+++ b/skills/trakoo/references/events-and-validation.md
@@ -0,0 +1,167 @@
+# Events and Validation Reference
+
+Use one shared runtime registry for browser and server analytics. The object keys organize source code; each definition's `name` is the emitted event name accepted by `track()` and sent to providers.
+
+## Define events
+
+Install only the chosen validator when runtime validation is needed. Trakoo does not require one:
+
+```bash
+npm install trakoo zod
+```
+
+```ts
+import { defineEvents, noProperties, typed } from "trakoo";
+import { z } from "zod";
+
+export const appEvents = defineEvents({
+	buttonClicked: {
+		name: "button_clicked",
+		category: "engagement",
+		properties: typed<{
+			buttonId: string;
+			location?: "hero" | "pricing";
+		}>(),
+	},
+	purchaseCompleted: {
+		name: "purchase_completed",
+		category: "conversion",
+		properties: z.object({
+			orderId: z.string(),
+			amount: z.coerce.number().positive(),
+			currency: z.string().length(3),
+		}),
+	},
+	sessionStarted: {
+		name: "session_started",
+		category: "user",
+		properties: noProperties(),
+	},
+});
+```
+
+The three property modes are:
+
+| Definition | Compile-time type | Runtime behavior |
+|---|---|---|
+| `typed<T>()` | Input and output are `T` | No runtime validation |
+| Standard Schema validator | Inferred validator input and output | Validates and normalizes before routing |
+| `noProperties()` | No properties argument | Normalizes omitted input to an empty provider object |
+
+Recent compatible Zod, Valibot, ArkType, and other Standard Schema implementations work directly with no Trakoo adapter. Install only the chosen validator; do not add validator-specific Trakoo configuration. Trakoo itself remains validator-optional.
+
+`typed<T>()` is for trusted, type-checked application values. It does not validate JavaScript, JSON, form data, or other untrusted input at runtime. Use a schema when that boundary needs validation. Duplicate emitted names are a registry initialization error.
+
+## Schema input and provider output
+
+A schema can accept one input shape and return a normalized provider output. In the example, Zod coercion accepts a numeric string and providers receive a number:
+
+```ts
+await analytics.track("purchase_completed", {
+	orderId: "order_456",
+	amount: "19.95",
+	currency: "EUR",
+});
+```
+
+Trakoo awaits the Standard Schema result, rejects invalid or non-object output under the configured policy, and routes the successful output—not the original input—to every selected provider. Transformations, coercion, stripping, and sanitization therefore happen once before routing.
+
+## Propertyless calls
+
+Client calls omit argument two:
+
+```ts
+await analytics.track("session_started");
+```
+
+For server analytics, server options go directly in argument two:
+
+```ts
+await serverAnalytics.track(
+	"session_started",
+	{
+		userId: "user_123",
+		user: {
+			email: "ada@example.com",
+			traits: { plan: "pro" },
+		},
+	},
+);
+```
+
+`userId` belongs directly in server track options. Identity fields such as `email` stay top-level in `user`, while application traits belong under `user.traits`. Do not pass a raw custom-traits object as `user`.
+
+Never pass an `undefined` properties placeholder. A client second argument, a server `undefined` placeholder, or properties supplied through untyped JavaScript is `invalid_properties` under the validation-failure policy.
+
+## Factory inference and user traits
+
+Both factories require the same registry value and infer the event map:
+
+```ts
+import { typed } from "trakoo";
+import { createClientAnalytics } from "trakoo/client";
+import { createServerAnalytics } from "trakoo/server";
+import { appEvents } from "./events";
+
+interface BrowserUserTraits {
+	email: string;
+	plan: "free" | "pro";
+}
+
+interface ServerUserTraits {
+	plan: "free" | "pro";
+}
+
+const analytics = createClientAnalytics({
+	events: appEvents,
+	userTraits: typed<BrowserUserTraits>(),
+	providers: clientProviders,
+});
+
+const serverAnalytics = createServerAnalytics({
+	events: appEvents,
+	userTraits: typed<ServerUserTraits>(),
+	providers: serverProviders,
+});
+```
+
+Use separate browser and server trait contracts. The browser marker must declare every object-literal field sent to `identify()`, including canonical identity values such as `email` and application values such as `plan`. The server marker describes only the custom values nested under `user.traits`; keep identity fields such as `email` at the top level of `user`. The optional `userTraits` marker is type-only and is neither validated nor sent to providers as configuration.
+
+## Validation timing
+
+Every `track()` variant returns `Promise<void>`. Validation finishes before provider routing begins, so a failed event is never partially delivered. Successful normalized output is shared by every selected provider.
+
+Standard Schema validation may be asynchronous. Concurrent calls are not guaranteed to reach providers in call order; await calls sequentially when order matters. Provider delivery remains parallel and isolated after validation.
+
+## Failure policy and security
+
+`onFailure` defaults to `"drop"` on both client and server. Invalid events resolve without delivery so analytics validation does not fail a successful business operation. Strict tests or workflows can opt into rejection:
+
+```ts
+const analytics = createServerAnalytics({
+	events: appEvents,
+	providers: serverProviders,
+	validation: {
+		onFailure: "throw",
+		onError(error) {
+			reportValidationFailure({
+				code: error.code,
+				eventName: error.eventName,
+				paths: error.issues.map((issue) => issue.path),
+			});
+		},
+	},
+});
+```
+
+`AnalyticsValidationError` reports the emitted event name, normalized issue information, and one of `unknown_event`, `invalid_properties`, `validator_failure`, or `invalid_output`. It never retains the submitted properties object or validator exception. Its normalized issues may include validator-provided messages, and those messages can contain application values.
+
+When configured, `onError` receives the error exactly once. A throwing or rejected callback cannot change the selected drop/throw policy. Select and sanitize fields before forwarding a validation failure to application observability; the example sends only the code, event name, and normalized paths rather than the whole error.
+
+Default debug logging exposes only sanitized metadata such as the code, event name, and normalized paths. It never logs raw messages or input.
+
+This validation policy does not redefine provider-delivery or initialization errors. Those retain their existing behavior, so `track()` can still reject for reasons outside event validation.
+
+## Verification
+
+Run the application's type checker and production build. Add runtime tests for schema success, transformation, and rejection. Confirm invalid events do not reach any provider and normalized output reaches every routed provider.
diff --git a/skills/trakoo/references/frameworks.md b/skills/trakoo/references/frameworks.md
new file mode 100644
index 0000000..1eed199
--- /dev/null
+++ b/skills/trakoo/references/frameworks.md
@@ -0,0 +1,210 @@
+# Framework Integration Reference
+
+Read only the section matching the consuming project. Framework APIs evolve; confirm routing hooks and server boundaries against the installed framework version before editing.
+
+## Detection
+
+| Signal | Framework |
+|---|---|
+| `next.config.*` plus `next` dependency | Next.js |
+| `svelte.config.*` plus `@sveltejs/kit` | SvelteKit |
+| `@tanstack/react-start` and its Vite/Rsbuild plugin | TanStack Start |
+| `astro.config.*` plus `astro` | Astro |
+| Browser entry plus server/API entry without the above | Framework-neutral TypeScript |
+
+## Shared rules
+
+- Keep `events.ts` environment-neutral and import only root event helpers from `trakoo`.
+- Import the same registry value in client and server modules:
+
+```ts
+import { appEvents } from "./events";
+
+const analytics = createClientAnalytics({
+	events: appEvents,
+	providers: clientProviders,
+});
+
+const serverAnalytics = createServerAnalytics({
+	events: appEvents,
+	providers: serverProviders,
+});
+```
+
+- Put `createClientAnalytics` and browser providers in a browser-only module.
+- Put `createServerAnalytics`, server providers, and secrets in a server-only module.
+- Track a business event where it becomes authoritative, not merely where navigation happens.
+- Use the framework's public-variable convention only for browser-safe provider identifiers.
+
+## Next.js
+
+Use a client component for browser initialization, identity lifecycle, and navigation effects. Import `appEvents` and pass it as the factory's `events` option. Browser values use `NEXT_PUBLIC_*`; unprefixed values remain server-only. Put critical tracking in route handlers, server actions, or other server-only modules and pass the same registry to the server factory. Await critical events. Call `shutdown()` in the request's `finally` block only when that request created and owns a fresh provider/analytics pair. A reusable module singleton stays alive across requests and shuts down only at application or process teardown. Verify with `next build` because it catches accidental server imports in client bundles.
+
+## SvelteKit
+
+Initialize browser analytics only in browser-executed code such as `onMount`; import `appEvents` and pass it to the client factory. Keep server providers in `+page.server.ts`, `+server.ts`, hooks, or other server-only modules and pass the same registry to the server factory. Use `$env/static/public` or `$env/dynamic/public` for client-safe values and private `$env/*/private` modules only on the server. Use the installed SvelteKit navigation API for page views and avoid double-counting the initial navigation.
+
+## TanStack Start
+
+Enforce the runtime boundary with filenames such as `analytics.client.ts` and `analytics.server.ts`. As an additional or alternative guard, put the matching side-effect marker at the top of each module:
+
+```ts
+// analytics.client.ts
+import "@tanstack/react-start/client-only";
+```
+
+```ts
+// analytics.server.ts
+import "@tanstack/react-start/server-only";
+```
+
+Place browser analytics in client-executed application code and server analytics inside `createServerFn` handlers or server routes. Import the shared `appEvents` registry on both sides and pass `events: appEvents` to each factory. Keep `.server.ts` helpers imported only inside a server-function handler or another compiler-recognized server callback:
+
+```ts
+import { createServerFn } from "@tanstack/react-start";
+import { z } from "zod";
+
+const trackPurchaseInput = z.object({
+	orderId: z.string().min(1),
+});
+
+export const trackPurchase = createServerFn({ method: "POST" })
+	.validator(trackPurchaseInput)
+	.handler(async ({ data }) => {
+		const { createRequestAnalytics } = await import("./analytics.server");
+		const { requireUser } = await import("./auth.server");
+		const { purchases } = await import("./purchases.server");
+
+		const user = await requireUser();
+		const order = await purchases.confirmAndLoad({
+			orderId: data.orderId,
+			userId: user.id,
+		});
+		const projectKey = process.env.POSTHOG_PROJECT_KEY!;
+		const analytics = createRequestAnalytics(projectKey);
+
+		try {
+			await analytics.track(
+				"purchase_completed",
+				{
+					orderId: order.id,
+					amount: order.totalAmount,
+					currency: order.currency,
+				},
+				{
+					userId: user.id,
+					user: {
+						email: user.email,
+						traits: { plan: order.plan },
+					},
+				},
+			);
+		} finally {
+			await analytics.shutdown();
+		}
+	});
+```
+
+`requireUser` and `purchases.confirmAndLoad` are seams supplied by the consuming application. Authenticate inside the server function, then use the lookup ID plus the authenticated user ID to load and confirm the authoritative purchase. Derive event properties and identity from that server-owned result and session; never accept event properties, user identity, or traits from the browser for an authoritative event.
+
+With Vite, expose only browser-safe identifiers through `VITE_*`. Read unprefixed deployment environment values inside `.handler()`, middleware `.server()`, server-route handlers, or other per-request callbacks. Edge runtimes may expose deployment bindings differently from Node's `process.env`; use the installed adapter's per-request binding API.
+
+Choose one page-view owner. The following router-owned approach requires the client `PostHogClientProvider` to use `capture_pageview: false` before the manual initial/navigation stream. If provider auto-capture owns page views, omit this stream. Export the retained client initialization promise as `analyticsReady`, and await it before emitting or recording the initial URL. Normalize initial and router URLs identically so relative and absolute hrefs deduplicate.
+
+The route-mounted tracker is isomorphic because a root route participates in SSR. It must not be named `*.client.tsx` or carry the client-only side-effect marker. Instead, keep `analytics.client.ts` import-protected and put its dynamic import plus all browser-only setup behind TanStack Start's compiler-recognized `createClientOnlyFn` boundary:
+
+```tsx
+// PageViewTracker.tsx — isomorphic and safe to import from an SSR root route
+import { createClientOnlyFn } from "@tanstack/react-start";
+import { useRouter } from "@tanstack/react-router";
+import { useEffect } from "react";
+
+const startPageViews = createClientOnlyFn((router: ReturnType<typeof useRouter>) => {
+	let lastPageUrl: string | undefined;
+	let unsubscribe: (() => void) | undefined;
+	let disposed = false;
+
+	async function start() {
+		const { analytics, analyticsReady } = await import("./analytics.client");
+
+		function emitPageView(href: string) {
+			const parsed = new URL(href, window.location.origin);
+			parsed.hash = "";
+			const url = parsed.href;
+
+			if (url === lastPageUrl) return;
+			lastPageUrl = url;
+
+			analytics.pageView({
+				path: `${parsed.pathname}${parsed.search}`,
+				url,
+			});
+		}
+
+		await analyticsReady;
+		if (disposed) return;
+
+		emitPageView(window.location.href);
+		unsubscribe = router.subscribe("onResolved", ({ toLocation }) => {
+			emitPageView(toLocation.href);
+		});
+	}
+
+	void start();
+
+	return () => {
+		disposed = true;
+		unsubscribe?.();
+	};
+});
+
+export function PageViewTracker() {
+	const router = useRouter();
+	useEffect(() => startPageViews(router), [router]);
+	return null;
+}
+```
+
+Mount that isomorphic component once in the long-lived root route:
+
+```tsx
+// routes/__root.tsx
+import { Outlet, createRootRoute } from "@tanstack/react-router";
+import { PageViewTracker } from "./PageViewTracker";
+
+export const Route = createRootRoute({ component: RootComponent });
+
+function RootComponent() {
+	return (
+		<>
+			<Outlet />
+			<PageViewTracker />
+		</>
+	);
+}
+```
+
+The effect cleanup marks a pending initialization as disposed before it can install the subscription, and calls `unsubscribe()` after installation. Apply the same one-owner decision to page-leave tracking; disable provider auto-capture before manually emitting page leaves. Confirm the consuming project's installed TanStack Start version exports `createClientOnlyFn` with this signature, then run its type checker and production build; those checks catch unsupported APIs and import-protection violations.
+
+## Astro
+
+Initialize client analytics in a processed `<script>` or a hydrated UI-framework island, importing the shared registry and passing `events: appEvents`. Use the retained initialization promise, exported as `analyticsReady` from the browser analytics module. Use `PUBLIC_*`/`astro:env/client` only for browser-safe values and `astro:env/server` for server provider secrets. Put critical tracking in endpoints, actions, middleware, or other server-rendered code and pass the same registry to the server factory. With Astro's client router, listen for completed navigations and await readiness before each page view:
+
+```ts
+import { analytics, analyticsReady } from "./analytics.client";
+
+document.addEventListener("astro:page-load", async () => {
+	await analyticsReady;
+	analytics.pageView({ path: window.location.pathname, url: window.location.href });
+});
+```
+
+Ensure a persistent script or guarded setup registers the listener once so client navigation does not multiply page views.
+
+## Framework-neutral TypeScript
+
+Create one browser-owned instance from the application's browser entry and one server factory or request-scoped instance from server code. Import the same `appEvents` value and pass it to every factory. A short-lived request may call `shutdown()` in `finally` only for the fresh provider/analytics pair it created and owns; a reusable module singleton shuts down only at application or process teardown. Use the build tool's public environment prefix (`VITE_*` for Vite by default). Subscribe to the chosen router's completed-navigation event rather than click events, because redirects and history navigation also change pages.
+
+## Verification
+
+Run the framework's typecheck and production build. Confirm browser output contains no server provider import or secret name. Exercise initial load, client navigation, login, logout, and one critical server event; ensure each expected event is emitted once.
diff --git a/skills/trakoo/references/providers.md b/skills/trakoo/references/providers.md
new file mode 100644
index 0000000..607211c
--- /dev/null
+++ b/skills/trakoo/references/providers.md
@@ -0,0 +1,191 @@
+# Provider Reference
+
+Read the selected provider's installed constructor types and official Trakoo provider page before generating final code. Install only dependencies required by the selected side.
+
+Import the shared runtime registry into every analytics module and pass `events: appEvents` to each client or server factory. Provider routing selects delivery targets; it does not replace registry validation.
+
+## Capability and dependency matrix
+
+| Provider | Browser | Server | Extra dependency | Use and constraints |
+|---|---:|---:|---|---|
+| PostHog | Yes | Yes | Browser: `posthog-js`; server: `posthog-node` | General product analytics. Keep the server key out of browser code. |
+| OpenPanel | Yes | Yes | Browser: `@openpanel/web`; server: `@openpanel/sdk` | Product and web analytics across both runtimes. |
+| Bento | Yes | Yes | Browser: none; server: `@bentonow/bento-node-sdk` | Browser page views may be anonymous. Email is required for identification, identified lifecycle events, and server events. |
+| Pirsch | Yes | Yes | None | Privacy-first analytics. Server hits require the visitor IP address and User-Agent request context. |
+| EmitKit | No | Yes | `@emitkit/js` when required by the installed version | Server-side event notifications; verify its current constructor from installed types. |
+| Visitors | Yes | No | None | Privacy-friendly web analytics. `identify()` does not itself require persistence; persistence enables cross-session tracking and revenue attribution. Page views are automatic. |
+| Proxy | Yes | Ingestion helpers | None | First-party batching from `ProxyProvider` to `createProxyHandler` or `ingestProxyEvents`. It is transport, not an analytics vendor. |
+
+## Choose by event semantics
+
+- Use browser providers for interaction, navigation, and other non-critical UI events.
+- Use server providers for payments, confirmed signups, jobs, and events that must survive blockers or navigation.
+- Pair providers when one handles anonymous measurement and another handles identified lifecycle automation.
+- Use Proxy when keys must stay server-side, request context is required, or first-party delivery is important.
+
+## Routing
+
+Each provider entry can be a provider instance or a routing object:
+
+```ts
+providers: [
+	new PostHogClientProvider({ token: publicPosthogKey }),
+	{
+		provider: new BentoClientProvider({ siteUuid: publicBentoSiteUuid }),
+		methods: ["identify", "track"],
+		eventPatterns: ["user_*", "subscription_*"],
+	},
+]
+```
+
+Use one method selector: `methods` or `exclude`. Use one event selector: `events`, `excludeEvents`, or `eventPatterns`. If mutually exclusive options are combined, Trakoo warns and applies precedence; remove the ambiguity instead of relying on precedence.
+
+## Provider constraints
+
+### PostHog
+
+Both PostHog constructors take a project capture credential (project API key), normally shaped like `phc_project_key`. A `phx_` value is a personal API key; never use or recommend a personal API key for event capture.
+
+Map the browser-public project key to client `token` and the deployment's server value to server `apiKey`:
+
+```ts
+import { PostHogClientProvider } from "trakoo/providers/client";
+import { PostHogServerProvider } from "trakoo/providers/server";
+
+const clientProvider = new PostHogClientProvider({
+	token: import.meta.env.VITE_POSTHOG_PROJECT_KEY,
+	capture_pageview: false,
+	capture_pageleave: false,
+});
+
+const serverProvider = new PostHogServerProvider({
+	apiKey: process.env.POSTHOG_PROJECT_KEY!,
+});
+```
+
+`VITE_POSTHOG_PROJECT_KEY` is intentionally browser-public. `POSTHOG_PROJECT_KEY` stays in server configuration even though both values identify the project. Do not expose unrelated server settings or personal credentials through the public prefix.
+
+Choose one page-view owner. When the application router owns initial and navigation views, set `capture_pageview: false` before manually emitting either stream. When PostHog auto-capture owns page views, do not add a manual initial view or router subscription. For page-leave tracking, use the same one-owner rule: set `capture_pageleave: false` when the application emits page leaves itself, or leave manual tracking out when PostHog owns it.
+
+For a router-owned stream, normalize every initial and navigation URL with the same function before deduplicating. Resolve relative router hrefs against `window.location.origin`, then compare the resulting absolute URL:
+
+```ts
+function normalizePageUrl(href: string): string {
+	const url = new URL(href, window.location.origin);
+	url.hash = "";
+	return url.href;
+}
+```
+
+### Bento
+
+Bento's browser integration can record anonymous page views. A valid email is required for `identify()`, identified lifecycle events, and server events; it is not required for every browser page view. Route other anonymous traffic according to the installed provider's supported methods.
+
+The current server constructor is `BentoServerProvider({ siteUuid, authentication: { publishableKey, secretKey } })`. All three values are server-only:
+
+```ts
+import { createServerAnalytics } from "trakoo/server";
+import { BentoServerProvider } from "trakoo/providers/server";
+import { appEvents } from "./events";
+
+export async function createBentoAnalytics() {
+	const provider = new BentoServerProvider({
+		siteUuid: process.env.BENTO_SITE_UUID!,
+		authentication: {
+			publishableKey: process.env.BENTO_PUBLISHABLE_KEY!,
+			secretKey: process.env.BENTO_SECRET_KEY!,
+		},
+	});
+
+	await provider.initialize();
+
+	return createServerAnalytics({
+		events: appEvents,
+		providers: [provider],
+	});
+}
+```
+
+Keep `BENTO_SITE_UUID`, `BENTO_PUBLISHABLE_KEY`, and `BENTO_SECRET_KEY` server-only; never expose them through client-prefixed environment variables.
+
+Explicitly await `BentoServerProvider.initialize()` before the first event. For request-scoped ownership, create a fresh provider and analytics pair, use it for that request, and shut down that same pair in `finally`:
+
+```ts
+const analytics = await createBentoAnalytics();
+
+try {
+	await analytics.track("signup_completed", properties, {
+		userId,
+		user: { email },
+	});
+} finally {
+	await analytics.shutdown();
+}
+```
+
+For a long-lived module instance, call `shutdown()` only at application or process teardown. Do not call `shutdown()` after each event on a reusable module singleton. Bento `shutdown()` clears provider state; it is not a buffered flush.
+
+### EmitKit
+
+EmitKit is server-only. Construct `EmitKitServerProvider` with the server-only `EMITKIT_API_KEY`, explicitly await its initialization, and only then pass it to `createServerAnalytics()`:
+
+```ts
+import { createServerAnalytics } from "trakoo/server";
+import { EmitKitServerProvider } from "trakoo/providers/server";
+import { appEvents } from "./events";
+
+export async function createEmitKitAnalytics() {
+	const provider = new EmitKitServerProvider({
+		apiKey: process.env.EMITKIT_API_KEY!,
+	});
+
+	await provider.initialize();
+
+	return createServerAnalytics({
+		events: appEvents,
+		providers: [provider],
+	});
+}
+```
+
+`EMITKIT_API_KEY` is server-only. Never expose it through client-prefixed environment variables or import this module into browser code. EmitKit dynamically imports its SDK; early calls can be skipped until initialization completes, so awaiting `provider.initialize()` before the factory is required.
+
+For request-scoped ownership, create a fresh provider and analytics pair and shut down that same pair in `finally`. For a reusable instance, call `shutdown()` only at application or process teardown. EmitKit sends immediately rather than buffering; its shutdown clears the provider's client state.
+
+### Pirsch
+
+No extra package is required. The current client constructor is `PirschClientProvider({ identificationCode, hostname? })`:
+
+```ts
+import { PirschClientProvider } from "trakoo/providers/client";
+
+const provider = new PirschClientProvider({
+	identificationCode: import.meta.env.VITE_PIRSCH_IDENTIFICATION_CODE,
+});
+```
+
+`VITE_PIRSCH_IDENTIFICATION_CODE` and an optional hostname override are browser-public configuration, not secrets. Pirsch's `pa.js` script records the initial page load and programmatic History API URL changes by default. The current provider's `pageView()` is therefore a no-op, and `methods: ["pageView"]` does not emit SPA navigation hits. Do not add a duplicate router hook when `pa.js` can observe the navigation. Verify one initial hit and one SPA navigation hit in the browser Network panel.
+
+`window.pirsch(name, options)` is the custom-event API, not a programmatic page-view API. Do not redeclare `Window.pirsch` in consuming code; importing `PirschClientProvider` already supplies its installed type. If a router does not produce observable History API changes, use a page-view API explicitly supported by the installed Pirsch version or route navigation page views elsewhere.
+
+Even when the selected configuration is browser-only, state the server delivery constraint: Pirsch server hits require the visitor's original IP address and User-Agent; without both, they cannot be attributed and are skipped. Proxy browser events through a server endpoint when that request context is needed.
+
+### Visitors
+
+Visitors is browser-only. `pageView()` does not send a duplicate because its script tracks page loads automatically. Non-scalar custom properties are dropped. `identify()` itself does not require persistence. Enable persistence when the application needs cross-session tracking or revenue attribution, and apply the appropriate consent rules whenever identification or persistence is used.
+
+### Proxy
+
+Import `ProxyProvider` from `trakoo/providers/client`; import `createProxyHandler` or `ingestProxyEvents` from `trakoo/providers/server`. Treat its endpoint as an application endpoint accepting untrusted JSON, not as a trusted internal channel. Require a same-origin `Origin` check for first-party browser delivery. If cross-origin delivery is intentional, enforce an explicit CORS allowlist; when ingestion is user-scoped, require and verify an authenticated session as well.
+
+Enforce a request body byte limit and decoded batch-size limits before ingestion, and rate limit the endpoint by an application-appropriate identity. Configure the deployment's trusted proxies before trusting `Forwarded`, `X-Forwarded-For`, or similar forwarded IP headers; otherwise use the directly observed peer address and do not treat forwarded values as visitor context.
+
+Pass the same `appEvents` registry to the browser analytics factory and the ingesting server analytics factory. The server registry must still reject or drop unknown names and validate schema-backed properties before provider routing. That runtime registry validation is necessary but not sufficient: it proves event shape, not caller authorization or truth. Never trust client-proxied `userId`, traits, or events as authoritative. Derive identity and critical business events from the authenticated session and server-owned state, and emit authoritative events at the server operation that confirms them.
+
+## Custom providers
+
+Extend `BaseAnalyticsProvider` from the environment-specific provider export and implement the `AnalyticsProvider` contract. Preserve Trakoo's event `action`, properties, and context; do not put vendor-specific behavior into shared event definitions.
+
+## Verification
+
+Typecheck constructor options against the installed provider types. Exercise one representative event per routing branch and confirm excluded events or methods do not reach that provider. Verify an initial page load and one completed SPA navigation independently. For server providers, exercise two sequential lifecycle events and confirm initialization and shutdown match instance ownership. For buffered server SDKs, verify the handler flushes before exit.
diff --git a/test/agent-skill.test.ts b/test/agent-skill.test.ts
new file mode 100644
index 0000000..83ea5ac
--- /dev/null
+++ b/test/agent-skill.test.ts
@@ -0,0 +1,630 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const read = (relativePath: string) =>
+	readFileSync(
+		fileURLToPath(new URL(`../${relativePath}`, import.meta.url)),
+		"utf8",
+	);
+
+const skillFiles = [
+	"skills/trakoo/SKILL.md",
+	"skills/trakoo/references/events-and-validation.md",
+	"skills/trakoo/references/providers.md",
+	"skills/trakoo/references/frameworks.md",
+];
+
+const codeBlocks = (content: string) =>
+	[...content.matchAll(/```(?:ts|tsx|typescript)\n([\s\S]*?)```/g)]
+		.map((match) => match[1])
+		.join("\n");
+
+describe("Trakoo Agent Skill", () => {
+	it("has discoverable metadata, v1 references, and current documentation", () => {
+		const skill = read("skills/trakoo/SKILL.md");
+
+		expect(skill).toMatch(/^---\nname: trakoo\ndescription: Use when /);
+		expect(skill).toContain("https://trakoo.co");
+		expect(skill).toContain("references/events-and-validation.md");
+		expect(skill).toContain("references/providers.md");
+		expect(skill).toContain("references/frameworks.md");
+	});
+
+	it("teaches the runtime registry and all three property modes", () => {
+		const events = read("skills/trakoo/references/events-and-validation.md");
+
+		expect(events).toContain(
+			'import { defineEvents, noProperties, typed } from "trakoo"',
+		);
+		expect(events).toContain("export const appEvents = defineEvents({");
+		expect(events).toContain("properties: typed<");
+		expect(events).toContain("properties: noProperties()");
+		expect(events).toMatch(
+			/properties: z\.object\(\{[\s\S]*z\.coerce\.number\(\)/,
+		);
+	});
+
+	it("documents direct Standard Schema validator compatibility", () => {
+		const events = read("skills/trakoo/references/events-and-validation.md");
+
+		for (const validator of ["Zod", "Valibot", "ArkType", "Standard Schema"]) {
+			expect(events).toContain(validator);
+		}
+		expect(events).toMatch(/no Trakoo adapter/i);
+		expect(events).toMatch(/install only[^\n]*chosen validator/i);
+		expect(events).toMatch(/input[\s\S]*provider output[\s\S]*coerc/i);
+	});
+
+	it("binds both factories to the shared registry without event generics", () => {
+		const skill = read("skills/trakoo/SKILL.md");
+		const registry = skill.match(
+			/## Shared event registry[\s\S]*?```ts\n([\s\S]*?)```/,
+		)?.[1];
+		const browser = skill.match(
+			/## Browser module\n\n```ts\n([\s\S]*?)```/,
+		)?.[1];
+		const server = skill.match(
+			/## Server module and critical event\n\n```ts\n([\s\S]*?)```/,
+		)?.[1];
+
+		expect(registry).toContain("purchaseCompleted");
+		expect(registry).toContain('name: "purchase_completed"');
+		expect(browser).toMatch(/import \{ appEvents \} from "\.\/events"/);
+		expect(browser).toMatch(/createClientAnalytics\(\{\s*events: appEvents,/);
+		expect(browser).not.toMatch(/createClientAnalytics</);
+		expect(browser).toContain("userTraits: typed<BrowserUserTraits>()");
+		expect(server).toMatch(/import \{ appEvents \} from "\.\/events"/);
+		expect(server).toMatch(/createServerAnalytics\(\{\s*events: appEvents,/);
+		expect(server).not.toMatch(/createServerAnalytics</);
+	});
+
+	it("documents propertyless client and server call shapes", () => {
+		const events = read("skills/trakoo/references/events-and-validation.md");
+
+		expect(events).toContain('analytics.track("session_started")');
+		expect(events).toMatch(
+			/serverAnalytics\.track\(\s*"session_started",\s*\{\s*userId: "user_123",/,
+		);
+		expect(events).toMatch(/server options go directly in argument two/i);
+		expect(events).toMatch(/never pass an `undefined` properties placeholder/i);
+	});
+
+	it("documents asynchronous validation and delivery ordering", () => {
+		const events = read("skills/trakoo/references/events-and-validation.md");
+
+		expect(events).toContain("`Promise<void>`");
+		expect(events).toMatch(/validation finishes before provider routing/i);
+		expect(events).toMatch(/concurrent[\s\S]*not guaranteed[\s\S]*call order/i);
+	});
+
+	it("documents validation defaults and sanitized reporting", () => {
+		const events = read("skills/trakoo/references/events-and-validation.md");
+		const failureExample = events.match(
+			/## Failure policy and security[\s\S]*?```ts\n([\s\S]*?)```/,
+		)?.[1];
+
+		expect(events).toContain('onFailure: "throw"');
+		expect(events).toContain("AnalyticsValidationError");
+		expect(events).toMatch(/defaults? to `?"drop"`?[^\n]*client and server/i);
+		expect(events).toMatch(/`onError`[\s\S]*exactly once/i);
+		expect(events).toMatch(
+			/AnalyticsValidationError[\s\S]*never retains[\s\S]*submitted properties object[\s\S]*validator exception/i,
+		);
+		expect(events).toMatch(
+			/normalized issues[\s\S]*may include[\s\S]*validator-provided messages/i,
+		);
+		expect(events).toMatch(
+			/default debug logging[\s\S]*never[\s\S]*raw messages[\s\S]*input/i,
+		);
+		expect(events).toMatch(
+			/select[\s\S]*sanitize[\s\S]*fields[\s\S]*observability/i,
+		);
+		expect(events).toMatch(
+			/does not redefine[\s\S]*provider-delivery[\s\S]*initialization/i,
+		);
+		expect(failureExample).toContain("onError(error)");
+		expect(failureExample).toContain("code: error.code");
+		expect(failureExample).toContain("eventName: error.eventName");
+		expect(failureExample).toContain("paths:");
+		expect(failureExample).not.toContain("reportValidationFailure(error)");
+		expect(failureExample).not.toContain("error: AnalyticsValidationError");
+	});
+
+	it("keeps event helpers neutral and runtime-specific APIs on subpaths", () => {
+		const skill = read("skills/trakoo/SKILL.md");
+
+		expect(skill).toContain("environment-neutral");
+		expect(skill).toContain("trakoo/client");
+		expect(skill).toContain("trakoo/server");
+		expect(skill).toContain("trakoo/providers/client");
+		expect(skill).toContain("trakoo/providers/server");
+		expect(skill).toMatch(/fresh[\s\S]*registry-bound instance/i);
+	});
+
+	it("contains no legacy event or singleton API guidance", () => {
+		const content = skillFiles.map(read).join("\n");
+		const code = codeBlocks(content);
+		const forbidden = [
+			"CreateEventDefinition",
+			"EventCollection",
+			"as const satisfies",
+			"properties: {} as",
+			"AppEvents",
+			"createClientAnalytics<",
+			"createServerAnalytics<",
+			"typeof appEvents",
+			"createAnalytics",
+			"getAnalytics",
+			"resetAnalyticsInstance",
+		];
+
+		for (const pattern of forbidden) {
+			expect(content).not.toContain(pattern);
+		}
+
+		for (const helper of [
+			"track",
+			"identify",
+			"pageView",
+			"pageLeave",
+			"reset",
+			"flush",
+		]) {
+			expect(code).not.toMatch(
+				new RegExp(
+					`import\\s*\\{[^}]*\\b${helper}\\b[^}]*\\}\\s*from\\s*["']trakoo/client["']`,
+				),
+			);
+			expect(code).not.toMatch(new RegExp(`(^|[^\\w.])${helper}\\s*\\(`, "m"));
+		}
+	});
+
+	it("covers every public provider and its delivery constraints", () => {
+		const providers = read("skills/trakoo/references/providers.md");
+
+		for (const name of [
+			"PostHog",
+			"OpenPanel",
+			"Bento",
+			"Pirsch",
+			"EmitKit",
+			"Visitors",
+			"Proxy",
+			"BaseAnalyticsProvider",
+		]) {
+			expect(providers).toContain(name);
+		}
+		expect(providers).toContain("@bentonow/bento-node-sdk");
+		expect(providers).toContain("IP address and User-Agent");
+		expect(providers).toContain("excludeEvents");
+		expect(providers).toContain("eventPatterns");
+	});
+
+	it("documents usable Pirsch and Bento constructor contracts", () => {
+		const providers = read("skills/trakoo/references/providers.md");
+
+		expect(providers).toContain(
+			"PirschClientProvider({ identificationCode, hostname? })",
+		);
+		expect(providers).toMatch(
+			/new PirschClientProvider\(\{\s*identificationCode: import\.meta\.env\.VITE_PIRSCH_IDENTIFICATION_CODE,\s*\}\)/,
+		);
+		expect(providers).toContain(
+			"BentoServerProvider({ siteUuid, authentication: { publishableKey, secretKey } })",
+		);
+		expect(providers).toMatch(
+			/new BentoServerProvider\(\{\s*siteUuid: process\.env\.BENTO_SITE_UUID!,\s*authentication: \{\s*publishableKey: process\.env\.BENTO_PUBLISHABLE_KEY!,\s*secretKey: process\.env\.BENTO_SECRET_KEY!,\s*\},\s*\}\)/,
+		);
+		expect(providers).toMatch(
+			/VITE_PIRSCH_IDENTIFICATION_CODE[\s\S]*browser-public/,
+		);
+		expect(providers).toMatch(/BENTO_SECRET_KEY[\s\S]*server-only/);
+	});
+
+	it("documents Bento initialization and shutdown ownership", () => {
+		const providers = read("skills/trakoo/references/providers.md");
+		const bento = providers.match(
+			/### Bento\n\n([\s\S]*?)\n\n### EmitKit/,
+		)?.[1];
+
+		expect(bento).toMatch(
+			/const provider = new BentoServerProvider[\s\S]*await provider\.initialize\(\);[\s\S]*createServerAnalytics\(\{[\s\S]*events: appEvents/,
+		);
+		expect(providers).toContain(
+			"Do not call `shutdown()` after each event on a reusable module singleton.",
+		);
+		expect(bento).toMatch(
+			/request-scoped[\s\S]*fresh provider and analytics pair[\s\S]*same pair[\s\S]*`finally`/,
+		);
+		expect(bento).toMatch(/long-lived[\s\S]*application or process teardown/);
+		expect(bento).toContain(
+			"Bento `shutdown()` clears provider state; it is not a buffered flush.",
+		);
+	});
+
+	it("documents awaited EmitKit initialization and its server-only key boundary", () => {
+		const providers = read("skills/trakoo/references/providers.md");
+		const emitkit = providers.match(
+			/### EmitKit\n\n([\s\S]*?)(?:\n\n### |\n\n## )/,
+		)?.[1];
+
+		expect(emitkit).toBeDefined();
+		expect(emitkit).toMatch(
+			/import \{ EmitKitServerProvider \} from "trakoo\/providers\/server"/,
+		);
+		expect(emitkit).toMatch(
+			/new EmitKitServerProvider\(\{\s*apiKey: process\.env\.EMITKIT_API_KEY!,\s*\}\)/,
+		);
+		expect(emitkit).toMatch(
+			/const provider = new EmitKitServerProvider[\s\S]*await provider\.initialize\(\);[\s\S]*createServerAnalytics\(\{[\s\S]*events: appEvents/,
+		);
+		expect(emitkit).toMatch(/EMITKIT_API_KEY[\s\S]*server-only/i);
+		expect(emitkit).toMatch(
+			/dynamically imports[\s\S]*early calls[\s\S]*skipped[\s\S]*initialization completes/i,
+		);
+		expect(emitkit).toMatch(
+			/request-scoped[\s\S]*`finally`[\s\S]*reusable[\s\S]*application or process teardown/i,
+		);
+	});
+
+	it("preserves Pirsch navigation and request-context constraints", () => {
+		const providers = read("skills/trakoo/references/providers.md");
+
+		expect(providers).toMatch(
+			/pa\.js[\s\S]*initial page load[\s\S]*History API URL changes[\s\S]*by default/,
+		);
+		expect(providers).toContain(
+			"`window.pirsch(name, options)` is the custom-event API",
+		);
+		expect(providers).toContain("Do not redeclare `Window.pirsch`");
+		expect(providers).not.toMatch(
+			/window\.pirsch(?:\?\.)?\(\s*["']pageview["']/i,
+		);
+		expect(providers).toMatch(
+			/verify one initial hit[\s\S]*one SPA navigation hit/i,
+		);
+		expect(providers).toContain(
+			'`methods: ["pageView"]` does not emit SPA navigation hits.',
+		);
+		expect(providers).toMatch(
+			/router does not produce observable History API changes[\s\S]*page-view API explicitly supported by the installed Pirsch version/,
+		);
+		expect(providers).toMatch(
+			/browser-only[\s\S]*server hits[\s\S]*original IP address[\s\S]*User-Agent[\s\S]*skipped/i,
+		);
+	});
+
+	it("documents accurate Bento and Visitors identity constraints", () => {
+		const providers = read("skills/trakoo/references/providers.md");
+		const bento = providers.match(
+			/### Bento\n\n([\s\S]*?)\n\n### EmitKit/,
+		)?.[1];
+		const visitors = providers.match(
+			/### Visitors\n\n([\s\S]*?)\n\n### Proxy/,
+		)?.[1];
+
+		expect(bento).toMatch(/anonymous page views[\s\S]*browser/i);
+		expect(bento).toMatch(
+			/email[\s\S]*identif(?:y|ication)[\s\S]*identified lifecycle[\s\S]*server events/i,
+		);
+		expect(bento).not.toMatch(/email before sending Bento events/i);
+		expect(visitors).toMatch(
+			/`identify\(\)`[\s\S]*does not require persistence/i,
+		);
+		expect(visitors).toMatch(
+			/persistence[\s\S]*cross-session tracking[\s\S]*revenue attribution/i,
+		);
+		expect(visitors).toMatch(/consent/i);
+	});
+
+	it("treats proxy ingestion as an untrusted application endpoint", () => {
+		const providers = read("skills/trakoo/references/providers.md");
+		const proxy = providers.match(
+			/### Proxy\n\n([\s\S]*?)\n\n## Custom providers/,
+		)?.[1];
+
+		expect(proxy).toMatch(/untrusted JSON/i);
+		expect(proxy).toMatch(
+			/same-origin `Origin`[\s\S]*CORS[\s\S]*authenticated session/i,
+		);
+		expect(proxy).toMatch(/request body[\s\S]*batch-size limits/i);
+		expect(proxy).toMatch(/rate limit/i);
+		expect(proxy).toMatch(/trusted prox(?:y|ies)[\s\S]*forwarded IP headers/i);
+		expect(proxy).toMatch(
+			/client-proxied[\s\S]*`userId`[\s\S]*traits[\s\S]*events[\s\S]*authoritative/i,
+		);
+		expect(proxy).toMatch(
+			/runtime registry validation[\s\S]*(?:necessary|required)[\s\S]*not sufficient/i,
+		);
+	});
+
+	it("requires client readiness before the first identity transition", () => {
+		const skill = read("skills/trakoo/SKILL.md");
+
+		expect(skill).toContain("const analyticsReady = analytics.initialize();");
+		expect(skill).toMatch(
+			/async function identifyUser[\s\S]*await analyticsReady;[\s\S]*analytics\.identify/,
+		);
+		expect(skill).toMatch(
+			/login[\s\S]*signup[\s\S]*restored-session\/bootstrap/i,
+		);
+	});
+
+	it("uses distinct browser and server trait contracts", () => {
+		const skill = read("skills/trakoo/SKILL.md");
+		const events = read("skills/trakoo/references/events-and-validation.md");
+		const browser = skill.match(
+			/## Browser module\n\n```ts\n([\s\S]*?)```/,
+		)?.[1];
+		const server = skill.match(
+			/## Server module and critical event\n\n```ts\n([\s\S]*?)```/,
+		)?.[1];
+
+		expect(browser).toMatch(
+			/interface BrowserUserTraits \{\s*email: string;\s*plan: "free" \| "pro";\s*\}/,
+		);
+		expect(browser).toContain("userTraits: typed<BrowserUserTraits>()");
+		expect(browser).toMatch(
+			/identifyUser\(userId: string, traits: BrowserUserTraits\)/,
+		);
+		expect(skill).toMatch(
+			/await identifyUser\([\s\S]*email: restoredSession\.user\.email,[\s\S]*plan: restoredSession\.user\.plan,/,
+		);
+		expect(server).toMatch(
+			/interface ServerUserTraits \{\s*plan: "free" \| "pro";\s*\}/,
+		);
+		expect(server).toContain("userTraits: typed<ServerUserTraits>()");
+		expect(server).not.toMatch(/interface ServerUserTraits \{[^}]*email:/);
+		expect(events).toMatch(
+			/interface BrowserUserTraits \{[\s\S]*email: string;[\s\S]*plan: "free" \| "pro";[\s\S]*\}[\s\S]*interface ServerUserTraits \{[\s\S]*plan: "free" \| "pro";[\s\S]*\}/,
+		);
+		expect(events).toMatch(
+			/browser marker[\s\S]*every object-literal field[\s\S]*`identify\(\)`/i,
+		);
+	});
+
+	it("keeps critical server analytics owned by the request invocation", () => {
+		const skill = read("skills/trakoo/SKILL.md");
+		const serverExample = skill.match(
+			/## Server module and critical event[\s\S]*?```ts\n([\s\S]*?)```/,
+		)?.[1];
+
+		expect(serverExample).toBeDefined();
+		expect(serverExample).toMatch(
+			/export async function [^(]+\([^)]*\) \{\s*const analytics = createRequestAnalytics\(\);\s*try \{/,
+		);
+		expect(serverExample).not.toMatch(
+			/^const analytics = createRequestAnalytics\(\);/m,
+		);
+		expect(serverExample).toMatch(
+			/userId: input\.userId,\s*user: \{\s*email: input\.email,\s*traits: \{ plan: input\.plan \},\s*\}/,
+		);
+		expect(serverExample).not.toMatch(/user:\s*input\.user/);
+		expect(serverExample).not.toMatch(/user:\s*\{\s*email:[^}]*,\s*plan:/);
+	});
+
+	it("nests custom traits in propertyless server user context", () => {
+		const events = read("skills/trakoo/references/events-and-validation.md");
+		const propertyless = events.match(
+			/## Propertyless calls[\s\S]*?```ts\n([\s\S]*?)```[\s\S]*?```ts\n([\s\S]*?)```/,
+		)?.[2];
+
+		expect(events).toMatch(
+			/identity fields[\s\S]*top-level[\s\S]*`user`[\s\S]*application traits[\s\S]*`user\.traits`/i,
+		);
+		expect(propertyless).toMatch(
+			/userId: "user_123",\s*user: \{\s*email: "ada@example\.com",\s*traits: \{ plan: "pro" \},\s*\}/,
+		);
+		expect(events).not.toMatch(/user:\s*input\.user/);
+	});
+
+	it("documents PostHog capture credentials and page-view ownership", () => {
+		const providers = read("skills/trakoo/references/providers.md");
+		const posthog = providers.match(
+			/### PostHog\n\n([\s\S]*?)\n\n### Bento/,
+		)?.[1];
+
+		expect(posthog).toBeDefined();
+		expect(posthog).toMatch(/project (?:capture |API )?key[\s\S]*`phc_/i);
+		expect(posthog).toMatch(/`phx_`[\s\S]*personal API key[\s\S]*never/i);
+		expect(posthog).toMatch(
+			/new PostHogClientProvider\(\{\s*token: import\.meta\.env\.VITE_POSTHOG_PROJECT_KEY,/,
+		);
+		expect(posthog).toMatch(
+			/new PostHogServerProvider\(\{\s*apiKey: process\.env\.POSTHOG_PROJECT_KEY!,/,
+		);
+		expect(posthog).toContain("capture_pageview: false");
+		expect(posthog).toMatch(/one page-view owner/i);
+		expect(posthog).toMatch(/page-leave[\s\S]*one[- ]owner/i);
+		expect(posthog).toMatch(/normalize[\s\S]*URL[\s\S]*deduplic/i);
+	});
+
+	it("passes the registry through supported framework boundaries", () => {
+		const frameworks = read("skills/trakoo/references/frameworks.md");
+
+		for (const name of [
+			"Next.js",
+			"SvelteKit",
+			"TanStack Start",
+			"Astro",
+			"Framework-neutral",
+		]) {
+			expect(frameworks).toContain(name);
+		}
+		expect(frameworks).toContain('import { appEvents } from "./events"');
+		expect(frameworks).toMatch(/events: appEvents/g);
+		expect(frameworks).toContain('router.subscribe("onResolved"');
+		expect(frameworks).toContain("astro:page-load");
+		expect(frameworks).toContain("PUBLIC_");
+		expect(frameworks).toContain("VITE_");
+	});
+
+	it("ties request shutdown to fresh instance ownership in framework guidance", () => {
+		const frameworks = read("skills/trakoo/references/frameworks.md");
+		const nextjs = frameworks.match(
+			/## Next\.js\n\n([\s\S]*?)\n\n## SvelteKit/,
+		)?.[1];
+		const neutral = frameworks.match(
+			/## Framework-neutral TypeScript\n\n([\s\S]*?)\n\n## Verification/,
+		)?.[1];
+
+		for (const guidance of [nextjs, neutral]) {
+			expect(guidance).toMatch(/fresh provider\/analytics pair/);
+			expect(guidance).toMatch(
+				/reusable module singleton[\s\S]*application or process teardown/,
+			);
+		}
+	});
+
+	it("enforces TanStack Start runtime boundaries and page-view ownership", () => {
+		const frameworks = read("skills/trakoo/references/frameworks.md");
+		const tanstack = frameworks.match(
+			/## TanStack Start\n\n([\s\S]*?)\n\n## Astro/,
+		)?.[1];
+
+		expect(tanstack).toContain("analytics.client.ts");
+		expect(tanstack).toContain("analytics.server.ts");
+		expect(tanstack).toContain('import "@tanstack/react-start/client-only"');
+		expect(tanstack).toContain('import "@tanstack/react-start/server-only"');
+		expect(tanstack).toMatch(
+			/\.server\.ts[\s\S]*imported only inside[\s\S]*server-function[\s\S]*handler/i,
+		);
+		expect(tanstack).toContain(
+			'import { createServerFn } from "@tanstack/react-start"',
+		);
+		expect(tanstack).toContain("createServerFn");
+		expect(tanstack).toContain(".handler(async");
+		expect(tanstack).toContain('await import("./analytics.server")');
+		expect(tanstack).toMatch(
+			/unprefixed[\s\S]*environment[\s\S]*`.handler\(\)`[\s\S]*per-request/i,
+		);
+		expect(tanstack).toMatch(/edge[\s\S]*bindings/i);
+		expect(tanstack).toContain("capture_pageview: false");
+		expect(tanstack).toMatch(/one page-view owner/i);
+		expect(tanstack).toContain("new URL(href, window.location.origin)");
+		expect(tanstack).toContain('router.subscribe("onResolved"');
+		expect(tanstack).toContain("unsubscribe()");
+	});
+
+	it("mounts TanStack page tracking through an isomorphic root integration", () => {
+		const frameworks = read("skills/trakoo/references/frameworks.md");
+		const tanstack = frameworks.match(
+			/## TanStack Start\n\n([\s\S]*?)\n\n## Astro/,
+		)?.[1];
+		const code = codeBlocks(tanstack ?? "");
+
+		expect(tanstack).toContain("PageViewTracker.tsx");
+		expect(tanstack).not.toContain("PageViewTracker.client.tsx");
+		expect(tanstack).toContain(
+			'import { createClientOnlyFn } from "@tanstack/react-start"',
+		);
+		expect(code).toMatch(
+			/createClientOnlyFn\(\(router:[\s\S]*await import\("\.\/analytics\.client"\)/,
+		);
+		expect(code).toMatch(
+			/function PageViewTracker\(\)[\s\S]*useEffect\(\(\) => startPageViews\(router\), \[router\]\)[\s\S]*return null/,
+		);
+		expect(tanstack).toMatch(
+			/isomorphic[\s\S]*root route[\s\S]*must not[\s\S]*`\*\.client\.tsx`/i,
+		);
+		expect(tanstack).toMatch(
+			/import \{ PageViewTracker \} from "\.\/PageViewTracker"[\s\S]*function RootComponent\(\)[\s\S]*<PageViewTracker \/>/,
+		);
+		expect(tanstack).toMatch(
+			/confirm[\s\S]*installed[\s\S]*`createClientOnlyFn`[\s\S]*production build/i,
+		);
+	});
+
+	it("awaits browser readiness before TanStack and Astro page views", () => {
+		const frameworks = read("skills/trakoo/references/frameworks.md");
+		const tanstack = frameworks.match(
+			/## TanStack Start\n\n([\s\S]*?)\n\n## Astro/,
+		)?.[1];
+		const astro = frameworks.match(
+			/## Astro\n\n([\s\S]*?)\n\n## Framework-neutral TypeScript/,
+		)?.[1];
+		const tanstackCode = codeBlocks(tanstack ?? "");
+		const astroCode = codeBlocks(astro ?? "");
+
+		expect(tanstack).toMatch(/retained[\s\S]*initialization promise/i);
+		expect(tanstackCode).toMatch(
+			/await analyticsReady;[\s\S]*emitPageView\(window\.location\.href\)[\s\S]*router\.subscribe/,
+		);
+		expect(tanstackCode).not.toMatch(
+			/emitPageView\(window\.location\.href\)[\s\S]*await analyticsReady/,
+		);
+		expect(astro).toMatch(/retained[\s\S]*initialization promise/i);
+		expect(astroCode).toMatch(
+			/astro:page-load[\s\S]*await analyticsReady;[\s\S]*analytics\.pageView/,
+		);
+		expect(tanstack).toMatch(/disposed[\s\S]*unsubscribe/i);
+		expect(astro).toMatch(/registers the listener once/i);
+	});
+
+	it("keeps TanStack critical events authoritative on the server", () => {
+		const frameworks = read("skills/trakoo/references/frameworks.md");
+		const tanstack = frameworks.match(
+			/## TanStack Start\n\n([\s\S]*?)\n\n## Astro/,
+		)?.[1];
+		const code = codeBlocks(tanstack ?? "");
+		const inputSchema = code.match(
+			/const trackPurchaseInput = z\.object\(\{([\s\S]*?)\}\);/,
+		)?.[1];
+
+		expect(inputSchema).toMatch(/^\s*orderId: z\.string\(\)\.min\(1\),?\s*$/);
+		expect(code).toContain(".validator(trackPurchaseInput)");
+		expect(code).toContain("const user = await requireUser()");
+		expect(code).toMatch(
+			/purchases\.confirmAndLoad\(\{\s*orderId: data\.orderId,\s*userId: user\.id,\s*\}\)/,
+		);
+		expect(code).toMatch(
+			/await analytics\.track\(\s*"purchase_completed",\s*\{\s*orderId: order\.id,\s*amount: order\.totalAmount,\s*currency: order\.currency,\s*\},\s*\{\s*userId: user\.id,\s*user: \{\s*email: user\.email,\s*traits: \{ plan: order\.plan \},\s*\},\s*\},\s*\)/,
+		);
+		expect(code).not.toMatch(/data\.(?:properties|options)\b/);
+		expect(code).not.toMatch(/\bdata\s+as\s+/);
+		expect(code).not.toMatch(/(?:amount|currency|userId|email|plan):\s*data\./);
+		expect(tanstack).toMatch(
+			/`requireUser` and `purchases\.confirmAndLoad`[\s\S]*consuming application/i,
+		);
+	});
+
+	it("documents skills CLI installation", () => {
+		const readme = read("readme.md");
+
+		expect(readme).toContain("## Agent Skill");
+		expect(readme).toContain(
+			"npx skills add multiplehats/trakoo --skill trakoo",
+		);
+		expect(readme).toContain("skills/trakoo/SKILL.md");
+	});
+
+	it("gates publication on real-package v1 consumer fixtures", () => {
+		const skill = read("skills/trakoo/SKILL.md");
+		const verification = skill.match(
+			/## Verification\n\n([\s\S]*?)\n\n## Common mistakes/,
+		)?.[1];
+
+		expect(verification).toBeDefined();
+		expect(verification).toMatch(/maintainer release gate/i);
+		expect(verification).toMatch(
+			/must not be published[\s\S]*PR #32[\s\S]*migrated implementation lands/i,
+		);
+		expect(verification).toMatch(
+			/representative consumer fixtures[\s\S]*compiled[\s\S]*typechecked[\s\S]*real built package/i,
+		);
+		expect(verification).toMatch(/not[\s\S]*fabricated declarations/i);
+		for (const requiredCoverage of [
+			"root helpers and registry",
+			"Zod transformation and distinct input/output types",
+			"Valibot or ArkType",
+			"client and server factories sharing `events`",
+			"browser identify traits and nested server traits",
+			"propertyless client call",
+			"propertyless server-options call",
+			'validation `"drop"` and `"throw"`',
+		]) {
+			expect(verification).toContain(requiredCoverage);
+		}
+	});
+});
diff --git a/www/content/docs/(Getting Started)/agent-skill.mdx b/www/content/docs/(Getting Started)/agent-skill.mdx
new file mode 100644
index 0000000..47c5c88
--- /dev/null
+++ b/www/content/docs/(Getting Started)/agent-skill.mdx	
@@ -0,0 +1,116 @@
+---
+title: Agent Skill
+description: Install the trakoo agent skill with the skills CLI so your coding agent follows trakoo's event, provider, and client/server conventions.
+sidebar:
+  label: Agent Skill
+---
+
+trakoo ships an [Agent Skill](https://www.skills.sh/docs): a set of instructions your coding agent loads when it works on analytics code. It teaches the agent how to define a shared event registry, where the browser/server boundary sits, how to configure each provider, and how to wire trakoo into Next.js, SvelteKit, TanStack Start, or Astro.
+
+The skill lives in this repository at [`skills/trakoo/SKILL.md`](https://github.com/multiplehats/trakoo/blob/main/skills/trakoo/SKILL.md) and uses the portable `SKILL.md` format, so it works with any agent the `skills` CLI supports — Claude Code, Codex, Cursor, and others.
+
+## Install
+
+Run the CLI from your project root:
+
+<Tabs>
+<Tab title="npm">
+
+```bash
+npx skills add multiplehats/trakoo --skill trakoo
+```
+
+</Tab>
+<Tab title="pnpm">
+
+```bash
+pnpm dlx skills add multiplehats/trakoo --skill trakoo
+```
+
+</Tab>
+<Tab title="bun">
+
+```bash
+bunx skills add multiplehats/trakoo --skill trakoo
+```
+
+</Tab>
+</Tabs>
+
+`--skill trakoo` selects the skill by name, so the CLI installs only this one instead of prompting for everything in the repository. The CLI then asks which agents to install it for and writes the skill into that agent's project directory — `.claude/skills/trakoo/` for Claude Code, for example.
+
+Skip the prompt by naming the agent yourself:
+
+```bash
+npx skills add multiplehats/trakoo --skill trakoo --agent claude-code
+```
+
+Install it once for every project on your machine with `--global`, which writes to your home directory instead of the current repository:
+
+```bash
+npx skills add multiplehats/trakoo --skill trakoo --global
+```
+
+:::note[Project or global?]
+Install per project when your team should share the same trakoo conventions through version control. Install globally when you want the skill available in every repository you touch, including ones that don't use trakoo yet.
+:::
+
+## Manage the skill
+
+```bash
+# See what's installed and where
+npx skills list
+
+# Pull the latest version of the skill
+npx skills update
+
+# Uninstall it
+npx skills remove trakoo
+```
+
+See the [skills CLI reference](https://www.skills.sh/docs/cli) for the full set of commands and flags.
+
+## Install manually
+
+If your agent isn't covered by the CLI, copy the skill directory into wherever that agent reads skills from:
+
+```bash
+git clone https://github.com/multiplehats/trakoo.git /tmp/trakoo
+cp -R /tmp/trakoo/skills/trakoo .claude/skills/trakoo
+```
+
+Keep the directory intact — `SKILL.md` links to the reference files next to it, and the agent reads them on demand.
+
+## What the agent gets
+
+| File | The agent reads it when |
+|------|-------------------------|
+| `SKILL.md` | Always. Covers the shared event registry, the client and server modules, import boundaries, identity lifecycle, and verification steps. |
+| `references/events-and-validation.md` | Defining events, adding a Standard Schema validator like Zod, or handling validation failures. |
+| `references/providers.md` | Choosing providers, routing events, using the Proxy, or writing a custom provider. |
+| `references/frameworks.md` | Integrating with Next.js, SvelteKit, TanStack Start, Astro, or a framework-neutral setup. |
+
+## Using it
+
+Agents load a skill based on its description, so you don't need to invoke it by name. Describe the work and the agent picks it up:
+
+> Track a `purchase_completed` event from our Stripe webhook handler and send it to PostHog.
+
+The skill tells the agent to inspect your project first — package manager, framework, installed trakoo version, and existing entry points — and to treat the trakoo declarations installed in your `node_modules` as the source of truth. If your installed version disagrees with the skill, the agent should surface the mismatch rather than invent an API.
+
+## Next steps
+
+<CardGroup>
+  <Card title="Installation" href="/docs/installation" icon="download">
+    Install the core package and the SDKs each provider needs.
+  </Card>
+  <Card title="Quick Start" href="/docs/quick-start" icon="rocket">
+    Go from install to your first tracked event in a few minutes.
+  </Card>
+  <Card title="Client vs Server" href="/docs/core-concepts/client-vs-server" icon="server">
+    Understand the boundary the skill enforces.
+  </Card>
+  <Card title="Framework Guides" href="/docs/guides/nextjs" icon="code">
+    Wire trakoo into Next.js or SvelteKit end to end.
+  </Card>
+</CardGroup>
diff --git a/www/content/docs/(Getting Started)/index.mdx b/www/content/docs/(Getting Started)/index.mdx
index 079e008..3aa4f8d 100644
--- a/www/content/docs/(Getting Started)/index.mdx	
+++ b/www/content/docs/(Getting Started)/index.mdx	
@@ -118,4 +118,7 @@ Add Bento for lifecycle email later, or move browser events through the [Proxy](
   <Card title="Framework Guides" href="/docs/guides/nextjs" icon="code">
     Wire trakoo into Next.js or SvelteKit end to end.
   </Card>
+  <Card title="Agent Skill" href="/docs/agent-skill" icon="bot">
+    Teach your coding agent trakoo's conventions with `npx skills add`.
+  </Card>
 </CardGroup>
diff --git a/www/content/docs/(Getting Started)/meta.ts b/www/content/docs/(Getting Started)/meta.ts
index bcf0b91..af9438d 100644
--- a/www/content/docs/(Getting Started)/meta.ts	
+++ b/www/content/docs/(Getting Started)/meta.ts	
@@ -3,5 +3,5 @@ import { defineMeta } from "blume";
 export default defineMeta({
 	title: "Getting Started",
 	icon: "rocket",
-	pages: ["index", "installation", "quick-start"],
+	pages: ["index", "installation", "quick-start", "agent-skill"],
 });