opencode-skills-collection 4.0.48 → 4.0.49

package/bundled-skills/slideops/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: slideops
+description: "Turn a repository into a cited HTML slide deck and detect the day it drifts from the code. Citations record file, lines, and hash; a stdlib check reports CURRENT, MOVED, or CHANGED."
+category: content
+risk: critical
+source: community
+source_repo: glukicov/slideops
+source_type: community
+date_added: "2026-08-31"
+author: glukicov
+tags: [slides, presentations, documentation, docs-as-code, drift-detection, citations, html]
+tools: [claude-code, codex-cli, copilot, opencode]
+license: "MIT"
+license_source: "https://github.com/glukicov/slideops/blob/main/LICENSE"
+---
+
+# SlideOps: slides from a repo, that tell you when they go stale
+
+> **Catalog copy, frozen at v1.0.0.** The canonical source is
+> [glukicov/slideops](https://github.com/glukicov/slideops), which also carries the deck
+> template, the two citation scripts, the reference docs, and the companion
+> `slides-to-pdf` skill. Install from there; this page summarizes the workflow.
+
+## Overview
+
+SlideOps has two jobs, and the second one is the point. **Build**: turn a repository into
+a single self-contained HTML slide deck whose every claim came from the code, not from a
+model's impression of the code. **Keep in sync**: make that deck able to prove, months
+later, whether it still matches the repository.
+
+The mechanism joining them is a citation. Every quoted snippet records the file, the line
+range, and a hash of those source lines at build time, and the deck records the commit it
+was built from. "Are these slides still accurate?" becomes a command instead of a
+re-read: a standard-library Python script diffs each citation against the current code
+and reports `CURRENT`, `MOVED`, `CHANGED`, or `MISSING`. No model, no network, no tokens,
+milliseconds to run.
+
+## When to Use This Skill
+
+- Use when the user asks for slides, a slide deck, or a presentation about a code
+  repository, one of its subsystems, a feature, or its recent changes: "make slides",
+  "overview deck", "team update slides", "HTML slides for this repo".
+- Use when the user asks whether an existing deck still matches the code, or wants one
+  rechecked, refreshed, or kept in sync: "is this deck still accurate", "check the
+  slides against the code", "these docs are stale".
+- Use when the user wants deck freshness wired into CI, a pull request check, or an
+  agent hook: "fail the build when the deck stops matching the code".
+- Do **not** use for slide decks about anything other than a codebase (a sales deck, a
+  lecture); the citation mechanism assumes a git repository as the source of truth.
+
+## How It Works
+
+### Step 1: Install from the canonical repo
+
+In Claude Code, as a plugin (both skills, background updates):
+
+```text
+/plugin marketplace add glukicov/slideops
+/plugin install slideops@slideops
+```
+
+Or for Codex CLI, Copilot CLI, and OpenCode, one installer covers all of them:
+
+```bash
+git clone https://github.com/glukicov/slideops && cd slideops
+git checkout ba43e89bc7936649be36a1796a62203f704f8c60   # the v1.0.0 release commit
+./install.sh
+```
+
+The checkout pins the exact commit this catalog copy froze at, which is what a reader
+can verify independently. (The canonical repo also blocks retargeting of `v*` tags with
+an active tag ruleset, but a SHA does not ask you to trust that.) `install.sh` symlinks
+the two skills into `~/.claude/skills` (read by Claude Code and OpenCode) and
+`~/.agents/skills` (read by Codex CLI and Copilot CLI).
+
+### Step 2: Build a deck
+
+The skill walks a fixed pipeline: a two-minute repo scan, one compact intake (topic,
+audience, length, theme, scope, extras), an outline checkpoint before any HTML is
+written, then slide-by-slide construction from a verified template. Every snippet is
+cited as it is written. Run the citation script from inside the repository being
+presented, via its installed path (an agent resolves `scripts/` against the skill's own
+directory automatically; the paths below are for running it yourself after
+`install.sh`):
+
+```bash
+python3 ~/.agents/skills/slideops/scripts/cite.py app/main.py:40-58 --repo . --snippet   # prints data-src + data-sha256
+python3 ~/.agents/skills/slideops/scripts/cite.py --stamp deck.html --repo .             # stamps the build commit
+```
+
+`--repo` always points at the repository the deck is about, never at the SlideOps
+checkout.
+
+Every slide is then rendered with headless Chrome and visually verified before the deck
+is considered done.
+
+### Step 3: Check it later, for free
+
+From inside the repository being presented, same path convention as Step 2:
+
+```bash
+python3 ~/.agents/skills/slideops/scripts/check.py docs/slides/ --repo .
+```
+
+Real output, from the demo deck that ships with the skill:
+
+```text
+Deck: skill-demo.html
+Built: commit=179bbdb date=2026-08-28 repo=slideops
+
+  slide   9  THEMING        skills/slideops/assets/template.html:22-45    CURRENT
+  slide  14  MERMAID        skills/slideops/references/diagrams.md:55-59  CURRENT
+
+2 current, 0 stale, 2 cited in total.
+```
+
+`MOVED` means only line numbers shifted (update two attributes, leave the prose).
+`CHANGED` means the quoted code was edited (read the diff, decide whether the slide's
+claim survived). `MISSING` means the file is gone (the slide is probably obsolete). The
+`--json` flag emits a complete repair brief per stale citation, so an agent can fix
+drift without re-reading the repository.
+
+## Examples
+
+### Example 1: New deck
+
+```text
+User: make slides about this repo
+Agent: [scans repo, proposes 3-4 concrete topics with a "why now" each,
+        asks one compact intake, shows an outline, then builds and
+        visually verifies a cited HTML deck at docs/slides/]
+```
+
+### Example 2: Freshness check in CI
+
+```bash
+python3 tools/slideops-check.py docs/slides/ --repo . --exit-zero   # report-only PR annotation
+```
+
+The canonical repo's `references/automation.md` has the PR-check workflow, advisory hook
+variants, and a delegated-refresh recipe. `check.py` is one dependency-free file, meant
+to be vendored into the deck's own repo.
+
+## Best Practices
+
+- ✅ Cite with `cite.py`, never by hand: a hand-computed hash silently reports `CHANGED`
+  months later and nobody can tell whether the code moved or the build was sloppy.
+- ✅ Repair a drifted deck; do not rebuild it. Fix only the slides whose citations went
+  stale, then re-stamp.
+- ✅ Automate the check for evergreen decks (onboarding, architecture); leave snapshots
+  (sprint updates, conference talks) frozen deliberately.
+- ❌ Do not run `check.py` against a PDF export: citations live in the HTML, so the PDF
+  reports "No citations found in this deck".
+- ❌ Do not block every commit on the check. Report-only on pull requests first; a docs
+  gate on the fast path trains people to pass `--no-verify`.
+
+## Limitations
+
+- Needs a headless Chrome or Chromium binary (Playwright cache or system install) for
+  the visual verification pass, and Python 3 for the citation scripts.
+- Works offline except two opt-ins: Mermaid diagrams (a one-time `npx` download) and
+  brand-color extraction from a live style guide.
+- The check verifies quoted snippets against the code; it cannot verify prose claims
+  that cite nothing.
+- Drift detection assumes the deck and the code share a git repository.
+
+## Security & Safety Notes
+
+- Ask before cloning the upstream repository, running `install.sh`, creating skill
+  symlinks in the user's home directory, downloading an optional `npx` package, or
+  writing deck output. Show the exact pinned commit and destination paths first, and
+  preserve any existing skill entries instead of overwriting them silently.
+- The citation scripts are standard-library-only Python: no dependencies, no network,
+  no tokens.
+- The skill declares no `allowed-tools`, deliberately: the host agent's own permission
+  model stays in charge, and headless Chrome keeps its sandbox.
+- The skill carries an explicit confidentiality rule for deck content: never read or
+  quote secrets, keys, `.env` files, production logs, or customer data; redact internal
+  hostnames and identifiers; and finish with a redaction scan of the rendered slides,
+  because decks are documents that leave the repository.
+- File writes are limited to the deck output folder (default `docs/slides/`) plus its
+  companion README.
+
+## Common Pitfalls
+
+- **Problem:** `check.py` on an exported PDF reports no citations.
+  **Solution:** Run it against the HTML deck; the PDF is a derived artifact from the
+  companion `slides-to-pdf` skill.
+- **Problem:** A freshly built deck already reports `CHANGED`.
+  **Solution:** That is a build defect, not a future problem: a snippet was quoted and
+  then edited, or a hash was hand-computed. Re-cite with `cite.py` before shipping.
+- **Problem:** Chrome is not found on the verification step.
+  **Solution:** The canonical repo's `references/verification.md` has the cross-platform
+  discovery recipe (Playwright cache first, then system installs).
+
+## Related Skills
+
+- `slides-to-pdf` (same canonical repo): screenshots every slide at 2x, prints a
+  page-per-slide PDF, and verifies the result by rendering the PDF back to images.
+- `@2slides-ppt-generator`: API-driven deck generation from text or documents; use it
+  when the source material is not a code repository.

package/bundled-skills/trigger-dev/SKILL.md

@@ -38,6 +38,7 @@ execution with excellent developer experience and TypeScript-first design.
 ## Scope
 
 - redis-queues -> bullmq-specialist
+- serverless-queues -> upstash-qstash
 - pure-event-driven -> inngest
 - workflow-orchestration -> temporal-craftsman
 - infrastructure -> infra-architect
@@ -891,6 +892,7 @@ Fix action: Batch items and use fewer waits, or split into subtasks
 ### Delegation Triggers
 
 - redis|bullmq|traditional queue -> bullmq-specialist (Need Redis-backed queues instead of managed service)
+- serverless queue|http queue|no workers -> upstash-qstash (Need HTTP-delivered queues and schedules without a worker runtime)
 - vercel|deployment|serverless -> vercel-deployment (Trigger.dev needs deployment config)
 - database|postgres|supabase -> supabase-backend (Tasks need database access)
 - openai|anthropic|ai model|llm -> llm-architect (Tasks need AI model integration)

package/bundled-skills/unsloth-finetuning/SKILL.md

@@ -72,10 +72,20 @@ libraries at import time; importing them first silently disables the optimizatio
 
 ```python
 import unsloth  # must be first
+import os
+import re
 from unsloth import FastLanguageModel
 
+def reviewed_revision(variable):
+    revision = os.environ.get(variable, "")
+    if re.fullmatch(r"[0-9a-fA-F]{40}", revision) is None:
+        raise RuntimeError(f"{variable} must be a reviewed full 40-character Hub commit SHA")
+    return revision.lower()
+
+model_revision = reviewed_revision("UNSLOTH_MODEL_REVISION")
 model, tokenizer = FastLanguageModel.from_pretrained(
     model_name = "unsloth/Qwen3-8B",
+    revision = model_revision,
     max_seq_length = 2048,
     load_in_4bit = True,
     dtype = None,  # auto-detects bf16 where supported
@@ -87,6 +97,9 @@ Pick the loader that matches the modality: `FastLanguageModel` for text-only cau
 
 The `unsloth/` Hub namespace holds pre-quantized copies that download faster and skip a local
 quantization pass. Upstream repos such as `Qwen/` or `meta-llama/` work identically.
+Before setting `UNSLOTH_MODEL_REVISION`, inspect that exact Hub commit and obtain approval for the
+download. Record the repository and full revision with the run; never substitute a branch, tag,
+range, or moving default.
 
 ### Step 3: Fix the chat template before training
 
@@ -194,20 +207,35 @@ cannot be cleanly re-quantized afterwards.
 
 ```python
 import unsloth
+import os
+import re
 from unsloth import FastLanguageModel
 from unsloth.chat_templates import get_chat_template, train_on_responses_only
 from datasets import load_dataset
 from trl import SFTTrainer, SFTConfig
 
+def reviewed_revision(variable):
+    revision = os.environ.get(variable, "")
+    if re.fullmatch(r"[0-9a-fA-F]{40}", revision) is None:
+        raise RuntimeError(f"{variable} must be a reviewed full 40-character Hub commit SHA")
+    return revision.lower()
+
+model_revision = reviewed_revision("UNSLOTH_MODEL_REVISION")
+dataset_revision = reviewed_revision("UNSLOTH_DATASET_REVISION")
 model, tokenizer = FastLanguageModel.from_pretrained(
     model_name = "unsloth/Qwen3-8B",
+    revision = model_revision,
     max_seq_length = 2048,
     load_in_4bit = True,
 )
 model = FastLanguageModel.get_peft_model(model, r = 16, lora_alpha = 16)
 
 tokenizer = get_chat_template(tokenizer, chat_template = "qwen3")
-dataset = load_dataset("mlabonne/FineTome-100k", split = "train[:5000]")
+dataset = load_dataset(
+    "mlabonne/FineTome-100k",
+    revision = dataset_revision,
+    split = "train[:5000]",
+)
 
 trainer = SFTTrainer(
     model = model,
@@ -239,11 +267,21 @@ Load with `fast_inference=True` to route sampling through vLLM in the same proce
 
 ```python
 import unsloth
+import os
+import re
 from unsloth import FastLanguageModel
 from trl import GRPOTrainer, GRPOConfig
 
+def reviewed_revision(variable):
+    revision = os.environ.get(variable, "")
+    if re.fullmatch(r"[0-9a-fA-F]{40}", revision) is None:
+        raise RuntimeError(f"{variable} must be a reviewed full 40-character Hub commit SHA")
+    return revision.lower()
+
+model_revision = reviewed_revision("UNSLOTH_MODEL_REVISION")
 model, tokenizer = FastLanguageModel.from_pretrained(
     model_name = "unsloth/Qwen3-4B",
+    revision = model_revision,
     max_seq_length = 1024,
     load_in_4bit = True,
     fast_inference = True,       # vLLM sampling backend
@@ -307,8 +345,13 @@ GRPO learning rates sit roughly two orders of magnitude below SFT. Reward functi
   committed token grants write access to every model the account owns.
 - Fine-tuning reproduces the training data's content and biases in the weights. Confirm the
   dataset is licensed for training and free of secrets before starting.
+- Pin every Hub model and dataset to a reviewed full commit SHA, obtain approval before changing
+  either revision, and record both values with the training artifact. Prefer the verified local
+  cache for repeat runs instead of re-resolving network defaults.
 - GGUF export builds llama.cpp from source on first use, compiling third-party code and
-  requiring network access. Expect it to be slow and to need a working toolchain.
+  requiring network access. Before the first export, identify and review the exact llama.cpp
+  revision that will be built; do not permit an unattended moving-revision fetch. Prefer a
+  user-approved, full-commit-pinned local toolchain and cache.
 - Unsloth is dual-licensed: the core package is Apache-2.0, while optional components such as
   the Studio UI are AGPL-3.0. Check a component's license before redistributing it.
 

package/bundled-skills/upstash-qstash/SKILL.md

@@ -931,7 +931,7 @@ Workflow:
 
 ## Related Skills
 
-Works well with: `vercel-deployment`, `nextjs-app-router`, `redis-specialist`, `email-systems`, `supabase-backend`, `cloudflare-workers`
+Works well with: `upstash-redis`, `upstash-ratelimit`, `vercel-deployment`, `nextjs-app-router`, `redis-specialist`, `email-systems`, `supabase-backend`, `cloudflare-workers`
 
 ## When to Use
 - User mentions or implies: qstash

package/bundled-skills/upstash-ratelimit/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: upstash-ratelimit
+description: "Add rate limiting to API routes, middleware, and edge functions with @upstash/ratelimit: sliding window, fixed window, and token bucket backed by Upstash Redis."
+category: backend
+risk: critical
+source: self
+source_type: self
+date_added: "2026-08-31"
+author: CahidArda
+tags: [upstash, rate-limiting, redis, serverless, edge, middleware, 429]
+tools: [claude, codex, cursor, gemini]
+---
+
+# Upstash Ratelimit
+
+## Overview
+
+`@upstash/ratelimit` implements distributed rate limiting on top of Upstash
+Redis. Because state lives in Redis, every instance of a serverless function
+or edge worker shares the same counters, which an in-memory limiter cannot
+do. It ships three algorithms (fixed window, sliding window, token bucket),
+per-identifier keys, optional in-memory blocking of already-limited
+identifiers, and optional analytics.
+
+## When to Use This Skill
+
+- Use when the user needs to limit requests per IP, user, API key, or tenant
+  across multiple serverless instances or regions.
+- Use when protecting login, signup, form, webhook, or LLM endpoints from
+  abuse and returning `429 Too Many Requests`.
+- Use when choosing between fixed window, sliding window, and token bucket.
+- Do not use for client-side retry/backoff against a third-party API's limits;
+  see `api-rate-limit-handler`.
+- Do not use for a single long-running process with no shared state; an
+  in-memory limiter is simpler there.
+
+## How It Works
+
+### Step 1: Install and configure
+
+```bash
+npm install @upstash/ratelimit @upstash/redis
+```
+
+Set `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` in the environment.
+
+### Step 2: Create the limiter once, outside the handler
+
+```typescript
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+
+export const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, "10 s"), // 10 requests per 10 seconds
+  prefix: "rl:api",
+  analytics: true,
+});
+```
+
+Constructing the limiter at module scope lets the built-in ephemeral cache
+short-circuit blocked identifiers without a Redis call.
+
+### Step 3: Call `limit()` with a stable identifier
+
+```typescript
+const { success, limit, remaining, reset, pending } = await ratelimit.limit(userId);
+```
+
+`success` is `false` when the identifier is over its limit. `reset` is a Unix
+timestamp in milliseconds. `pending` is a promise for background work
+(analytics, multi-region sync); await it or pass it to `waitUntil` on edge
+runtimes so the function is not frozen before it completes.
+
+## Examples
+
+### Example 1: Next.js middleware returning 429
+
+```typescript
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+import { NextResponse, type NextRequest } from "next/server";
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(20, "1 m"),
+});
+
+export async function middleware(request: NextRequest) {
+  const ip = request.headers.get("x-forwarded-for") ?? "anonymous";
+  const { success, limit, remaining, reset } = await ratelimit.limit(ip);
+
+  if (!success) {
+    return new NextResponse("Too Many Requests", {
+      status: 429,
+      headers: {
+        "X-RateLimit-Limit": String(limit),
+        "X-RateLimit-Remaining": String(remaining),
+        "X-RateLimit-Reset": String(reset),
+        "Retry-After": String(Math.ceil((reset - Date.now()) / 1000)),
+      },
+    });
+  }
+  return NextResponse.next();
+}
+
+export const config = { matcher: "/api/:path*" };
+```
+
+### Example 2: Token bucket with per-plan limits
+
+```typescript
+const limiters = {
+  free: new Ratelimit({
+    redis: Redis.fromEnv(),
+    prefix: "rl:free",
+    limiter: Ratelimit.tokenBucket(5, "10 s", 10), // refill 5 per 10 s, burst 10
+  }),
+  pro: new Ratelimit({
+    redis: Redis.fromEnv(),
+    prefix: "rl:pro",
+    limiter: Ratelimit.tokenBucket(50, "10 s", 100),
+  }),
+};
+
+const { success } = await limiters[plan].limit(apiKey);
+```
+
+## Best Practices
+
+- ✅ Use a stable, low-cardinality identifier (user id, API key, tenant) where
+  possible; fall back to IP only for anonymous traffic.
+- ✅ Set a distinct `prefix` per endpoint or plan so limits do not collide.
+- ✅ Return `Retry-After` and `X-RateLimit-*` headers with 429 responses.
+- ✅ Prefer `slidingWindow` for most APIs; use `tokenBucket` when short bursts
+  are acceptable; use `fixedWindow` when the lowest Redis cost matters.
+- ❌ Don't construct a new `Ratelimit` inside the request handler.
+- ❌ Don't rely on `pending` completing on its own in edge runtimes.
+- ❌ Don't rate limit by `x-forwarded-for` without validating it is set by
+  your proxy; clients can spoof it otherwise.
+
+## Limitations
+
+- Requires an Upstash Redis database; it does not work with other Redis
+  servers or without network access.
+- Each `limit()` call is at least one HTTP round trip to Redis, so it adds
+  latency to every request it guards.
+- Sliding window is an approximation that assumes an even spread of requests
+  in the previous window; it is not an exact log.
+- `MultiRegionRatelimit` trades strict accuracy for lower latency and does
+  not support the token bucket algorithm.
+- If Redis is unreachable, the default `timeout` (5 s) lets requests through
+  (`reason: "timeout"`); this fails open, not closed.
+- This skill does not replace environment-specific validation, testing, or
+  expert review.
+
+## Security & Safety Notes
+
+- Rate limiting is one layer of abuse protection, not authentication. Pair it
+  with auth and input validation.
+- The Redis token grants full database access; keep it server-side.
+- Changing limits in production can lock out legitimate users. Confirm the
+  numbers with the user before deploying stricter limits.
+
+## Common Pitfalls
+
+- **Problem:** Every request is allowed even after the limit.
+  **Solution:** Each identifier must be the same string across requests;
+  check that the identifier is not `undefined` or a fresh random value.
+- **Problem:** Analytics are empty on Vercel Edge or Cloudflare Workers.
+  **Solution:** Pass `pending` to `waitUntil` (`ctx.waitUntil(pending)`) so
+  the background request is not cancelled when the response is sent.
+
+## Related Skills
+
+- `@upstash-redis` - The client this package uses for storage.
+- `@api-rate-limit-handler` - Client-side backoff and retry when you are the
+  one being rate limited.
+- `@upstash-qstash` - Queue and smooth traffic to downstream services instead
+  of rejecting it.
+
+## Additional Resources
+
+- [Upstash Ratelimit documentation](https://upstash.com/docs/redis/sdks/ratelimit-ts/overview)
+- [@upstash/ratelimit on GitHub](https://github.com/upstash/ratelimit-js)
+- [Algorithms guide](https://upstash.com/docs/redis/sdks/ratelimit-ts/algorithms)

package/bundled-skills/upstash-redis/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: upstash-redis
+description: "Use the @upstash/redis HTTP client for caching, sessions, counters, and Redis data structures from serverless and edge runtimes without connection pooling."
+category: backend
+risk: critical
+source: self
+source_type: self
+date_added: "2026-08-31"
+author: CahidArda
+tags: [upstash, redis, cache, serverless, edge, key-value]
+tools: [claude, codex, cursor, gemini]
+---
+
+# Upstash Redis
+
+## Overview
+
+`@upstash/redis` is a Redis client that talks to an Upstash Redis database over
+HTTPS instead of a TCP connection. Because every command is a stateless HTTP
+request, it works in environments where a pooled TCP client is awkward or
+impossible: Vercel and Netlify functions, Cloudflare Workers, Deno, Bun, and
+Next.js middleware. The client serializes and deserializes JavaScript values
+automatically, so numbers and objects round-trip without manual `JSON.parse`.
+
+## When to Use This Skill
+
+- Use when the user needs a cache, session store, counter, leaderboard, or
+  simple queue from a serverless or edge function.
+- Use when the user mentions Upstash Redis, `UPSTASH_REDIS_REST_URL`, or
+  `@upstash/redis`.
+- Use when migrating an `ioredis` or `node-redis` call site to a runtime that
+  cannot hold a persistent TCP socket.
+- Do not use for a self-hosted or non-Upstash Redis server; the client only
+  speaks the Upstash REST protocol. Use `ioredis` or `node-redis` there.
+- Do not use for Redis administration or CLI work; see `redis-cli`.
+
+## How It Works
+
+### Step 1: Configure credentials
+
+Create a database in the Upstash console and copy the REST URL and token into
+environment variables. Never hardcode them.
+
+```bash
+UPSTASH_REDIS_REST_URL=https://<your-db>.upstash.io
+UPSTASH_REDIS_REST_TOKEN=<your-rest-token>
+```
+
+### Step 2: Create one client per module
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+export const redis = Redis.fromEnv();
+```
+
+On Cloudflare Workers, import from `@upstash/redis/cloudflare` and pass the
+worker `env` object: `Redis.fromEnv(env)`.
+
+### Step 3: Call Redis commands as methods
+
+Command names are lowercase methods (`get`, `set`, `hset`, `zadd`, `incr`).
+Values are auto-serialized; pass and receive native JavaScript types.
+
+## Examples
+
+### Example 1: Cache-aside with a TTL
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+export async function getUser(id: string) {
+  const cached = await redis.get<{ id: string; name: string }>(`user:${id}`);
+  if (cached) return cached;
+
+  const user = await db.users.findById(id);
+  await redis.set(`user:${id}`, user, { ex: 3600 }); // expires in 1 hour
+  return user;
+}
+
+export async function invalidateUser(id: string) {
+  await redis.del(`user:${id}`);
+}
+```
+
+### Example 2: Batch commands in a pipeline
+
+```typescript
+const pipeline = redis.pipeline();
+pipeline.hset("user:1", { name: "Alice", plan: "pro" });
+pipeline.incr("signups:total");
+pipeline.zadd("leaderboard", { score: 120, member: "user:1" });
+const [hsetResult, signups, zaddResult] = await pipeline.exec();
+```
+
+`pipeline()` batches independent commands into one round trip. It is not
+atomic; use `redis.multi()` for MULTI/EXEC or a reviewed server-side Lua script
+when commands must run as one unit.
+
+## Best Practices
+
+- ✅ Read credentials with `Redis.fromEnv()` or from a secrets manager.
+- ✅ Set a TTL (`{ ex: seconds }`) on cache entries so stale data expires.
+- ✅ Namespace keys (`user:123`, `session:abc`) to keep the keyspace readable.
+- ✅ Use `pipeline()` or `mget`/`mset` instead of many sequential awaits.
+- ❌ Don't `JSON.stringify` values before `set`; the client already does it.
+- ❌ Don't call `keys("*")` in request handlers; use `scan` for large keyspaces.
+- ❌ Don't store secrets or PII in Redis without a retention plan and TTL.
+
+## Limitations
+
+- Requires an Upstash Redis database; it cannot connect to other Redis servers.
+- Each command is an HTTP request, so latency is higher than a warm TCP
+  connection; batch with pipelines where it matters.
+- Transactions (`multi()`) do not roll back on runtime errors, and `WATCH` is
+  not available over REST; use a Lua script for atomic check-and-set.
+- Pub/Sub subscribe and blocking commands (`BLPOP`, `XREAD BLOCK`) are not
+  supported over the REST client.
+- This skill covers the TypeScript client only. Python, Go, and other SDKs
+  differ in method names.
+- This skill does not replace environment-specific validation, testing, or
+  expert review.
+
+## Security & Safety Notes
+
+- The REST token grants full read/write access to the database. Keep it in
+  server-side environment variables; never ship it to a browser bundle.
+- Use a read-only token from the console for read-only workloads.
+- Commands such as `flushdb` and `del` are destructive; confirm with the user
+  before running them against a production database.
+
+## Common Pitfalls
+
+- **Problem:** `get` returns `null` in production but works locally.
+  **Solution:** The deployment is missing `UPSTASH_REDIS_REST_URL` or
+  `UPSTASH_REDIS_REST_TOKEN`; check the platform's environment settings.
+- **Problem:** A number comes back as a string after `incr` on a value set
+  with `JSON.stringify`.
+  **Solution:** Store the raw number (`redis.set("n", 1)`) and let the client
+  serialize it.
+
+## Related Skills
+
+- `@upstash-ratelimit` - Rate limiting built on this client.
+- `@upstash-qstash` - HTTP message queue and schedules when you need delivery
+  guarantees rather than a data store.
+- `@redis-cli` - Inspecting and administering Redis from the command line.
+- `@bullmq-specialist` - Job queues on a TCP Redis you operate yourself.
+
+## Additional Resources
+
+- [Upstash Redis documentation](https://upstash.com/docs/redis)
+- [@upstash/redis on GitHub](https://github.com/upstash/redis-js)
+- [TypeScript SDK reference](https://upstash.com/docs/redis/sdks/ts/overview)