@ericrisco/rsc 0.1.44 → 0.1.46

package/skills/building-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: building-agents
-description: "Use when designing or building an LLM agent, tool-using system, RAG pipeline, eval harness, or MCP server in this repo — across any provider (OpenAI, Anthropic, Google Gemini, or OSS via OpenAI-compatible endpoints / litellm). Triggers: 'build an agent', 'add tool calling / function calling', 'structured JSON output', 'RAG / retrieval / embeddings / rerank', 'agent loop / ReAct / orchestrator-worker / multi-agent', 'LLM eval / golden set / LLM-as-judge / regression gate', 'prompt caching / model routing / token budget / cost control', 'trace / observability for LLM calls', 'build an MCP server', or 'make our LLM code provider-agnostic / swap models'. FastAPI/Python, Next.js, Go, Flutter, Postgres stacks."
+description: "Use when building or restructuring an LLM agent — provider adapter, tool calling, structured output, RAG, agent loop, eval gate, cost routing, tracing, MCP server — model-agnostic across OpenAI/Anthropic/Gemini/OSS so a model swap is a config change. NOT vector-store SQL alone (that is `postgresdb`) or service deployment (that is `deployment`)."
 tags: [agents, llm, mcp, rag, evals, ai]
 recommends: [secure-coding, deployment]
 origin: risco
@@ -8,65 +8,26 @@ origin: risco
 
 # Building production LLM agents (model-agnostic)
 
-Build production LLM agents that are model-agnostic by construction — a thin provider adapter, a disciplined agent loop, schema-validated tools, provider-neutral RAG, eval gates, OTel tracing, and optionally an MCP server — so swapping OpenAI ↔ Anthropic ↔ Gemini ↔ OSS is a config change, not a rewrite.
+A thin provider adapter, a disciplined agent loop, schema-validated tools, provider-neutral RAG, eval gates, OTel tracing, and optionally an MCP server — so swapping OpenAI ↔ Anthropic ↔ Gemini ↔ OSS is a config change, not a rewrite.
 
 ## The one rule
 
-> Program against a **capability interface**, never a vendor SDK. Vendor specifics (model id, tool-schema shape, JSON mode, caching, token limits) live behind one adapter resolved from config. If a model name or price appears in business logic, it's a bug.
+> Program against a **capability interface**, never a vendor SDK. Vendor specifics (model id, tool-schema shape, JSON mode, caching, token limits) live behind one adapter resolved from config. Model names and prices rot — if one appears in business logic it's a bug, and re-verify the dated tables before quoting a number.
 
-> Model names and prices rot. Never hardcode them in app logic — resolve from config/registry, and re-verify the dated tables before quoting a number.
-
-## When to use / When NOT to use
-
-> **⚠️ SDD new-feature gate — read this first.** If this skill fired on a **new, non-trivial feature or behaviour change** and there is **no approved spec + plan** under `02-DOCS/wiki/sdd/`, STOP — do **not** write feature code yet. Hand off to `../specify/SKILL.md` first: it runs brainstorm → spec → plan → tasks before any code, then routes back here once the plan is approved. Build here directly only for a genuinely one-line / low-risk change. Method: `../sdd/SKILL.md`.
-
-**Use when:** starting any production-bound LLM feature; code is hardwired to one SDK and you want to swap/route/fallback models; adding tools/function calling, structured output, or streaming; standing up RAG over Postgres/`pgvector` or an external store; building an eval harness / CI quality gate; adding tracing, cost tracking, caching, or routing/cascades; building or hardening an MCP server.
-
-**Do NOT use when:**
-
-- One-shot throwaway prompt, no tools, no eval, no production path → just call the SDK directly.
-- Pure prompt-wording improvement with no architecture → that's prompt engineering, not this.
-- Anthropic-SDK-specific tuning (caching internals, thinking, batch) in a file that *only* imports `anthropic` → defer to a dedicated Anthropic-SDK skill if your environment provides one (e.g. `claude-api`); this skill stays multi-provider.
-- Workspace scaffolding (`01-TOOLS`/`02-DOCS` layout) → **`harness`**.
-- Picking *which* coding agent (Claude Code vs Aider) → agent-eval territory, not this.
-- No retrieval, no tools, no loop, no evals at all → you don't need an agent; say so.
+**Hand off instead when:** a new non-trivial feature has no approved spec + plan under `02-DOCS/wiki/sdd/` → stop and run [`specify`](../specify/SKILL.md) first (method: [`sdd`](../sdd/SKILL.md)), which routes back here once the plan is approved; one-line/low-risk changes go straight through. Anthropic-SDK internals (caching, thinking, batch) in a file that *only* imports `anthropic` → `claude-api` if your environment has it, since this skill stays multi-provider. Workspace scaffolding → [`harness`](../harness/SKILL.md). Choosing *which* coding agent to use → agent-eval territory. Pure prompt-wording tuning with no architecture change → prompt engineering, not this. A one-shot throwaway prompt, or no retrieval/tools/loop/evals at all → you don't need an agent; call the SDK directly and say so.
 
 ## Decision rules (read before writing code)
 
 1. **Adapter first** — define the `LLMProvider` Protocol before any provider call.
-2. **Smallest loop that works** — single-agent before multi-agent; ReAct only when the path is uncertain; plan-execute when steps are knowable.
+2. **Smallest loop that works** — single-agent before multi-agent; ReAct only when the path is uncertain; plan-execute when steps are knowable. Multi-agent means orchestrator-worker with a semaphore-bounded parallel fan-out, never a free-for-all.
 3. **Tools are typed contracts** — schema + validation + idempotency key on every side-effecting tool; no catch-all tools.
 4. **Retrieve, don't stuff** — RAG when ground truth lives in data; cite or refuse.
 5. **Eval before ship** — a golden set + regression gate in CI, or it's not production.
 6. **Cheapest model that passes the eval** — route/cascade up, never default to flagship.
 
-## Architecture at a glance
-
-```text
-            ┌───────────────────────────────────────────────────────────┐
-  Caller ──▶│  Agent loop  (perceive → decide → act → observe, bounded) │
-            └───────────────────────────────────────────────────────────┘
-               │              │                │              │
-               ▼              ▼                ▼              ▼
-        ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐
-        │  Provider  │  │   Tool     │  │ Retriever  │  │  Tracer    │
-        │  adapter   │  │  registry  │  │ (pgvector) │  │  (OTel)    │
-        │ ↔ OpenAI / │  │ → sandboxed│  │ → cite/    │  │ gen_ai.*   │
-        │ Anthropic /│  │   tools    │  │   refuse   │  │            │
-        │ Gemini /OSS│  └────────────┘  └────────────┘  └────────────┘
-        └────────────┘
-               ▲                                          │
-               └──────────── Eval gate (CI) ◀─────────────┘
-   provider-abstraction.md  agent-loops…/tools-and-rag.md  evals-and-observability.md
-```
-
 ## The provider adapter (the heart of the skill)
 
-The one payload to internalize. Python 3.12+, Pydantic v2, **async** so it composes
-directly with the agent loop in `references/agent-loops-and-harness.md`. Streaming,
-the Gemini and OSS/litellm adapters, tool-result plumbing, and a `route()` registry live
-in `references/provider-abstraction.md` — this excerpt is the load-bearing core, not the
-whole interface.
+The one payload to internalize. Python 3.12+, Pydantic v2, **async** so it composes directly with the bounded loop (and orchestrator-worker fan-out) in [`references/agent-loops-and-harness.md`](references/agent-loops-and-harness.md). Structured output is the quirk that differs most per vendor: strict JSON Schema (OpenAI), tool-forcing (Anthropic), `response_json_schema` (Gemini). Streaming, the Gemini and OSS/litellm adapters, tool-result plumbing, and a `route()` registry live in [`references/provider-abstraction.md`](references/provider-abstraction.md) — this excerpt is the load-bearing core, not the whole interface.
 
 ```python
 from __future__ import annotations
@@ -176,21 +137,7 @@ def get_provider(spec: str | None = None) -> LLMProvider:
 
 ## Good vs Bad
 
-```python
-# BAD — vendor SDK + model id hardwired into a handler; swapping = rewrite every call-site.
-client = OpenAI()
-def summarize(text: str) -> str:
-    r = client.chat.completions.create(model="gpt-5.5", messages=[{"role": "user", "content": text}])
-    return r.choices[0].message.content
-```
-
-```python
-# GOOD — one adapter resolved from config; logic never names a model.
-provider = get_provider(settings.llm)  # e.g. "anthropic:claude-sonnet-4-6"
-async def summarize(text: str) -> str:
-    req = CompletionRequest(model=settings.model_id, messages=[Message(role="user", content=text)])
-    return (await provider.complete(req)).text
-```
+Call-sites use the adapter and never name a model: `provider = get_provider(settings.llm)` (e.g. `"anthropic:claude-sonnet-4-6"`), then `await provider.complete(req)`. The two failures that survive that discipline:
 
 ```python
 # BAD — parse-and-pray; wrong shape fails silently at 3am.
@@ -276,9 +223,10 @@ def dispatch(name: str, raw_args: dict) -> ToolResult:
         return ToolResult(status="error", summary="invalid args", data={"errors": e.errors()},
                           next_actions=["fix the arguments and retry"])
     return handler(args)
-# schema design, sandboxing, idempotency, DI-scoped DB sessions -> references/tools-and-rag.md
 ```
 
+Schema design, sandboxing, idempotency, DI-scoped DB sessions, plus the RAG internals below — chunking, hybrid RRF, rerank, the citation grader, memory — are in [`references/tools-and-rag.md`](references/tools-and-rag.md).
+
 ## RAG in 30 lines (provider-agnostic embeddings)
 
 ```sql
@@ -320,7 +268,6 @@ async def answer(query: str) -> str:
                   Message(role="user", content=f"{context}\n\nQ: {query}")],
     )
     return (await provider.complete(req)).text
-# chunking, hybrid RRF, rerank, citation grader, memory -> references/tools-and-rag.md
 ```
 
 ## Evals & cost gates (the production line)
@@ -355,8 +302,8 @@ async def run_eval(golden_path: str, graders: list, thresholds: dict[str, float]
 ```
 
 Routing cascade in one line: `route(task) → cheapest model whose eval passes; escalate only on a failed self-check`.
-
-Pointer: full runner, judge, CI gate, caching, batching, budgets → `references/evals-and-observability.md`.
+Full runner, judge, CI gate, caching, batching and budgets →
+[`references/evals-and-observability.md`](references/evals-and-observability.md).
 
 ## Observability (OTel GenAI, vendor-neutral)
 
@@ -381,10 +328,10 @@ async def traced_complete(provider: LLMProvider, req: CompletionRequest) -> Comp
 
 ## MCP: when and the smallest server
 
-**Native tools** when the agent and tools share a process/repo. **MCP** when tools must be reused across clients/teams or run out-of-process — accept the MCP cost (schema tokens, transport, ops) in exchange for reuse.
+**Native tools** when the agent and tools share a process/repo. **MCP** when tools must be reused across clients/teams or run out-of-process — accept the MCP cost (schema tokens, transport, ops) in exchange for reuse. TypeScript server, transports, HTTP+auth and testing are in [`references/mcp-servers.md`](references/mcp-servers.md).
 
 ```python
-from fastmcp import FastMCP  # standalone fastmcp 2.x; see references/mcp-servers.md
+from fastmcp import FastMCP  # standalone fastmcp 2.x
 
 mcp = FastMCP("invoices")
 
@@ -406,12 +353,11 @@ def read_invoice(invoice_id: str) -> str:
 if __name__ == "__main__":
     mcp.run()  # stdio transport
 # (MCP spec 2025-11-25; stateless-core RC 2026-07-28; verify before quoting)
-# TypeScript server, transports, HTTP+auth, testing -> references/mcp-servers.md
 ```
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization | Reality |
+| Anti-pattern | Reality |
 |---|---|
 | "I'll just call the OpenAI SDK directly, we'll never switch" | The adapter is ~40 lines; retrofitting it across 30 call-sites later is a rewrite. Adapter first. |
 | "JSON output is usually valid, I'll parse it" | "Usually" = pages at 3am. Use strict structured output + schema validation. |
@@ -426,44 +372,15 @@ if __name__ == "__main__":
 | "Tool results just return the raw API blob" | Give the model `status/summary/next_actions`; raw blobs waste context and stall recovery. |
 | "Prompt caching is Anthropic-only so skip caching" | Each provider has its own caching/dedup; abstract it behind the adapter, don't skip it. |
 
-## Quick reference
-
-| Task | Do this | Reference |
-|---|---|---|
-| Define a provider | `LLMProvider` Protocol + normalized request/response | `references/provider-abstraction.md` |
-| Add a tool | Pydantic args model + `ToolResult` + validating dispatcher | `references/tools-and-rag.md` |
-| Structured output | Strict JSON Schema (OpenAI) / tool-forcing (Anthropic) / `response_json_schema` (Gemini) | `references/provider-abstraction.md` |
-| Build the loop | Bounded perceive → decide → act → observe with budgets | `references/agent-loops-and-harness.md` |
-| Multi-agent | Orchestrator-worker + parallel fan-out with a semaphore | `references/agent-loops-and-harness.md` |
-| RAG | `pgvector` ANN + hybrid RRF + rerank + cite | `references/tools-and-rag.md` |
-| Eval gate | Golden set + graders + CI threshold exit code | `references/evals-and-observability.md` |
-| Trace | OTel GenAI `gen_ai.*` spans, swappable exporter | `references/evals-and-observability.md` |
-| Cut cost | Cache + route/cascade + batch + budgets | `references/evals-and-observability.md` |
-| MCP server | FastMCP stdio / Streamable HTTP server | `references/mcp-servers.md` |
-
 ## verify.sh
 
 `scripts/verify.sh` lints example agent code and dry-runs the eval smoke test in **the user's project** — not in this skill repo. It detects each tool (`ruff`, `mypy`, `tsc`/`node`, `go`, the eval entrypoint, `markdownlint`) and skips any that are missing with a yellow WARN; a missing tool never fails the run. Invoke it with `bash scripts/verify.sh` from the project root. Exit 0 means clean (or only skips); a non-zero exit means a real lint/typecheck/vet/eval failure.
 
-## Project grounding (02-DOCS + CLAUDE.md)
-
-When this skill runs in a project with a `02-DOCS/` layer (the
-[`harness`](../harness/SKILL.md) Karpathy wiki), record this
-project's agent decisions there and index them in `02-DOCS/wiki/index.md`, so the next
-agent inherits the conventions instead of re-deriving them.
-
-1. **Find the article** `02-DOCS/wiki/stack/agents.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
-2. **If missing or stale**, create/update it with the project's real choices — the provider(s) and model routing, where the provider adapter lives, tool/RAG conventions, the eval gates, and the observability backend —
-   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it). Write it as an OKF v0.1 wiki article per the harness [`wiki-article-template.md`](../harness/references/wiki-article-template.md): open with YAML frontmatter carrying a non-empty `type:` (use `type: stack`), and use standard markdown links — never wikilinks.
-3. **Read it first on every use** and stay consistent; when a convention changes, update the
-   article (bump its `timestamp`) in the same change.
+## Project grounding
 
-No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Unlike the
-brand study, technical conventions are *recorded, not gated* — never block the task on this.
+In a project with a `02-DOCS/` layer ([`harness`](../harness/SKILL.md)), read `02-DOCS/wiki/stack/agents.md` first on every use and stay consistent with it. If it is missing or stale, write this project's real choices there — provider(s) and model routing, where the adapter lives, tool/RAG conventions, eval gates, observability backend — as a `type: stack` article per the harness [`wiki-article-template.md`](../harness/references/wiki-article-template.md), index it in `02-DOCS/wiki/index.md`, and bump its `timestamp` in the same change as any convention change. No `02-DOCS/`? Skip silently — technical conventions here are *recorded, not gated*; never block the task on this.
 
-## See Also
+## See also
 
-- `../harness/SKILL.md` — workspace `01-TOOLS`/`02-DOCS` scaffolding.
-- Stack siblings the examples target: `../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`; plus `../secure-coding/SKILL.md` and `../deployment/SKILL.md` for hardening and shipping the agent service.
-- External skills (no sibling in this repo; use if your environment provides them): `claude-api` — Anthropic-SDK-specific tuning (caching internals, thinking, batch) when a file only imports `anthropic`; `deep-research` — the research-harness fan-out / verify pattern.
-- ECC analogues (external, no links): `agent-harness-construction`, `eval-harness`, `cost-aware-llm-pipeline`, `mcp-server-patterns`, `context-budget`.
+- Stacks the examples target: [`fastapi`](../fastapi/SKILL.md), [`nextjs`](../nextjs/SKILL.md), [`go`](../go/SKILL.md), [`postgresdb`](../postgresdb/SKILL.md), [`flutter`](../flutter/SKILL.md). Harden with [`secure-coding`](../secure-coding/SKILL.md), ship with [`deployment`](../deployment/SKILL.md).
+- External (no sibling here; use if your environment provides them): `claude-api` for Anthropic-SDK-only tuning, `deep-research` for the research-harness fan-out / verify pattern.

package/skills/business-intelligence/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: business-intelligence
-description: "Use when someone wants to ask business questions over the org's data in plain language and get consistent, trustworthy numbers, when a metric (revenue, MRR, active users, gross margin) must be defined once so every dashboard/report/agent computes it identically, when wiring an LLM or agent to query data without hallucinating SQL, or when two teams report different numbers for the same thing. Triggers: 'semantic layer', 'metrics layer', 'define MRR once', 'self-serve analytics in plain English', 'text-to-SQL but trustworthy', 'sales and finance disagree on revenue', 'the agent keeps hallucinating SQL', 'dbt Semantic Layer', 'MetricFlow', 'Cube', 'capa semántica', 'consultar dades en llenguatge natural'. NOT designing chart layout or panels (that is dashboard), NOT choosing which KPIs to track (that is kpi-framework), NOT writing the raw query by hand (that is sql)."
+description: "Use when a metric (revenue, MRR, margin) needs defining once in a governed semantic layer so every dashboard, report and agent returns the same number, or when an LLM must answer data questions in plain language without hallucinating SQL. NOT chart layout (that is `dashboard`), NOT which KPIs to track (that is `kpi-framework`), NOT a hand-written query (that is `sql`)."
 tags: [business-intelligence, semantic-layer, metrics-layer, text-to-sql, natural-language-query, dbt, cube]
 recommends: [sql, dashboard, kpi-framework, reporting, analytics, forecasting, clickhouse-analytics, duckdb]
 origin: risco
@@ -119,15 +119,6 @@ Question: "MRR by plan, monthly, last 2 quarters, EU customers only"
   filter      -> region = 'EU'
 ```
 
-```text
-Pregunta (ES/CA): "ingresos por región, mensual, últimos 2 trimestres, solo UE"
-  metric      -> gross_revenue
-  group by    -> region
-  time grain  -> month
-  date filter -> last 2 quarters
-  filter      -> region = 'EU'
-```
-
 You hand the layer that spec; it generates the governed SQL. You then explain the answer back in business terms ("EU MRR grew 8% QoQ, driven by the Pro plan"), not as a table dump.
 
 ## Wire the agent
@@ -155,22 +146,17 @@ Author toward the **Open Semantic Interchange** standard so definitions survive
 
 ## Anti-patterns
 
-| Rationalization | Reality | STOP |
+| Anti-pattern | Why it bites | Instead |
 |---|---|---|
-| "Just free-hand the SQL this once, it's faster" | "Once" becomes the fourth conflicting revenue figure; it's unauditable | Add/query a metric |
-| "Each dashboard can define revenue itself" | That is exactly how you get three numbers and a fire drill | One metric, all consumers query it |
-| "The time dimension grain is obvious, skip declaring it" | Undeclared grain → silent daily-vs-monthly mismatches | Declare `time_granularity`/`grain` |
-| "Give the agent warehouse creds, it'll figure out the joins" | Raw text-to-SQL is 84-90% (33% in 2023); unauditable | Expose metrics via MCP/API |
-| "Stand up a semantic layer for this 200-row CSV" | Pure overhead for one analyst | `../sql/SKILL.md` / `../duckdb/SKILL.md` |
-| "The LLM is smart enough to write correct SQL" | The dbt 2026 benchmark says the layer is +8-14pts more accurate | Ground it in the layer |
-| "Hard-code the EU filter into the metric" | Now you need a second metric for every region | Pass filters at query time |
+| Free-handing the SQL "just this once" because it's faster | "Once" becomes the fourth conflicting revenue figure; it's unauditable | Add/query a metric |
+| Letting each dashboard define revenue itself | That is exactly how you get three numbers and a fire drill | One metric, all consumers query it |
+| Skipping the time dimension's grain because it's "obvious" | Undeclared grain → silent daily-vs-monthly mismatches | Declare `time_granularity`/`grain` |
+| Handing the agent warehouse creds to figure out the joins | Raw text-to-SQL is 84-90% (33% in 2023) and unauditable; the dbt 2026 benchmark puts the layer +8-14pts ahead | Expose metrics via MCP/API |
+| Standing up a semantic layer for a 200-row CSV | Pure overhead for one analyst | `../sql/SKILL.md` / `../duckdb/SKILL.md` |
+| Hard-coding the EU filter into the metric | Now you need a second metric for every region | Pass filters at query time |
 
 ## Verify
 
 Run `scripts/verify.sh [path]` on your semantic-model directory. It is read-only, never touches a warehouse, and discovers candidate YAML, then warns (advisory) on: a metric with no underlying measure, a measure with no declared `agg`, a time dimension with no grain, duplicate metric names, and a `.sql` beside the model hand-rolling an aggregate the layer should own. It exits non-zero only on unparseable YAML; an empty or clean target passes clean.
 
-## See also
-
-- `references/authoring-semantic-models.md` — multi-entity models, metric types, semi-additive measures, time spines, fan-out traps.
-- `references/wiring-agents-and-apis.md` — MCP metrics-tool pattern, dbt SL / Cube query shapes, agent guardrails.
-- Siblings: `../sql/SKILL.md` · `../dashboard/SKILL.md` · `../kpi-framework/SKILL.md` · `../reporting/SKILL.md` · `../analytics/SKILL.md` · `../forecasting/SKILL.md`
+Siblings: `../sql/SKILL.md` · `../dashboard/SKILL.md` · `../kpi-framework/SKILL.md` · `../reporting/SKILL.md` · `../analytics/SKILL.md` · `../forecasting/SKILL.md`

package/skills/calendar-scheduling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: calendar-scheduling
-description: "Use when adding booking/scheduling to a product — a 'pick a slot' page, an embedded Cal.com/Calendly widget, or a flow that shows real availability and writes the confirmed meeting to Google/Outlook/Apple — and when fixing the three classic bugs: double-booking, wrong-time-after-DST, and orphaned events on reschedule. Triggers: 'add a book-a-call page', 'embed Cal.com and white-label it', 'show my real availability and create the calendar event', 'we keep getting double-booked when two people pick the same slot', 'bookings show the wrong time after the clocks changed', 'fire a webhook on each booking', 'añade reservas de citas a la web y evita solapamientos con mi calendario de Outlook', 'evita que se reserve dos veces el mismo hueco'. NOT raw calendar CRUD, free/busy plumbing, or watch channels for an internal app with no booking surface (that is google-workspace), NOT a generic non-booking inbound event receiver (that is webhooks), NOT charging for a paid appointment (that is stripe)."
+description: "Use when a product needs a booking surface — a pick-a-slot page, a Cal.com/Calendly embed, or real availability plus the confirmed meeting written to Google/Outlook — or when fixing double-booking, DST drift, or orphaned reschedule events. NOT calendar CRUD with no booking surface (that is `google-workspace`), NOT the payment (that is `stripe`)."
 tags: [scheduling, booking, calendar, calcom, calendly, google-calendar, availability, webhooks]
 recommends: [google-workspace, webhooks, automation-flows, email-connector, stripe, sales-pipeline]
 profiles: []
@@ -12,17 +12,9 @@ origin: risco
 Scheduling is always two halves bolted together: a **booking surface** (an
 external person reserves a slot — embed, atom, or API call) and **calendar
 sync** (you read free/busy to compute availability and write the confirmed
-event back). Ship one without the other and you get the three bugs this skill
-exists to prevent:
-
-- **Double-booking** — two people grab the same slot because availability was
-  computed in the browser or written before a re-check.
-- **Timezone drift** — a meeting shows the wrong hour after a DST change because
-  a wall-clock time was stored instead of an instant + IANA zone.
-- **Orphaned events** — a reschedule creates a *second* calendar event instead
-  of moving the first, so the calendar fills with phantoms.
-
-Everything below is in service of not shipping those.
+event back). Ship one without the other and you get the three bugs the rest of
+this skill exists to prevent: **double-booking**, **timezone drift** after a DST
+change, and **orphaned events** on reschedule.
 
 ## Decide the altitude first
 
@@ -38,7 +30,9 @@ Pick the lowest-code option that still owns the data model you actually need.
 Why per row: the embed is zero-maintenance but a black box; the atom/API buys
 your own UI without owning sync; raw provider is full control and full
 liability; a unified API trades a vendor for not maintaining three calendar
-integrations. Full comparison in `references/provider-matrix.md`.
+integrations. Hosting, auth/scopes, webhook events, cross-domain support and
+when each wins, per provider:
+[`references/provider-matrix.md`](references/provider-matrix.md).
 
 - **Cal.com** is open-source and self-hostable. Self-hosted instances get
   **unlimited API access** (no cloud rate limit) and full white-label by
@@ -78,9 +72,6 @@ Scope ladder, narrowest first:
 - `calendar` / `calendar.events` — restricted; request only if you genuinely
   manage arbitrary events the app didn't create.
 
-**Calendly:** OAuth 2.1 or a personal access token. **Cal.com self-host:** no
-rate-limit anxiety, so no token-bucket gymnastics needed in your client.
-
 ## Availability without double-booking — the core flow
 
 Both classic races (computing slots in the browser, and writing the event
@@ -107,8 +98,10 @@ Decision — do you need a hold step?
 | Multi-step booking form, payment, or high contention | Yes — a TTL lock so the slot survives the form and releases if abandoned |
 
 Google's availability primitive is `freebusy.query` (POST, returns busy blocks
-per calendar); the write is `events.insert`. Payloads in
-`references/google-calendar-sync.md`.
+per calendar); the write is `events.insert`. Both payloads (with
+`conferenceData` for Meet), `watch` channels + sync tokens, recurring-event edge
+cases and refresh-token handling:
+[`references/google-calendar-sync.md`](references/google-calendar-sync.md).
 
 ## Timezone correctness
 
@@ -180,15 +173,6 @@ that orchestration is **automation-flows**, not here.
 | Poll the calendar for changes | Slow, rate-limited, misses edits | `watch` push channels + incremental sync tokens |
 | Write new code against Calendly v1 | v1 API + webhooks dead since May 2025 | Calendly v2 (OAuth 2.1 / PAT) |
 
-## References
-
-- `references/provider-matrix.md` — Cal.com vs Calendly vs Google direct vs
-  Nylas v3 vs Cronofy: hosting, auth/scopes, webhook events, cross-domain,
-  when each wins.
-- `references/google-calendar-sync.md` — `freebusy.query` and `events.insert`
-  (with `conferenceData` for Meet) payloads, `watch` channels + sync tokens,
-  recurring-event edge cases, refresh-token handling.
-
 Adjacent skills: raw calendar CRUD / watch channels with no booking →
 [`../google-workspace/SKILL.md`](../google-workspace/SKILL.md); charging for a
 paid appointment → [`../stripe/SKILL.md`](../stripe/SKILL.md); booking funnel as

package/skills/case-studies/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: case-studies
-description: "Use when turning a real customer win into a case study or testimonial — a metrics-anchored success story or an attributed quote a prospect can act on, including when a great result reads like a brochure and needs to convert. Triggers: 'turn this customer win into a case study', 'we cut their churn 40% — write it up', 'draft a testimonial quote from this customer-interview transcript', 'we have a 40% drop but the write-up sounds like marketing fluff — make it convert', 'build a reusable customer-story template plus an intake/consent form', 'escríbeme un caso de éxito de este cliente con métricas y una cita', 'redacta un cas d'èxit amb mètriques'. NOT the deck that pitches the vision to a room (that is pitch-deck), NOT a long thought-leadership article with no single named customer (that is article-writing)."
+description: "Use when turning one named customer's measured win into a case study, or the attributed testimonial quote that travels with it — consent-cleared, metrics-anchored proof for the next skeptical buyer. NOT the deck that sells the vision to a room (that is `pitch-deck`), NOT thought-leadership with no single named customer (that is `article-writing`)."
 tags: [case-study, testimonial, social-proof, customer-story, conversion]
 recommends: [pitch-deck, article-writing, retention, review-management, brand-voice, landing-copy]
 origin: risco
@@ -29,7 +29,7 @@ If the request is not a single customer's measured outcome, hand it off before y
 | Drop the proven quote into a converting page | `../landing-copy/SKILL.md` |
 | Price the offer this win justifies | `pricing` |
 
-The one-sentence call: it is a case study if a real, named customer already got a measured result and consented to be quoted. Vision-to-a-room is `pitch-deck`; no-single-customer is `article-writing`.
+The one-sentence call: it is a case study if a real, named customer already got a measured result and consented to be quoted.
 
 ## The intake gate — STOP if any of these is missing
 
@@ -61,7 +61,7 @@ quote_source: "interview-2026-05-20.txt"
 ---
 ```
 
-`consent: pending` means draft-only. `consent: anonymized` means no name/logo/identifying detail ships. Only `consent: signed` may publish a named, quoted, imaged customer. Full intake form, approval-email wording, and substantiation notes live in `references/consent-and-substantiation.md`.
+`consent: pending` means draft-only. `consent: anonymized` means no name/logo/identifying detail ships. Only `consent: signed` may publish a named, quoted, imaged customer. Full intake form, consent/release checklist, approval-email wording, substantiation and insider-disclosure notes, and the anonymization fallback rules live in `references/consent-and-substantiation.md`.
 
 ## Case-study anatomy
 
@@ -140,8 +140,3 @@ Write the prose so these fall out cleanly; do not produce a separate brochure fo
 `scripts/verify.sh <case-study.md>` is a read-only structural and legal lint. It checks for a quantified hero metric, the required Challenge/Solution/Result sections and snapshot box, an attributed quote, a before→after signal, a CTA, and the `consent:` / `approved:` marker — and it warns on the superlative banlist. It **fails hard** when the hero has no metric, a core section is missing, or consent is unmarked, because shipping an un-consented named quote is the legal risk. It is structural lint only; persuasion quality is the capability eval's job and yours.
 
 Hand off when the piece is done: the proven quote → `../landing-copy/SKILL.md`, the broader narrative → `../article-writing/SKILL.md`, the slide version → `../pitch-deck/SKILL.md`, the public-review angle → `../review-management/SKILL.md`.
-
-## References
-
-- `references/case-study-skeleton.md` — the full ordered template (results headline, snapshot box, C-S-R sections with Context-Achievement-Relevance metric lines, attributed quote block, CTA) plus a filled mini-example with consent front-matter.
-- `references/consent-and-substantiation.md` — intake-form fields, consent/release checklist, exact-quote-approval email wording, FTC substantiation and insider-disclosure notes, anonymization fallback rules.

package/skills/chatbot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chatbot
-description: "Use when putting a support or sales bot on a live website and it must behave — writing or hardening its persona/system prompt, designing the bot→human handoff, stopping it inventing prices/policies/refunds, defending against jailbreaks and prompt injection, qualifying leads, or setting launch metrics and a kill switch. Triggers: 'put a chatbot on our site that answers from our docs', 'add a chat widget', 'our bot promised a refund we don't offer — lock it down', 'stop people jailbreaking our website assistant', 'design the handoff to a human agent', 'qualify leads and book demos', 'necesito un chatbot de ventas para la web que califique leads i reservi demos'. NOT building the agent loop/RAG index/eval harness under it (that is building-agents), and NOT a human answering one live ticket (that is customer-support)."
+description: "Use when a support or sales bot on a live website must behave: persona/system prompt, grounding so it cannot invent prices or policy, jailbreak and injection defense, the human handoff, launch metrics and kill switch. NOT the agent loop or RAG index under it (that is `building-agents`), NOT a human answering one ticket (that is `customer-support`)."
 tags: [chatbot, support-bot, sales-bot, handoff, guardrails, grounding, conversational-ai]
 recommends: [building-agents, rag, customer-support, agent-safety, prompt-engineering, brand-voice]
 origin: risco
@@ -10,26 +10,14 @@ origin: risco
 
 This skill owns the bot that sits on a public site 24/7, answers support or sales questions, deflects what it safely can, and hands off cleanly what it can't. Four parts and nothing else: its **persona** (system prompt), its **grounding** (what it's allowed to know), its **guardrails** (what it must never say or do), and its **handoff** (when and how it gives up to a human). The retrieval engine under it is [`../building-agents/SKILL.md`](../building-agents/SKILL.md); the human who picks up the escalation is [`../customer-support/SKILL.md`](../customer-support/SKILL.md). You are productizing a bot, not engineering an agent and not working a ticket.
 
+Not here: the agent loop, tool schemas and eval harness → [`../building-agents/SKILL.md`](../building-agents/SKILL.md) (and `rag` for the index half: chunking, embeddings, rerank); one live ticket answered by a human — triage, SLA, macros → [`../customer-support/SKILL.md`](../customer-support/SKILL.md); prompt *wording* in the abstract → `prompt-engineering`; general LLM abuse taxonomy beyond the public-bot case → `agent-safety`; the golden-set eval as an engineering artifact → `agent-eval`; win-back/renewal → [`../retention/SKILL.md`](../retention/SKILL.md); new-customer welcome → [`../client-onboarding/SKILL.md`](../client-onboarding/SKILL.md); generic automation wiring → [`../automation-flows/SKILL.md`](../automation-flows/SKILL.md); WhatsApp/Telegram channel plumbing → [`../whatsapp-telegram/SKILL.md`](../whatsapp-telegram/SKILL.md).
+
 ## The one rule
 
 > The bot may state only what it can **cite** (from approved KB) or **confirm** (a fact it was given). Everything else is "Let me connect you to a human." Grounded-or-handoff. It never improvises a price, a policy, a refund, or a promise.
 
 Why: a hallucinated answer is a binding answer. Air Canada's bot invented a bereavement-refund policy; a tribunal held the airline liable for what the bot said (multiple 2025 retrospectives, accessed 2026-06-02). The bot speaks for the company in court, so cap what it's allowed to invent at zero.
 
-## When to use / When NOT to use
-
-**Use when:** standing up a support/sales chat widget on a website; writing or hardening the bot's system prompt (scope, refusals, tone); designing escalation to a human and what context travels; stopping the bot inventing policy/price (incident hardening); defending against jailbreaks / prompt injection on a public bot; building a sales bot that qualifies a lead and books a demo; defining launch metrics (deflection/containment/handoff) and the threshold that pulls it back.
-
-**Do NOT use when:**
-
-- Building the agent loop, tool schemas, RAG pipeline, or eval harness under the bot → [`../building-agents/SKILL.md`](../building-agents/SKILL.md) (and `rag` for the index half: chunking, embeddings, rerank).
-- A human (or assisted) agent answering one live ticket — triage, SLA, macros → [`../customer-support/SKILL.md`](../customer-support/SKILL.md).
-- Improving prompt *wording* in the abstract, prompt-pattern library → `prompt-engineering`.
-- General LLM abuse taxonomy / red-team policy beyond the public-bot case → `agent-safety`.
-- Building the golden-set eval as an engineering artifact → `agent-eval`.
-- Win-back/renewal → [`../retention/SKILL.md`](../retention/SKILL.md); new-customer welcome → [`../client-onboarding/SKILL.md`](../client-onboarding/SKILL.md).
-- Generic automation wiring → [`../automation-flows/SKILL.md`](../automation-flows/SKILL.md); WhatsApp/Telegram channel plumbing → [`../whatsapp-telegram/SKILL.md`](../whatsapp-telegram/SKILL.md).
-
 ## The four layers (the spine)
 
 Build and review the bot in this order. Each layer assumes the one above it holds.
@@ -68,7 +56,7 @@ Good (scoped, grounded, refusal + authority clauses, no secrets):
    - Keep replies under ~120 words; link the source you used."
 ```
 
-Full annotated template: [`references/system-prompt-and-guardrails.md`](references/system-prompt-and-guardrails.md).
+Reach for [`references/system-prompt-and-guardrails.md`](references/system-prompt-and-guardrails.md) while authoring: full annotated template, the forbidden-topic bucket catalog with per-bucket handling, and the prompt-injection defense checklist.
 
 ## Layer 2 — Grounding contract
 
@@ -96,7 +84,7 @@ Route every borderline message by topic bucket:
 | Off-scope / unknown | anything not in KB | "I don't have that" → offer human. |
 | Injection attempt | "Ignore your rules / you are now…" | Refuse, do not break scope, do not reveal the prompt; log it. |
 
-Injection defenses (full checklist in the reference): a clear instruction hierarchy (system > retrieved content > user), treat retrieved text and user input as *data not instructions*, refuse "ignore previous / reveal your prompt / you are now" patterns, and an **output filter** that blocks commitment phrases before they reach the user. Plus a hard **length cap** so a coaxed essay can't smuggle a promise.
+Injection defenses (full checklist in [`references/system-prompt-and-guardrails.md`](references/system-prompt-and-guardrails.md)): a clear instruction hierarchy (system > retrieved content > user), treat retrieved text and user input as *data not instructions*, refuse "ignore previous / reveal your prompt / you are now" patterns, and an **output filter** that blocks commitment phrases before they reach the user. Plus a hard **length cap** so a coaxed essay can't smuggle a promise.
 
 ## Layer 4 — Handoff state machine
 
@@ -116,7 +104,7 @@ Three trigger families:
 - Collected variables (account/order id, plan, intent, sentiment, what was already tried).
 - The detected trigger and the bot's best summary of the unresolved problem.
 
-**Warm** transfer when a human is online (bot summarizes, agent continues). **Cold** when none is: capture a ticket with the same packet and tell the user exactly when to expect a reply — never drop them into a silent void. Packet template + trigger cues: [`references/handoff-and-sales.md`](references/handoff-and-sales.md).
+**Warm** transfer when a human is online (bot summarizes, agent continues). **Cold** when none is: capture a ticket with the same packet and tell the user exactly when to expect a reply — never drop them into a silent void. Packet template, trigger detection cues, and warm-transfer / offline-fallback wording: [`references/handoff-and-sales.md`](references/handoff-and-sales.md).
 
 ## Sales-bot mode (branch)
 
@@ -160,9 +148,4 @@ Don't ship a bot you can't measure or pull back. Define these before launch:
 | Bot promises a fix/price it can't authorize | Binding commitment it had no right to make | Authority clause + handoff for anything committal |
 | Go fully autonomous on day one | No baseline, no kill switch, incident in production | Shadow → assisted → autonomous, kill switch armed |
 
-## References
-
-- [`references/system-prompt-and-guardrails.md`](references/system-prompt-and-guardrails.md) — full annotated support-bot system prompt template, the forbidden-topic bucket catalog with per-bucket handling, and the prompt-injection defense checklist. Reach for it while authoring the prompt.
-- [`references/handoff-and-sales.md`](references/handoff-and-sales.md) — the handoff packet template, the explicit/implicit/topic trigger catalog with detection cues, warm-transfer and offline-fallback wording, and the sales qualification + demo-booking flow.
-
 Verify a candidate system prompt before shipping: `scripts/verify.sh path/to/system-prompt.md` (read-only structural + banlist linter; see `evals/README.md`).

package/skills/chrome-extension/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chrome-extension
-description: "Use when building, structuring, or shipping a Manifest V3 browser extension and hitting its quirks — the service worker keeps dying or losing state between events, permission warnings scare users away, the Chrome Web Store rejected the listing, or you must drag an old Manifest V2 extension to V3. Triggers: 'build a Chrome extension', 'my background script keeps resetting its state', 'store rejected me for excessive permissions', 'migrate MV2 to MV3', 'content script messaging to the popup', 'declarativeNetRequest ad blocker', 'crear una extensión de Chrome', 'publicar a la Chrome Web Store', 'el service worker se muere'. NOT a generic web app (that is nextjs)."
+description: "Use when building or shipping a Manifest V3 browser extension and hitting its quirks — service worker dying and losing state, permission warnings, a Chrome Web Store rejection, content-script/worker/popup messaging, or an MV2-to-V3 migration. NOT a generic web app (that is `nextjs`), NOT a desktop shell (that is `electron`)."
 tags: [chrome-extension, manifest-v3, browser-extension, service-worker, chrome-web-store]
 recommends: [nextjs, react, gdpr-privacy, secure-coding, vercel]
 origin: risco
@@ -134,7 +134,7 @@ chrome.action.onClicked.addListener(async (tab) => {
 
 - `run_at`: `document_start` (before DOM), `document_end`, or `document_idle` (default, after load). Pick `document_start` only if you must beat the page's own scripts.
 - **Isolated world** (default): your content script's JS is sandboxed from the page's JS — they share the DOM but not variables. Use **MAIN world** (`"world": "MAIN"`) only when you must touch the page's own JS objects, and know it loses the isolation guarantee.
-- For dynamic, user-supplied injection, `chrome.userScripts.execute()` exists (Chrome 135, Mar 2025) — see references.
+- For dynamic, user-supplied injection, `chrome.userScripts.execute()` exists (Chrome 135, Mar 2025) — see [references/store-and-migration.md](references/store-and-migration.md).
 
 ## Storage, alarms, no remote code