@ericrisco/rsc 0.1.52 → 0.1.54

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/medium-publishing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: medium-publishing
-description: "Use when getting a finished article onto Medium correctly — choosing profile vs publication, cross-posting from your own site without an SEO duplicate-content hit, the import tool, the 5-tag limit, and Medium's pseudo-Markdown formatting gotchas. Triggers: 'cross-post to Medium', 'republish on Medium with a canonical link', 'submit my draft to a Medium publication', 'why are my code blocks broken on Medium', 'can I still automate Medium via the API', 'the Medium import tool failed with a 403', 'importar mi artículo a Medium sin penalización SEO', 'publicar a Medium amb enllaç canònic'. NOT drafting, structuring, or headlining the article itself (that is medium-writing)."
+description: "Use when a finished article has to land on Medium correctly — profile vs publication, cross-posting under a canonical link so your own site keeps the SEO credit, import-tool failures, the 5-tag cap, pseudo-Markdown gotchas. NOT writing or headlining the piece (that is `medium-writing`), NOT cadence or earnings (that is `medium-strategy`)."
 tags: [medium, publishing, cross-posting, canonical-url, seo, import-tool]
 recommends: [medium-writing, medium-strategy, seo-geo, social-publisher]
 origin: risco
@@ -10,13 +10,11 @@ origin: risco
 
 Land a finished article on Medium with correct metadata: right destination, no duplicate-content penalty, valid tags, intact formatting. Writing the article is `../medium-writing/SKILL.md`; deciding when/where/how-often to publish and how it grows is `../medium-strategy/SKILL.md`. This skill is only the mechanics of getting bytes onto the platform with the right metadata attached.
 
-## Reality check — read this first (2025-2026)
+## Reality check (2025-2026)
 
 **The Medium API is closed to new integrations.** As of 2025-01-01 Medium issues no new integration tokens and accepts no new integrations; only tokens minted before that date still work. Why it matters: any plan that starts with "register a Medium API token and automate it" is dead on arrival for anyone who didn't already have one. Integration platforms confirm this — the Medium app in Make is marked legacy, and n8n's Medium credentials can no longer be newly configured.
 
-So the default publishing path is **web editor + import tool + canonical link**, done through the UI. Treat the API as a legacy escape hatch (last section), not the plan.
-
-Do not promise API automation. If the user asks "can I get a token and automate this?", the honest answer is almost always no — explain why and route them to the import path below.
+So the default publishing path is **web editor + import tool + canonical link**, done through the UI. Treat the API as a legacy escape hatch (last section), not the plan — when asked "can I get a token and automate this?", the honest answer is almost always no, so say why and route to the import path below rather than promising automation.
 
 ## Decision table — pick your path
 
@@ -30,11 +28,9 @@ Branch on where the article already lives and what you control:
 | You hold a pre-2025 API token and want automation | Legacy `POST /v1/users/{id}/posts` | `canonicalUrl` field in the request body |
 | Destination is a publication you write for | Submit draft to the publication | Same as above; submission is separate from canonical |
 
-When in doubt and the piece exists elsewhere, prefer the import tool — it gets canonical *and* backdate right in one step.
-
 ## Cross-post without an SEO penalty (the core job)
 
-When the article already lives on your own site, you must tell search engines the original is canonical, or Google sees two copies and may credit Medium or neither. Two mechanisms, in order of preference:
+When the article already lives on your own site, you must tell search engines that the **origin** — your page, never the Medium URL — is canonical, or Google sees two copies and may credit Medium or neither. Two mechanisms, in order of preference:
 
 **1. Import tool (preferred).** Pasting the original URL into Medium's import field does three things at once:
 - imports the rendered content into a new draft,
@@ -54,8 +50,6 @@ Good: Use the import tool (canonical + backdate set automatically), or if
       BEFORE publishing.
 ```
 
-The canonical must point to the **origin** (your site), not to the Medium URL. The whole point is that your site keeps the SEO credit.
-
 ## When the import fails
 
 The importer is an HTTP crawler hitting your URL; failures are crawl failures, not Medium bugs. Map the symptom to the cause:
@@ -98,9 +92,7 @@ Good: Convert the table to a labeled list, or screenshot/export it as an
 Two outcomes, often confused:
 
 - **Self-publish** puts the story on your own profile immediately.
-- **Submit to a publication** routes the draft to that publication's editors. It stays **pending** — not live — until an editor publishes it, and you must already be an accepted writer for that publication. Submitting does not auto-publish.
-
-Why it sits pending: a publication is editorially controlled; submission is a request, not a publish action. If you're not yet a writer there, request access first; submitting otherwise goes nowhere.
+- **Submit to a publication** routes the draft to that publication's editors, where it stays **pending** — not live — until one of them publishes it. A publication is editorially controlled, so submission is a request, not a publish action, and it only works if you are already an accepted writer there. If you're not, request access first; submitting otherwise goes nowhere.
 
 ## Legacy API — only if you hold a pre-2025 token
 

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/n8n/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: n8n
-description: "Use when operating a live n8n instance programmatically — driving its public REST API (`{host}/api/v1`, `X-N8N-API-KEY`) or the n8n-mcp server to create, validate, test, activate/deactivate, list, update, or delete workflows and read executions, on self-host or `*.app.n8n.cloud`. Triggers: 'deploy this workflow to my n8n over the API', 'push my workflow JSON to n8n with curl', 'I set active:true in the create call but it stays inactive', 'connect n8n-mcp / n8n_create_workflow to Claude', 'validate and autofix my n8n workflow', 'run an n8n workflow by id from a script', 'delete a workflow via the API', 'automatiza n8n por API', 'desplega el workflow a n8n.cloud'. NOT designing the flow's trigger-step-error logic or hand-building the importable workflow JSON (that is automation-flows), NOT operating Make / Zapier / Power Automate (their own skills), NOT a typed API client with auth+pagination+retry (api-connector-builder), NOT the inbound webhook receiver in your own app (webhooks)."
+description: "Use when operating a live n8n instance programmatically — its REST API (`{host}/api/v1`, `X-N8N-API-KEY`) or the n8n-mcp server — to create, validate, test, activate, update, delete workflows and read executions on self-host or n8n.cloud. NOT designing the flow or its importable JSON (that is `automation-flows`), NOT another platform (`make`, `zapier`)."
 tags: [n8n, automation, workflows, mcp, rest-api, no-code, integrations]
 recommends: [automation-flows, automation-strategy, api-connector-builder, webhooks]
 profiles: [full]
@@ -9,15 +9,11 @@ origin: risco
 
 # n8n — operate a live instance over its REST API and MCP
 
-You already have a workflow *design* (the trigger→steps→error shape and the importable JSON).
-This skill is the **operate** half: push that JSON into a running n8n, validate it, test it, flip it
-live, watch its executions, and tear it down safely — all without touching the UI. n8n has the
-richest programmatic story of the no-code platforms: a first-party REST API **plus** a mature MCP
-server, both hitting the same instance.
-
-Designing the flow itself (what fires it, how errors are handled, dedup) is **automation-flows** —
-this skill *consumes* that skill's `references/n8n-workflow-json.md` payload; it does not re-teach
-design.
+You already have a workflow *design* — the trigger→steps→error shape and the importable JSON, which is
+`automation-flows`' job and this skill does not re-teach it. This skill is the **operate** half: push
+that JSON into a running n8n, validate it, test it, flip it live, watch its executions, and tear it
+down safely — all without touching the UI. n8n has the richest programmatic story of the no-code
+platforms: a first-party REST API **plus** a mature MCP server, both hitting the same instance.
 
 ## Connect first — REST API vs MCP
 
@@ -31,10 +27,10 @@ Two ways to drive the same instance. Pick by who is at the wheel.
 | Surface | identical on self-host **and** `*.app.n8n.cloud` | same underlying API; hosted trial at `dashboard.n8n-mcp.com` |
 
 **Version reality (verify at author time — n8n moves fast):**
-- API base is `{host}/api/v1`. Self-host ships interactive Swagger at `/api/v1/docs`; **cloud does not**.
+- API base is `{host}/api/v1`. Self-host ships interactive Swagger at `/api/v1/docs`; **cloud does not**
+  — on cloud, work from the docs.
 - `POST /workflows/{id}/execute` (run-by-id) is **recent** (n8n PR #20234). Older instances lack it —
-  there, the only programmatic run is POSTing to a Webhook node's URL. It also takes **no custom input**.
-- The API surface is the SAME whether you self-host or run on `*.app.n8n.cloud`; only the host differs.
+  there, the only programmatic run is POSTing to a Webhook node's URL.
 
 ### `.env`
 
@@ -66,7 +62,8 @@ shapes rather than guessing — that is the single biggest reason to drive via M
 ## Dynamic lifecycle
 
 create → **validate** → test → **activate** → manage → delete. A concrete sketch per step, curl and
-n8n-mcp side by side.
+n8n-mcp side by side; every endpoint with pagination and scopes is in
+`references/rest-api-cheatsheet.md`.
 
 ### 1. Validate (do this BEFORE create)
 
@@ -107,8 +104,9 @@ n8n_test_workflow       { "id": "$ID" }
 
 ### 4. Activate — the step people miss
 
-`active` in the create/update body is **read-only and silently ignored**. Setting `"active": true`
-does nothing. You MUST call the separate endpoint:
+`active` (and `tags`) in the create/update body are **read-only and silently ignored**. Setting
+`"active": true` does nothing, which is why the workflow you just created never fires. You MUST call
+the separate endpoint:
 
 ```bash
 curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/activate"   -H "X-N8N-API-KEY: $N8N_API_KEY"
@@ -137,7 +135,8 @@ omitted. n8n-mcp's `n8n_update_partial_workflow` applies a targeted, atomic batc
 
 ### 6. Delete — irreversible
 
-`DELETE` is a **hard delete: no trash, no undo.** Export the current JSON first, every time.
+`DELETE` is a **hard delete: no trash, no undo**, so export the current JSON first, every time — this
+one is absolute because nothing downstream can recover the workflow if you skip it.
 
 ```bash
 curl -sS "$N8N_API_URL/api/v1/workflows/$ID" -H "X-N8N-API-KEY: $N8N_API_KEY" > backup-$ID.json  # export FIRST
@@ -147,7 +146,7 @@ curl -sS -X DELETE "$N8N_API_URL/api/v1/workflows/$ID" -H "X-N8N-API-KEY: $N8N_A
 n8n_get_workflow { "id": "$ID" }   →  save output  →  n8n_delete_workflow { "id": "$ID" }
 ```
 
-**Irreversibility rule:** never DELETE (or full-replace) a live workflow without exporting it first.
+The same applies to a full replace: export before `PUT`.
 
 ## Governance
 
@@ -156,50 +155,23 @@ If you expose n8n-mcp to an agent, lock down destructive tools with the `DISABLE
 key itself too — n8n supports scoped keys (e.g. grant `workflow:read` without `workflow:execute`).
 Details in `references/n8n-mcp-tools.md`.
 
-## Honesty / gotchas
-
-- **`active` and `tags` are read-only on create/update** — ignored in the body; activate/tag via the
-  dedicated endpoints. This is the #1 "why is my workflow inactive" bug.
-- **`/workflows/{id}/execute` takes no custom input** — for runtime params, trigger a Webhook workflow
-  by POSTing to its URL. Also, it is a newer endpoint; older instances 404 it.
-- **`DELETE` and `PUT` are destructive** — hard delete (no trash) and full replace. Export first; prefer
-  `n8n_update_partial_workflow` for edits.
-- **`typeVersion` must exist on the target** — a node version the instance doesn't have fails only at
-  activate/execute time, not at create. Validate (MCP) or test before activating.
-- **Credential secrets are not fully manageable over the public API** — you can reference existing
-  credentials by id/name and create some, but you cannot read secrets back; provision credentials in
-  the UI / n8n-mcp `n8n_manage_credentials` and reference them.
-- **Cloud has no Swagger** — `/api/v1/docs` is self-host only; on cloud, work from the docs.
-- **Activation can succeed via API where the UI would block it** — the public API historically skips a
-  few UI-side activation validations, so a workflow can be "active" yet non-functional. Test it live.
-
-## Related skills
-
-- **automation-flows** — *design* the flow and produce the importable JSON this skill deploys. Design
-  vs operate boundary: they decide the trigger/steps/error path; you push it live. Start there if the
-  flow's logic isn't settled yet.
-- **automation-strategy** — whether n8n is even the right platform (cost model, self-host vs cloud) vs
-  Make/Zapier/Power Automate.
-- **make / zapier / power-automate** — the other platforms' operate stories (Zapier and Power Automate
-  can't create flows via API — n8n's edge).
-- **api-connector-builder** — a generic typed HTTP client with auth/pagination/backoff, when the answer
-  is real code, not a workflow.
-- **webhooks** — building the inbound receiver *in your own app*; here webhooks are just n8n triggers.
-
-## Checklist
-
-- [ ] `.env` has `N8N_API_URL`/`N8N_HOST` + `N8N_API_KEY` (key from Settings → n8n API); key not logged.
-- [ ] Payload has `name`, `nodes` (one trigger), `connections`, `settings` per automation-flows' schema;
-      node credentials referenced by store, never inlined.
-- [ ] Validated (`n8n_validate_workflow` / `n8n_autofix_workflow`) before create when MCP is available.
-- [ ] Created via `POST /workflows` or `n8n_create_workflow`; captured the returned `id`.
-- [ ] Tested — `execute`-by-id (no input) or POST to the webhook URL (with input) — and the run succeeded.
-- [ ] Activated via `POST /workflows/{id}/activate` (NOT `active:true` in the body).
-- [ ] Before any DELETE or full-replace: exported the current JSON (hard delete, no trash).
-- [ ] If MCP is exposed to an agent: `DISABLED_TOOLS` set and/or the API key scoped.
-
-## References
-
-- `references/rest-api-cheatsheet.md` — every workflow/execution endpoint with curl, pagination, scopes.
-- `references/n8n-mcp-tools.md` — the management + node-knowledge tool list, the auth split, `DISABLED_TOOLS`.
-- `references/auth-and-selfhost.md` — API-key creation, self-host vs cloud, Swagger, installing/pointing n8n-mcp.
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| `"active": true` (or `tags`) in the create/update body | Read-only fields, silently ignored — the #1 "why is my workflow inactive" bug | `POST /workflows/{id}/activate`; set tags via their own endpoint |
+| Passing runtime input to `/workflows/{id}/execute` | It accepts no custom input, and older instances 404 the endpoint entirely | Trigger a Webhook workflow by POSTing to its URL |
+| `PUT` with a partial body, or `DELETE` on a live workflow | Full replace drops every node you omitted; delete is a hard delete with no trash | GET and export first; prefer `n8n_update_partial_workflow` for edits |
+| A `typeVersion` the target instance doesn't have | Create succeeds; it fails only at activate/execute time | Validate via MCP, or test, before activating |
+| Inlining node credential secrets, or expecting to read them back | Credentials are not fully manageable over the public API — it can create some, but never returns a secret | Provision in the UI or via `n8n_manage_credentials`, then reference existing credentials by id/name |
+| Treating a successful API activation as proof it works | The public API historically skips a few UI-side activation validations, so a workflow can be "active" yet non-functional | Run it live after activating and check the execution |
+
+## Route elsewhere
+
+| If the ask is | Skill |
+|---|---|
+| Designing the flow (trigger/steps/error path, dedup) and producing the importable JSON | `automation-flows` — start there if the logic isn't settled |
+| Whether n8n is the right platform at all — cost model, self-host vs cloud | `automation-strategy` |
+| Operating a different platform | `make`, `zapier`, `power-automate` (neither Zapier nor Power Automate can create flows via API — n8n's edge) |
+| A generic typed HTTP client with auth/pagination/backoff — real code, not a workflow | `api-connector-builder` |
+| The inbound webhook receiver in your own app (here webhooks are only n8n triggers) | `webhooks` |