diff --git a/.agents/skills/jetstream-client/SKILL.md b/.agents/skills/jetstream-client/SKILL.md
new file mode 100644
index 0000000..e849c68
--- /dev/null
+++ b/.agents/skills/jetstream-client/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: jetstream-client
+description: Integrate or debug the Zig Jetstream v2 client SDK, including archive replay, live cutover, event handling, cursors, and failover. Use for applications consuming this SDK and for changes to its client behavior.
+---
+
+# Jetstream client
+
+Start with the consumer's dependency pin and the matching SDK revision.
+Distinguish released behavior from local edits before giving API examples.
+
+## choose the client surface
+
+Read [the client contract](../../../docs/client.md) and
+[the public exports](../../../src/root.zig). `subscribe` owns archive replay
+and live cutover; `LiveClient` and `ArchiveBackfill` expose the individual
+halves. Read [the implementation](../../../src/client.zig) when diagnosing
+recovery or callback behavior. The v1 time-cursor client remains in `zat`;
+identify the consumer's actual import before changing it.
+
+## integration decisions
+
+- Decide whether the application needs current records, bounded historical
+  replay, or continuous capture. [The Streamplace example](../../../examples/streamplace_chat.zig)
+  demonstrates time-bounded replay; estimate the planned work before a large
+  download. Archive retention and delete-compaction determine what history
+  remains available.
+- Persist the cursor with successfully processed application state. Define
+  idempotency and restart behavior; a delivered callback alone does not prove
+  that the application's durable state advanced.
+- A v2 sequence cursor belongs to one instance. Read
+  [failover](../../../docs/failover.md) before configuring multiple hosts;
+  live rotation re-anchors by witnessed time, while archive errors stay on
+  their original instance. Witnessed time is distinct from record creation.
+- Choose the archive error policy explicitly. Accepting a recoverable error
+  through `onError` accepts incomplete archive work; the client contract
+  describes which rows can still be delivered. Check the pinned version.
+- Match filters and event kinds to the application, including identity,
+  account, and sync handling. Record data can borrow SDK buffers; copy anything
+  retained beyond the callback according to the pinned implementation.
+
+## verify the integration
+
+Use bounded local fixtures for cursor persistence, duplicates, callback stop,
+archive-error decisions, and reconnects. The SDK's
+[loopback tests](../../../src/loopback_test.zig) show protocol fixtures.
+Use a finite live smoke for transport checks; size an archive plan before
+using it as a smoke test. Follow the project release skill for SDK releases.
+
+For stream.waow.tech deployment, authentication configuration, and operational
+incidents, consult the owning [stream docs](https://tangled.org/zat.dev/stream/tree/main/docs),
+especially deploying.md, gotchas.md, and upstream-subscribe-protocol.md.