@ericrisco/rsc 0.1.53 → 0.1.54

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.53",
+  "version": "0.1.54",
   "counts": {
     "skills": 258
   },
@@ -2549,7 +2549,7 @@
     },
     {
       "id": "lead-gen",
-      "description": "Use when you need to find and qualify prospects, build a target list, or score and prioritize leads before anyone reaches out — defining an ICP, sourcing named accounts/contacts from Apollo/ZoomInfo/Clay, deduping against the CRM, and ranking with a fit+intent+engagement model. Triggers: 'build me a prospect list', 'who should we sell to', 'score these leads', 'which accounts do we call first', 'tighten our ICP', 'is this cold list GDPR-safe', 'necesito una lista de clientes potenciales', 'califica estos leads', 'a qui truquem primer'. NOT writing or sending the outreach (that is cold-outreach), NOT tracking the deal after first contact (that is sales-pipeline).",
+      "description": "Use when building and qualifying a prospect list before anyone reaches out — a falsifiable ICP, named accounts/contacts from Apollo/ZoomInfo/Clay, deduped against the CRM, tiered by fit+intent+engagement. NOT writing or sending the outreach (that is cold-outreach), NOT tracking the deal after first contact (that is sales-pipeline).",
       "tags": [
         "lead-generation",
         "prospecting",
@@ -2609,7 +2609,7 @@
     },
     {
       "id": "linkedin-carousels",
-      "description": "Use when designing a LinkedIn carousel / document post — the swipeable multi-page PDF that is currently the highest-reach native LinkedIn format — and you need the slide-by-slide build: a scroll-stopping cover hook, a narrative arc that pulls swipe-to-swipe, one focused idea per slide with real visual hierarchy, a payoff + CTA closer, and a PDF export spec. Triggers: 'turn this into a LinkedIn carousel', 'design a swipeable PDF document post', 'my carousel cover gets no swipes fix the hook', 'how many slides and what goes on each', 'restructure one-idea-per-slide', 'what size to export so it isnt cropped on mobile', 'convierte este post en un carrusel de LinkedIn', 'dissenya'm un carrusel de LinkedIn amb portada i CTA'. NOT the account/format plan (that is linkedin-strategy), NOT a text or single-image feed post (that is linkedin-content), NOT a spoken-to talk deck (that is presentations).",
+      "description": "Use when building a LinkedIn carousel / document post — the swipeable multi-page PDF — slide by slide: cover hook, narrative arc, one idea per slide, CTA closer, PDF export spec. NOT the account/format plan (that is `linkedin-strategy`), NOT a text or single-image feed post (that is `linkedin-content`), NOT a 16:9 talk deck (that is `presentations`).",
       "tags": [
         "linkedin",
         "carousel",
@@ -2694,7 +2694,7 @@
     },
     {
       "id": "llm-pipeline",
-      "description": "Use when wiring several LLM calls into one production flow, when random 429s/timeouts/provider outages take a feature down, when adding a fallback model or a gateway in front of OpenAI/Claude, or when the bill explodes from uncached or flagship-everywhere calls. Triggers: 'chain these LLM calls', 'step 1 extracts step 2 summarizes', 'add a fallback if GPT fails use Claude', 'route easy requests to Haiku escalate to Opus', 'put a LiteLLM gateway in front', 'our bill tripled because we re-call the model on every request', 'semantic cache the responses', 'encadenar llamadas y cachear respuestas', 'cadena de crides a l'LLM amb fallback'. NOT prompt wording (that is prompt-engineering).",
+      "description": "Use when wiring several LLM calls into a production flow: typed contracts between steps, a router/gateway so 429s, timeouts and outages fail over instead of taking you down, and cost control via caching, model tiers and abort caps. NOT single-prompt wording (that is `prompt-engineering`), NOT a model-driven tool loop (that is `building-agents`).",
       "tags": [
         "llm-orchestration",
         "llm-gateway",
@@ -2912,7 +2912,7 @@
     },
     {
       "id": "modal",
-      "description": "Use when running Python functions or GPU workloads serverlessly on Modal — defining a modal.App with inline container Images, scaling @app.function onto CPU/GPU, persisting weights or datasets in a Volume, scheduling jobs, serving an HTTP/ASGI endpoint, or choosing modal run vs serve vs deploy. Triggers: 'run my embedding job on an H100 without managing servers', 'cache HuggingFace weights across runs', 'my @app.function GPU string errors', 'gpu=modal.gpu.A100() fails', 'modal serve isn't hot-reloading my fastapi_endpoint', 'cold start too slow / keep a warm pool', 'ejecutar Python en GPU serverless', 'desplegar un model de difusió amb GPU sense servidor i exposar-lo per HTTP'. NOT managed prediction endpoints with no infra code (that is replicate) and NOT persistent SSH-able GPU pods rented by the hour (that is runpod).",
+      "description": "Use when running Python or GPU workloads serverlessly on Modal — modal.App, inline container Images, gpu= on @app.function, Volumes for weight caching, Cron schedules, ASGI endpoints, modal run vs serve vs deploy. NOT managed prediction APIs with no container of your own (that is replicate); NOT SSH-able GPU boxes rented by the hour (that is runpod).",
       "tags": [
         "modal",
         "serverless",
@@ -3075,7 +3075,7 @@
     },
     {
       "id": "newsletter",
-      "description": "Use when running an email newsletter as a recurring publication — writing the subject line + preview text, structuring an issue so opens turn into clicks, the welcome/onboarding sequence, send cadence and engagement segmentation, growth loops (referral, signup incentive, double opt-in), and a metric scorecard that survives Apple Mail Privacy Protection. Triggers: 'write the newsletter subject line', 'my newsletter gets opened but nobody clicks', 'set up a welcome sequence', 'grow my newsletter list', 'newsletter referral program', 'how often should I send', 'what metrics matter now that opens are fake', 'click-to-open rate', 'escriu la newsletter d'aquesta setmana', 'campaña de newsletter que convierta'. NOT the one-off product launch or nurture campaign (that is marketing), NOT the SPF/DKIM/DMARC plumbing under the send (that is email-deliverability).",
+      "description": "Use when running an email newsletter as a recurring publication — subject + preview pair, issues that turn opens into clicks, the welcome sequence, cadence and engagement tiering, growth loops, and a post-Apple-MPP click scorecard. NOT one-off launch or nurture sends (that is `marketing`), NOT SPF/DKIM/DMARC (that is `email-deliverability`).",
       "tags": [
         "newsletter",
         "email",
@@ -3609,7 +3609,7 @@
     },
     {
       "id": "prompt-engineering",
-      "description": "Use when one prompt has to give the same right answer across reruns, models, and hostile inputs — a prompt that works sometimes, forcing valid JSON or a fixed schema out of a model, choosing how many few-shot examples and which ones, hardening a prompt against injected instructions, writing a tiny eval set before changing a prompt, or porting a prompt to a new model without behavior drift. Triggers: 'the prompt works sometimes', 'force valid JSON from the model', 'how many few-shot examples', 'outputs drift between reruns', 'the model ignores my instructions on long inputs', 'users can paste instructions into my input field', 'el prompt a veces falla', 'forzar JSON válido del modelo', 'el model no segueix les instruccions'. NOT the agent loop, tool wiring, or RAG retrieval (that is building-agents).",
+      "description": "Use when one prompt must give the same right answer across reruns, models, and pasted-in hostile input: forcing a fixed schema, picking the few-shot set, ordering the prompt blocks, or the inline cases you run while tuning. NOT the agent loop, tools, or retrieval (that is `building-agents`), NOT a standing CI eval harness (that is `agent-eval`).",
       "tags": [
         "prompts",
         "llm",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "0.1.53",
+  "version": "0.1.54",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/skills/lead-gen/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lead-gen
-description: "Use when you need to find and qualify prospects, build a target list, or score and prioritize leads before anyone reaches out — defining an ICP, sourcing named accounts/contacts from Apollo/ZoomInfo/Clay, deduping against the CRM, and ranking with a fit+intent+engagement model. Triggers: 'build me a prospect list', 'who should we sell to', 'score these leads', 'which accounts do we call first', 'tighten our ICP', 'is this cold list GDPR-safe', 'necesito una lista de clientes potenciales', 'califica estos leads', 'a qui truquem primer'. NOT writing or sending the outreach (that is cold-outreach), NOT tracking the deal after first contact (that is sales-pipeline)."
+description: "Use when building and qualifying a prospect list before anyone reaches out — a falsifiable ICP, named accounts/contacts from Apollo/ZoomInfo/Clay, deduped against the CRM, tiered by fit+intent+engagement. NOT writing or sending the outreach (that is cold-outreach), NOT tracking the deal after first contact (that is sales-pipeline)."
 tags: [lead-generation, prospecting, icp, lead-scoring, sales]
 recommends: [cold-outreach, sales-pipeline, market-research, data-scraper, spreadsheet-ops, email-deliverability, gdpr-privacy]
 origin: risco
@@ -8,9 +8,7 @@ origin: risco
 
 # Lead Gen — The List and the Model That Ranks It
 
-*You turn "we sell X to Y" into a deduplicated, scored, compliance-cleared roster of named accounts and people. You define the target, you build the list, you rank it — then you stop. You do not write the email and you do not run the deal.*
-
-The identity of this skill is **the list and its scoring model**, not the messages sent to it and not the pipeline it becomes. Everything you produce is a *prioritized roster + the rationale that ranked it*. The hand-off is the finish line, not the campaign.
+*You turn "we sell X to Y" into a deduplicated, scored, compliance-cleared roster of named accounts and people. You define the target, you build the list, you rank it — then you stop. What you produce is a prioritized roster plus the rationale that ranked it; the hand-off is the finish line, not the campaign.*
 
 ## The pipeline — three phases, two gates
 
@@ -151,5 +149,3 @@ This skill stops at a scored, compliance-cleared list. From there:
 - The **A/B tiers + persona context** go to `../cold-outreach/SKILL.md` — that skill writes the message and the cadence; you do not.
 - **Accepted leads** (worked and responsive) go to `../sales-pipeline/SKILL.md` — that skill tracks stages, forecasts, and manages the deal; you do not.
 - If the request is really "how big is this market / which segment?" with no named list, that is `../market-research/SKILL.md`, not this skill.
-
-When the deliverable would be a message, a pipeline stage, or a market sizing — route. Your job ended at the ranked roster.

package/skills/lead-gen/evals/cases.yaml

@@ -10,9 +10,9 @@ should_trigger:
   - prompt: "Is this cold prospect list legal to email under GDPR before we send?"
     why: "The compliance gate (GDPR LIA, no scraped basis) is part of making a list ship-ready — non-obvious that lead-gen owns it, not a generic legal skill."
   - prompt: "Necesito una lista de clientes potenciales para nuestro SaaS de logística."
-    why: "Spanish core trigger — build a target list of prospects."
+    why: "Spanish-language phrasing of the core case — build a target list of prospects."
   - prompt: "A qui de la nostra base truquem primer, tenim 300 comptes sense prioritzar?"
-    why: "Catalan trigger — scoring/tiering an unprioritized account list."
+    why: "Catalan-language phrasing — scoring/tiering an unprioritized account list."
 
 should_not_trigger:
   - prompt: "Write the cold email sequence for these prospects."

package/skills/linkedin-carousels/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: linkedin-carousels
-description: "Use when designing a LinkedIn carousel / document post — the swipeable multi-page PDF that is currently the highest-reach native LinkedIn format — and you need the slide-by-slide build: a scroll-stopping cover hook, a narrative arc that pulls swipe-to-swipe, one focused idea per slide with real visual hierarchy, a payoff + CTA closer, and a PDF export spec. Triggers: 'turn this into a LinkedIn carousel', 'design a swipeable PDF document post', 'my carousel cover gets no swipes fix the hook', 'how many slides and what goes on each', 'restructure one-idea-per-slide', 'what size to export so it isnt cropped on mobile', 'convierte este post en un carrusel de LinkedIn', 'dissenya'm un carrusel de LinkedIn amb portada i CTA'. NOT the account/format plan (that is linkedin-strategy), NOT a text or single-image feed post (that is linkedin-content), NOT a spoken-to talk deck (that is presentations)."
+description: "Use when building a LinkedIn carousel / document post — the swipeable multi-page PDF — slide by slide: cover hook, narrative arc, one idea per slide, CTA closer, PDF export spec. NOT the account/format plan (that is `linkedin-strategy`), NOT a text or single-image feed post (that is `linkedin-content`), NOT a 16:9 talk deck (that is `presentations`)."
 tags: [linkedin, carousel, document-post, slide-design, visual-hierarchy, hook, b2b, social-content]
 recommends: [linkedin-content, linkedin-strategy, brand-identity, brand-voice, presentations, social-publisher]
 origin: risco
@@ -8,16 +8,10 @@ origin: risco
 
 # LinkedIn carousels
 
-Design **one swipeable LinkedIn document post**: the cover hook, the narrative arc, one idea
-per slide, and the PDF export spec. You hand back a slide-by-slide build ready to assemble in
-Canva/Figma/Slides and a one-page design+export checklist.
-
-You do not own the account plan (which formats, cadence, niche — that is
-[`../linkedin-strategy/SKILL.md`](../linkedin-strategy/SKILL.md)), the words of a text or
-single-image feed post ([`../linkedin-content/SKILL.md`](../linkedin-content/SKILL.md)), the
-programmatic upload ([`../linkedin-api/SKILL.md`](../linkedin-api/SKILL.md)), or a spoken-to
-16:9 talk deck ([`../presentations/SKILL.md`](../presentations/SKILL.md)). Your artifact is the
-*slides of a phone-read PDF* — sequence and visual hierarchy are the product.
+Design **one swipeable LinkedIn document post**. Your artifact is the *slides of a phone-read
+PDF* — sequence and visual hierarchy are the product — handed back as a slide-by-slide build
+ready to assemble in Canva/Figma/Slides plus a one-page design+export checklist. Everything
+adjacent (the account plan, the feed copy, the upload, a talk deck) routes out; see Handoffs.
 
 ## What you produce
 
@@ -27,34 +21,30 @@ programmatic upload ([`../linkedin-api/SKILL.md`](../linkedin-api/SKILL.md)), or
 - **A design + export spec** — canvas, safe area, type floor, PDF checklist (one page).
 - **A one-line caption starter** — the first feed line; full caption tuning routes out.
 
-Precondition: you need a topic, an angle, or a source (post/article). If the ask is the
-account plan or a block of feed copy, you are in the wrong skill — see the handoffs table.
+Precondition: a topic, an angle, or a source (post/article). If the ask is the account plan or
+a block of feed copy, you are in the wrong skill — see the handoffs table.
 
 ## Ground first
 
-A carousel inherits an identity; it does not invent one. Before you design slides:
-
-- **Read the brand kit** if it exists in `02-DOCS/` (colors, type, logo) —
-  [`../brand-identity/SKILL.md`](../brand-identity/SKILL.md) owns it. Don't pick arbitrary fonts.
-- **Read the voice** so the headlines sound like the account —
-  [`../brand-voice/SKILL.md`](../brand-voice/SKILL.md) owns it.
-- **Pull the angle** from any plan/post already produced by
-  [`../linkedin-strategy/SKILL.md`](../linkedin-strategy/SKILL.md) or
-  [`../linkedin-content/SKILL.md`](../linkedin-content/SKILL.md). Reuse the hook, don't reopen it.
-
-If none exist, name your assumptions on slide 0 of the spec and proceed — don't stall.
+A carousel inherits an identity; it does not invent one. Read the brand kit (colors, type,
+logo — owned by [`../brand-identity/SKILL.md`](../brand-identity/SKILL.md)) and the voice
+([`../brand-voice/SKILL.md`](../brand-voice/SKILL.md)) from `02-DOCS/` if they exist; don't pick
+arbitrary fonts. Pull the angle from any plan or post already produced by
+[`../linkedin-strategy/SKILL.md`](../linkedin-strategy/SKILL.md) or
+[`../linkedin-content/SKILL.md`](../linkedin-content/SKILL.md) — reuse the hook, don't reopen
+it. If none exist, name your assumptions on slide 0 of the spec and proceed; don't stall.
 
 ## The swipe economics (why every rule below exists)
 
 Document/carousel posts are the **highest-engagement native format on LinkedIn right now** —
-they hit roughly 6.6% average engagement, ahead of every other format, and top-performing
-pages post far more of them than median pages. The reason is **dwell time**: a swipeable deck
-holds the thumb on screen, and dwell — not likes — is the algorithm's main distribution signal.
+roughly 6.6% average engagement, ahead of every other format, and top-performing pages post far
+more of them than median pages. The reason is **dwell time**: a swipeable deck holds the thumb
+on screen, and dwell — not likes — is the algorithm's main distribution signal.
 
 So the whole bet is the **cover slide and the swipe-to-slide-2 bounce**. If the cover doesn't
-earn the first swipe, your slide count, your arc, and your CTA never get seen. Every swipe
-after that extends dwell and signals quality, which is why each slide must *pull to the next*.
-Design backwards from that: stop the thumb, then keep it moving.
+earn the first swipe, your slide count, your arc, and your CTA never get seen; every swipe after
+that extends dwell and signals quality, which is why each slide must *pull to the next*. Design
+backwards from that: stop the thumb, then keep it moving.
 
 ## The cover slide
 
@@ -150,11 +140,10 @@ Good — one idea, one dominant element, breathing room
 ## Slide count
 
 Aim for the **6–12 band, ~8 as the sweet spot** (cover + ~6 content + CTA). Reported peaks
-cluster around 7–8 slides; 8–12 is where the highest dwell/save/share rates show up. Fewer
-than 5 underdelivers (not worth the swipe); more than ~15 loses people before the payoff.
-
-Treat the band as a guide, not a law: **length follows the arc, not a quota.** If the arc
-resolves in 7 slides, ship 7 — don't pad to hit a number.
+cluster around 7–8 slides; 8–12 is where the highest dwell/save/share rates show up. Fewer than
+5 underdelivers (not worth the swipe); more than ~15 loses people before the payoff. Treat the
+band as a guide, not a law: **length follows the arc, not a quota** — if the arc resolves in 7
+slides, ship 7, don't pad to hit a number.
 
 ## The CTA closer
 
@@ -184,17 +173,17 @@ Gotchas:   open the exported PDF and verify fonts — free Canva silently substi
 ```
 
 Portrait 4:5 takes the most vertical space in a mobile feed, which raises dwell and the chance
-of a scroll-stop. PDF is the only export that preserves fonts and layout reliably across
-devices — exporting slides as images loses crispness and breaks selectable text. The full
+of a scroll-stop; PDF is the only export that preserves fonts and layout reliably across
+devices, since slides exported as images lose crispness and break selectable text. The full
 checklist in prose is in [`references/carousel-patterns.md`](references/carousel-patterns.md).
 
 ## The feed caption handoff
 
 A document post still has a **text caption above it**, and its first 1–2 lines (before the
 "…more" fold) must restate the cover hook — that line is what people read before deciding to
-expand and swipe. Give a one-line starter that echoes the cover, then route full feed-copy
-length/tone tuning to [`../linkedin-content/SKILL.md`](../linkedin-content/SKILL.md). You own
-the slides; that sibling owns the caption.
+expand and swipe. Give a one-line starter that echoes the cover; you own the slides, and
+[`../linkedin-content/SKILL.md`](../linkedin-content/SKILL.md) owns the caption's full
+length/tone tuning.
 
 ## Handoffs
 
@@ -202,7 +191,7 @@ the slides; that sibling owns the caption.
 |---|---|
 | The account/format plan, cadence, niche, who to target | [`../linkedin-strategy/SKILL.md`](../linkedin-strategy/SKILL.md) |
 | A text or single-image feed post (just the copy) | [`../linkedin-content/SKILL.md`](../linkedin-content/SKILL.md) |
-| 1:1 DMs / connection-request outreach sequences | `linkedin-outreach` |
+| 1:1 DMs / connection-request outreach sequences | [`../linkedin-outreach/SKILL.md`](../linkedin-outreach/SKILL.md) |
 | To publish/schedule the deck via the LinkedIn API | [`../linkedin-api/SKILL.md`](../linkedin-api/SKILL.md) |
 | A spoken-to 16:9 talk deck (speaker support) | [`../presentations/SKILL.md`](../presentations/SKILL.md) |
 | The color / type / logo brand kit the deck is styled in | [`../brand-identity/SKILL.md`](../brand-identity/SKILL.md) |
@@ -236,4 +225,4 @@ scripts/verify.sh path/to/carousel-spec.md
 It checks (read-only) for a labeled cover slide, a slide count in 5–15 (warns outside 6–12), a
 CTA slide with an explicit ask, a portrait/square canvas, a ≥28 px type floor, "PDF" as the
 export target, and warns on any crammed (3+ bullet) interior slide. An empty or clean target
-passes. The deeper rigor is the capability eval in `evals/`.
+passes.

package/skills/llm-pipeline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: llm-pipeline
-description: "Use when wiring several LLM calls into one production flow, when random 429s/timeouts/provider outages take a feature down, when adding a fallback model or a gateway in front of OpenAI/Claude, or when the bill explodes from uncached or flagship-everywhere calls. Triggers: 'chain these LLM calls', 'step 1 extracts step 2 summarizes', 'add a fallback if GPT fails use Claude', 'route easy requests to Haiku escalate to Opus', 'put a LiteLLM gateway in front', 'our bill tripled because we re-call the model on every request', 'semantic cache the responses', 'encadenar llamadas y cachear respuestas', 'cadena de crides a l'LLM amb fallback'. NOT prompt wording (that is prompt-engineering)."
+description: "Use when wiring several LLM calls into a production flow: typed contracts between steps, a router/gateway so 429s, timeouts and outages fail over instead of taking you down, and cost control via caching, model tiers and abort caps. NOT single-prompt wording (that is `prompt-engineering`), NOT a model-driven tool loop (that is `building-agents`)."
 tags: [llm-orchestration, llm-gateway, fallbacks, prompt-caching, cost-control, litellm, reliability]
 recommends: [prompt-engineering, structured-extraction, building-agents, cost-tracking, agent-eval, rag, observability, parallel]
 origin: risco
@@ -10,14 +10,7 @@ origin: risco
 
 Wire multiple LLM calls into a reliable, controllable production pipeline. You chain steps where one call's validated output feeds the next, put a router in front of providers so an outage fails over instead of taking you down, and engineer the cross-cutting concerns: timeouts, bounded retries, fallbacks, caching, and cost caps.
 
-## Core stance
-
-Treat the LLM as an unreliable network dependency, not a local function call. Everything below follows from that.
-
-- **Every call gets a hard timeout and bounded retries.** Providers have outages, rate limits, and latency tails; a naked call can hang your whole request behind one slow upstream.
-- **Steps pass validated structured objects, not free text.** The output of step N is a contract you assert on before it becomes step N+1's input — a parse failure is caught at the seam, not three steps later.
-- **A router sits in front of every provider.** One model's 429/500/timeout fails over to another; no single provider is a single point of failure.
-- **Cache and tier before you tune prompts.** The cheapest, fastest, most reliable call is the one you never made. Prompt wording is the last lever, not the first.
+Treat the LLM as an unreliable network dependency, not a local function call. Every rule below follows from that: providers have outages, rate limits, and latency tails, so no single provider is a single point of failure and no call is allowed to run unbounded.
 
 ## Do you even need a pipeline?
 
@@ -116,6 +109,8 @@ except Exception:
 
 ## Caching: two distinct layers
 
+The cheapest, fastest, most reliable call is the one you never made — so cache and tier before you tune prompts. Wording is the last lever, not the first.
+
 | Layer | What it matches | Safety | Enable when |
 | --- | --- | --- | --- |
 | Prefix / prompt cache (provider-native) | Exact prefix of the prompt | Always safe (same input → same cached compute) | Always; put the stable prefix first |

package/skills/modal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: modal
-description: "Use when running Python functions or GPU workloads serverlessly on Modal — defining a modal.App with inline container Images, scaling @app.function onto CPU/GPU, persisting weights or datasets in a Volume, scheduling jobs, serving an HTTP/ASGI endpoint, or choosing modal run vs serve vs deploy. Triggers: 'run my embedding job on an H100 without managing servers', 'cache HuggingFace weights across runs', 'my @app.function GPU string errors', 'gpu=modal.gpu.A100() fails', 'modal serve isn't hot-reloading my fastapi_endpoint', 'cold start too slow / keep a warm pool', 'ejecutar Python en GPU serverless', 'desplegar un model de difusió amb GPU sense servidor i exposar-lo per HTTP'. NOT managed prediction endpoints with no infra code (that is replicate) and NOT persistent SSH-able GPU pods rented by the hour (that is runpod)."
+description: "Use when running Python or GPU workloads serverlessly on Modal — modal.App, inline container Images, gpu= on @app.function, Volumes for weight caching, Cron schedules, ASGI endpoints, modal run vs serve vs deploy. NOT managed prediction APIs with no container of your own (that is replicate); NOT SSH-able GPU boxes rented by the hour (that is runpod)."
 tags: [modal, serverless, gpu, python, ai-infra, deployment, cron, web-endpoint]
 recommends: [replicate, runpod, fastapi, docker, python, llm-pipeline]
 origin: risco
@@ -19,27 +19,19 @@ Pinned stack: **modal 1.4.3** (released 2026-05-18), Python **3.10–3.14** (`>=
 Install with `pip install modal` then `modal setup` to authenticate. Everything below uses
 the Modal 1.0+ API; several pre-1.0 forms were removed and are called out as Bad→Good.
 
-## When to use
+## Not this skill
 
-- Running a Python function or batch job on remote CPU/GPU with no server to manage.
-- GPU inference, fine-tuning, or model serving (vLLM, diffusion, embeddings) on T4…B200.
-- Building a container image inline (`Image.debian_slim().uv_pip_install(...)`) for a remote job.
-- Persisting model weights or datasets across runs with a Modal `Volume`.
-- Scheduled jobs (nightly report, periodic scrape) via `modal.Cron` / `modal.Period`.
-- Exposing a function over HTTP (`fastapi_endpoint`, `asgi_app`, `wsgi_app`, `web_server`).
-- Fan-out parallelism with `.map()` / `.starmap()` / `.spawn()`.
+Modal owns the serverless-container-as-decorators surface and its CLI lifecycle; the *contents*
+of your function belong elsewhere.
 
-## When NOT to use
-
-- Calling a **managed prediction API** with no container of your own → **`replicate`** / `together-fireworks` / `fal`.
-- Renting a **persistent, SSH-able GPU box** by the hour/week → **`runpod`**.
-- Generic **FastAPI design** (routing, Pydantic, deps) independent of host → **`fastapi`**.
-- Writing a **Dockerfile** for a registry / k8s / Compose → **`docker`**.
-- General **Python language/runtime** questions → **`python`**.
-- **RAG / LLM pipeline** orchestration logic itself → **`llm-pipeline`**.
-
-Modal owns the serverless-container-as-decorators surface and its CLI lifecycle; the
-*contents* of your function (FastAPI app, RAG chain) belong to the siblings above.
+| The job | Goes to |
+|---|---|
+| Calling a **managed prediction API** with no container of your own | [`replicate`](../replicate/SKILL.md) / [`together-fireworks`](../together-fireworks/SKILL.md) / [`fal`](../fal/SKILL.md) |
+| Renting a **persistent, SSH-able GPU box** by the hour/week | [`runpod`](../runpod/SKILL.md) |
+| **FastAPI design** (routing, Pydantic, deps) independent of host | [`fastapi`](../fastapi/SKILL.md) |
+| Writing a **Dockerfile** for a registry / k8s / Compose | [`docker`](../docker/SKILL.md) |
+| General **Python language/runtime** questions | [`python`](../python/SKILL.md) |
+| **RAG / LLM pipeline** orchestration logic itself | [`llm-pipeline`](../llm-pipeline/SKILL.md) |
 
 ## Decision: which entrypoint?
 
@@ -109,8 +101,8 @@ image = (
 )
 ```
 
-`→ references/images-gpu-cookbook.md` for vLLM / torch+CUDA / diffusers recipes and the
-download-once weight-cache pattern.
+→ [`references/images-gpu-cookbook.md`](references/images-gpu-cookbook.md) for vLLM / torch+CUDA
+/ diffusers recipes and the download-once weight-cache pattern.
 
 ## GPU — it's a string now
 
@@ -193,8 +185,7 @@ def pull():
 ```
 
 Never bake a token into the image (`.run_commands("export TOKEN=...")`) — it's recorded in
-layer history. Use a Secret. `→ references/images-gpu-cookbook.md` for the weight-cache and
-HF/OpenAI secret patterns.
+layer history. Use a Secret. The cookbook above also carries the HF/OpenAI secret patterns.
 
 ## Web endpoints
 
@@ -228,8 +219,8 @@ def web():
 
 Develop with `modal serve app.py` (hot-reload); ship with `modal deploy app.py` (stable URL).
 For custom domains, proxy-auth tokens, batching (`@modal.batched`), and concurrency tuning →
-`references/web-and-scaling.md`. For the FastAPI app's *own* design (routes, Pydantic, deps),
-that's the `fastapi` sibling — this skill only mounts it.
+[`references/web-and-scaling.md`](references/web-and-scaling.md). For the FastAPI app's *own*
+design (routes, Pydantic, deps), that's [`fastapi`](../fastapi/SKILL.md) — this skill only mounts it.
 
 ## Scheduled jobs
 
@@ -268,9 +259,9 @@ def main():
 they complete (faster when latencies vary). Combine with `retries=` on the function so a
 single bad input doesn't sink the batch.
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization | Reality → STOP |
+| Anti-pattern | Do instead |
 |---|---|
 | "I'll use `gpu=modal.gpu.A100()` like the old docs" | Removed in 1.0. Use the string `gpu="A100-80GB"`. |
 | "Attach a GPU, it might speed up this CPU job" | GPU is billed per second alive. CPU-only job → no `gpu=`. |
@@ -279,30 +270,21 @@ single bad input doesn't sink the batch.
 | "`modal run` it, the endpoint/schedule will stay up" | `run` is ephemeral; it exits. Use `modal deploy` for anything persistent. |
 | "Order the decorators however — Modal figures it out" | `@app.function` outermost, web decorator innermost. Wrong order errors. |
 | "Bake the HF token into the image with `run_commands`" | Leaks into layer history. Use `modal.Secret.from_name(...)`. |
-| "Just call the model via a managed API through Modal" | If you write no container, that's a managed-API job → `replicate`. |
-| "I need a box to SSH into for a week" | That's a persistent rental → `runpod`, not Modal's scale-to-zero. |
+| "Just call the model via a managed API through Modal" | If you write no container, that's a managed-API job → [`replicate`](../replicate/SKILL.md). |
+| "I need a box to SSH into for a week" | That's a persistent rental → [`runpod`](../runpod/SKILL.md), not Modal's scale-to-zero. |
 | "Set `min_containers` high so it's always fast" | Idle warm containers cost money 24/7. Tune `scaledown_window` first. |
 
-## verify.sh
+## Verify
 
-`scripts/verify.sh [TARGET]` statically lints the nearest emitted Modal `*.py`: it requires a
-`modal.App(`, **fails** if the removed `modal.gpu.` object form appears, checks that any web
-decorator sits under an `@app.function`, and that any `Volume` uses
+[`scripts/verify.sh`](scripts/verify.sh) `[TARGET]` statically lints the nearest emitted Modal
+`*.py`: it requires a `modal.App(`, **fails** if the removed `modal.gpu.` object form appears,
+checks that any web decorator sits under an `@app.function`, and that any `Volume` uses
 `from_name(..., create_if_missing=...)`. It runs `python -c "import modal"` only if modal is
-installed (skip-pass otherwise) and needs **no Modal credentials**. On an empty/clean target it
-exits 0.
-
-## Project grounding (02-DOCS + CLAUDE.md)
-
-In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki), record this
-app's real Modal choices — GPU types, image base, Volume names, schedule, endpoint shape — in
-`02-DOCS/wiki/stack/modal.md` and index it in `02-DOCS/wiki/index.md` (the Knowledge map; root
-`CLAUDE.md` keeps only a short pointer to it). Read it
-first on every use; create/update it with the real decisions. No `02-DOCS/`? Skip silently.
+installed (skip-pass otherwise), needs **no Modal credentials**, and exits 0 on an empty target.
 
-## See Also
+## Project grounding (02-DOCS)
 
-- [`fastapi`](../fastapi/SKILL.md) — the design of the FastAPI app you mount behind `@modal.asgi_app()`.
-- References: [`references/images-gpu-cookbook.md`](references/images-gpu-cookbook.md), [`references/web-and-scaling.md`](references/web-and-scaling.md).
-- Verify gate: [`scripts/verify.sh`](scripts/verify.sh).
-- Siblings (catalog): `replicate` / `together-fireworks` / `fal` (managed prediction APIs), `runpod` (persistent GPU pods), `docker` (Dockerfiles), `python` (language), `llm-pipeline` (orchestration).
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki), read
+`02-DOCS/wiki/stack/modal.md` first, then record this app's real Modal choices there — GPU types,
+image base, Volume names, schedule, endpoint shape — and index it in `02-DOCS/wiki/index.md`. No
+`02-DOCS/`? Skip silently.

package/skills/newsletter/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: newsletter
-description: "Use when running an email newsletter as a recurring publication — writing the subject line + preview text, structuring an issue so opens turn into clicks, the welcome/onboarding sequence, send cadence and engagement segmentation, growth loops (referral, signup incentive, double opt-in), and a metric scorecard that survives Apple Mail Privacy Protection. Triggers: 'write the newsletter subject line', 'my newsletter gets opened but nobody clicks', 'set up a welcome sequence', 'grow my newsletter list', 'newsletter referral program', 'how often should I send', 'what metrics matter now that opens are fake', 'click-to-open rate', 'escriu la newsletter d'aquesta setmana', 'campaña de newsletter que convierta'. NOT the one-off product launch or nurture campaign (that is marketing), NOT the SPF/DKIM/DMARC plumbing under the send (that is email-deliverability)."
+description: "Use when running an email newsletter as a recurring publication — subject + preview pair, issues that turn opens into clicks, the welcome sequence, cadence and engagement tiering, growth loops, and a post-Apple-MPP click scorecard. NOT one-off launch or nurture sends (that is `marketing`), NOT SPF/DKIM/DMARC (that is `email-deliverability`)."
 tags: [newsletter, email, growth, copywriting, retention-metrics]
 recommends: [marketing, email-deliverability, brand-voice, landing-copy, ab-testing]
 profiles: []
@@ -11,29 +11,19 @@ origin: risco
 
 Run the newsletter as a **product you ship on a cadence**, not a one-off send. The job is the system around the recurring issue: the subject + preview that earns the open, the issue body that earns the click, the welcome sequence that activates a new subscriber, the cadence and segmentation that keep the list healthy, the growth loops that compound it, and a scorecard that still tells the truth after Apple broke open rates. Every send is one episode of an ongoing show — design the show, not the episode.
 
-## When to use
-
-- Writing the subject line + preview text for an issue and fitting them to inbox truncation.
-- Structuring a recurring issue so opens convert: hook on the first screen, scannable body, one CTA.
-- Writing the welcome / onboarding sequence a confirmed subscriber gets.
-- Planning send cadence, frequency, and engagement-based segmentation.
-- Designing a growth loop: referral program, signup incentive / lead magnet, double opt-in.
-- Choosing which metrics to trust now that Apple MPP inflates opens; building the scorecard.
-- Rescuing a newsletter with high opens but no clicks, or a quietly decaying engaged-reader count.
-
 ## When NOT to use — route instead
 
 | The ask | Route to |
 |---|---|
 | One-off product launch announcement or campaign drip nurture | `../marketing/SKILL.md` |
-| Mail lands in spam; set up SPF / DKIM / DMARC, tracking domain, reputation | `email-deliverability` |
+| Mail lands in spam; set up SPF / DKIM / DMARC, tracking domain, reputation | `../email-deliverability/SKILL.md` |
 | Write the subscribe / opt-in landing page copy | `../landing-copy/SKILL.md` |
 | Define the house voice, tone, and vocabulary the newsletter speaks in | `../brand-voice/SKILL.md` |
-| Win back / reactivate lapsed *paying customers* (lifecycle, not readers) | `retention` |
+| Win back / reactivate lapsed *paying customers* (lifecycle, not readers) | `../retention/SKILL.md` |
 | Produce the underlying long-form articles the issue links out to | `../content-engine/SKILL.md` |
-| Sample size / significance / MDE math for the test itself | `ab-testing` |
-| Source or scrape new contacts; prospect an un-opted-in list | `lead-gen`, `../cold-outreach/SKILL.md` |
-| Actually wire the send through an ESP / Gmail API and schedule it | `email-connector`, `google-workspace` |
+| Sample size / significance / MDE math for the test itself | `../ab-testing/SKILL.md` |
+| Source or scrape new contacts; prospect an un-opted-in list | `../lead-gen/SKILL.md`, `../cold-outreach/SKILL.md` |
+| Actually wire the send through an ESP / Gmail API and schedule it | `../email-connector/SKILL.md`, `../google-workspace/SKILL.md` |
 
 You own the *recurring opted-in publication and its open/click/growth system*. The plumbing under every send and the page that captures the signup are someone else's.
 
@@ -81,7 +71,7 @@ The subject and the preview (preheader) ship together and are tested together
 - **Payload in the first ~33 characters**; keep the whole subject ~30–50 chars (≈7–9 words) so it survives mobile truncation.
 - **The preview extends the subject, it never repeats it.** Its first ~35–50 chars are prime real estate; waste them on a duplicate and you've burned the line.
 - **≤2 emojis, at the end, never an all-emoji subject** — an all-emoji subject is the one case that actually trips filters.
-- **The "spam trigger words" list is a myth.** "Free", "guarantee", a normal emoji — these do not sink you; authentication and sender reputation dominate deliverability. Police reputation, not vocabulary; the reputation/auth layer lives in `email-deliverability`.
+- **The "spam trigger words" list is a myth.** "Free", "guarantee", a normal emoji — these do not sink you; authentication and sender reputation dominate deliverability. Police reputation, not vocabulary; the reputation/auth layer lives in `../email-deliverability/SKILL.md`.
 
 ```text
 Bad (payload past char 33, preview repeats subject):
@@ -134,13 +124,13 @@ A newsletter is the canonical bulk marketing message, so the Gmail/Yahoo bulk-se
 - **RFC 8058 one-click unsubscribe** (`List-Unsubscribe` + `List-Unsubscribe-Post` headers) on every send, plus a **visible footer unsubscribe link.** Both, always.
 - **Keep the spam-complaint rate under 0.1%** and never let it reach 0.3%. This is why you sunset, not why you mail harder.
 
-The DNS / authentication side of those rules — SPF, DKIM, DMARC, the sending domain — is **not this skill**; that is `email-deliverability`. This skill applies the rules to the issue and the cadence.
+The DNS / authentication side of those rules — SPF, DKIM, DMARC, the sending domain — is **not this skill**; that is `../email-deliverability/SKILL.md`. This skill applies the rules to the issue and the cadence.
 
 ## A/B testing the right way
 
 - **Test exactly one element at a time** — subject vs subject, or preview vs preview. Change two and the winner is uninterpretable.
 - **Put preview text in the rotation**, not just the subject; it's half the inbox row and usually under-tested.
-- The statistical design — sample size, significance, minimum detectable effect — is `ab-testing`. This skill tells you *what* to test; that one tells you whether the result is real.
+- The statistical design — sample size, significance, minimum detectable effect — is `../ab-testing/SKILL.md`. This skill tells you *what* to test; that one tells you whether the result is real.
 
 ## Anti-patterns
 
@@ -151,7 +141,7 @@ The DNS / authentication side of those rules — SPF, DKIM, DMARC, the sending d
 | Preview text repeats the subject | Burns half the inbox row on a duplicate | Preview extends the subject with new info |
 | Mailing a decaying list harder | Complaints climb; reputation and inbox placement collapse | Sunset / re-permission the dormant tier |
 | All-emoji subject line | The one emoji case that actually trips filters | ≤2 emojis, at the end, around real words |
-| Policing "spam trigger words" | A myth; reputation/auth decide deliverability | Fix auth + reputation in `email-deliverability` |
+| Policing "spam trigger words" | A myth; reputation/auth decide deliverability | Fix auth + reputation in `../email-deliverability/SKILL.md` |
 | Buying a list / no double opt-in | Spam traps and complaints gate the whole sender | Double opt-in; grow with referral + lead magnet |
 | Testing two variables at once | Winner is uninterpretable | One variable; preview in the rotation |
 | Referral ask bolted on months later | Misses peak engagement | Put the ask inside the welcome sequence |

package/skills/newsletter/references/growth-loops.md

@@ -23,7 +23,7 @@ tiering. Numbers below are dated; treat them as calibration, not promises.
   generic "join our newsletter."
 - The asset doubles as shareable bait for the referral loop — make it good
   enough to forward.
-- The opt-in *page* and its copy are `../landing-copy/SKILL.md`; this skill owns
+- The opt-in *page* and its copy are `../../landing-copy/SKILL.md`; this skill owns
   what the incentive is and how it ties into the welcome + referral flow.
 
 ## Opt-in: single vs double
@@ -64,10 +64,10 @@ this? click to stay") and, if no click, a **sunset** off the active list.
   is the lever that protects it. (Yahoo Sender Hub best practices; Google
   Workspace sender guidelines — accessed 2026-06-02.)
 - Re-permission is a newsletter-list hygiene step. Lifecycle reactivation of
-  lapsed *paying customers* is a different job — that is `retention`.
+  lapsed *paying customers* is a different job — that is `../../retention/SKILL.md`.
 
 ## Send-time hypothesis
 
 Tuesday/Thursday ~10am or 1–3pm is the cross-industry baseline starting point.
 It is a hypothesis to test against your own list's click data, never a fixed law.
-The test design (sample size, significance) is `ab-testing`.
+The test design (sample size, significance) is `../../ab-testing/SKILL.md`.

package/skills/prompt-engineering/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prompt-engineering
-description: "Use when one prompt has to give the same right answer across reruns, models, and hostile inputs — a prompt that works sometimes, forcing valid JSON or a fixed schema out of a model, choosing how many few-shot examples and which ones, hardening a prompt against injected instructions, writing a tiny eval set before changing a prompt, or porting a prompt to a new model without behavior drift. Triggers: 'the prompt works sometimes', 'force valid JSON from the model', 'how many few-shot examples', 'outputs drift between reruns', 'the model ignores my instructions on long inputs', 'users can paste instructions into my input field', 'el prompt a veces falla', 'forzar JSON válido del modelo', 'el model no segueix les instruccions'. NOT the agent loop, tool wiring, or RAG retrieval (that is building-agents)."
+description: "Use when one prompt must give the same right answer across reruns, models, and pasted-in hostile input: forcing a fixed schema, picking the few-shot set, ordering the prompt blocks, or the inline cases you run while tuning. NOT the agent loop, tools, or retrieval (that is `building-agents`), NOT a standing CI eval harness (that is `agent-eval`)."
 tags: [prompts, llm, few-shot, structured-output, evals]
 recommends: [building-agents, agent-eval, structured-extraction]
 origin: risco
@@ -10,12 +10,6 @@ origin: risco
 
 You are tuning a single prompt so it produces the same correct output across reruns, across models, and against adversarial input. This is the craft layer — the prompt artifact itself: its block order, its few-shot set, its output contract, and the small eval that proves it. The systems layer (loop, tools, retrieval) is `../building-agents/SKILL.md`.
 
-## The one rule
-
-> A prompt is not done until it passes a small eval set you wrote **before** you started tuning. Without cases you are fiddling — changing words and trusting a vibe. With 5-15 cases, every edit is a measurement.
-
-Write the cases first. They define "right answer" before you fall in love with a phrasing.
-
 ## Prompt skeleton (this order)
 
 Order the blocks so the model reads identity and task before it sees the (untrusted) input. Each block earns its place:
@@ -86,11 +80,11 @@ Good (range: normal / awkward / edge):
 - **Re-state the task after the input** for long inputs. Why: when the input is huge, early instructions fall out of attention — this is the cause of "the model ignores my instructions on long inputs".
 - **Phrase constraints positively.** "Output only the category" survives; "don't add commentary" invites the model to negotiate.
 - **Add a refusal anchor** — one explicit branch for out-of-contract input (`If the ticket is empty or unreadable, output: other`). Why: undefined behavior is where injections and drift live.
-- System-scope abuse handling — refusal policy, monitoring, jailbreak defense across a product — is `agent-safety`, not this skill. Here you harden one prompt.
+- System-scope abuse handling — refusal policy, monitoring, jailbreak defense across a product — is `../agent-safety/SKILL.md`, not this skill. Here you harden one prompt.
 
-## Inline evals (the part people skip)
+## Inline evals — write these first
 
-Build 5-15 cases next to the prompt and run them before AND after every change.
+A prompt is not done until it passes a small eval set you wrote **before** you started tuning: 5-15 cases next to the prompt, run before AND after every change. Cases fix what "right answer" means before you fall in love with a phrasing — without them you are fiddling, changing words and trusting a vibe; with them every edit is a measurement.
 
 ```yaml
 # prompt-eval cases for the triage prompt
@@ -112,7 +106,7 @@ cases:
     expect: { equals: "billing" }   # input treated as data, not command
 ```
 
-Assert on the contract: schema-valid, exact token, contains/not-contains. Keep them in the repo beside the prompt. The standing harness — golden set, LLM-as-judge, CI regression gate, metrics — is `agent-eval`; this is the small inline set you run while tuning.
+Assert on the contract: schema-valid, exact token, contains/not-contains. Keep them in the repo beside the prompt; `references/eval-templates.md` has the cases.yaml shape, assertion helpers, and a before/after diff runner. The standing harness — golden set, LLM-as-judge, CI regression gate, metrics — is `../agent-eval/SKILL.md`; this is the small inline set you run while tuning.
 
 ## Iterate one variable at a time
 
@@ -131,8 +125,3 @@ Assert on the contract: schema-valid, exact token, contains/not-contains. Keep t
 | 3 near-identical few-shot examples | Teaches one shape, wastes tokens | 3 deliberately different: normal / awkward / edge |
 | Negative-only constraints ("don't…") | Invites negotiation, ignored on long input | Phrase positively; re-state task after long input |
 | Tuning by vibe, no cases | You are fiddling, not engineering | Write 5-15 cases first; measure each edit |
-
-## References
-
-- `references/output-contracts.md` — per-provider strict-output recipes, schema surface (pydantic/zod), streaming caveat, retry-on-parse-fail loop.
-- `references/eval-templates.md` — cases.yaml shape, assertion helpers, before/after diff runner, DSPy MIPROv2-vs-GEPA when-to-optimize note.

package/skills/prompt-engineering/evals/cases.yaml

@@ -10,7 +10,7 @@ should_trigger:
   - prompt: "Make this prompt enforce a fixed schema reliably instead of sometimes returning prose."
     why: "Forcing a fixed schema out of a model — the output-contract decision table (strict json_schema / strict tool use vs JSON mode)."
   - prompt: "Write me a small eval set to check this prompt before I change it."
-    why: "Inline eval set authored before tuning — 'the one rule' of the skill; the small set, not a standing harness."
+    why: "Inline eval set authored before tuning — the discipline the 'Inline evals — write these first' section exists to enforce; the small set, not a standing harness."
   - prompt: "Users can paste 'ignore your instructions' into my input field and the model obeys it."
     why: "Prompt-scope injection hardening — delimiting untrusted input and treating it as data, a named robustness rule."
   - prompt: "I'm moving this prompt from one model to another and the behavior shifted; how do I keep it stable?"