@ericrisco/rsc 0.1.44 → 0.1.46

package/package.json

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

package/scripts/lib/domains.js

@@ -10,7 +10,7 @@ export const DOMAINS = [
   { title: 'Raise & model money', ids: ['pitch-deck', 'investor-materials', 'financial-model', 'fundraising', 'unit-economics', 'grants'] },
   { title: 'Legal, privacy & compliance', ids: ['gdpr-privacy', 'terms-conditions', 'compliance', 'data-policy', 'ip-trademark'] },
   { title: 'Market & brand', ids: ['marketing', 'seo-geo', 'content-engine', 'social-publisher', 'brand-voice', 'brand-identity', 'newsletter', 'landing-copy', 'ads', 'article-writing', 'case-studies', 'video-shorts', 'podcast', 'market-research', 'competitor-watch', 'press-kit', 'community', 'webinar', 'review-management'] },
-  { title: 'Grow a channel (YouTube / TikTok / Reels / LinkedIn / Medium)', ids: ['youtube-api', 'youtube-strategy', 'youtube-ideation', 'youtube-thumbnails', 'youtube-packaging', 'remotion-video', 'tiktok-api', 'instagram-api', 'shortform-strategy', 'shortform-ideation', 'shortform-packaging', 'shortform-editing', 'linkedin-api', 'linkedin-strategy', 'linkedin-content', 'linkedin-carousels', 'linkedin-outreach', 'medium-writing', 'medium-publishing', 'medium-strategy'] },
+  { title: 'Grow a channel (YouTube / TikTok / Reels / LinkedIn / Medium)', ids: ['youtube-api', 'youtube-strategy', 'youtube-ideation', 'youtube-thumbnails', 'youtube-packaging', 'remotion-video', 'tiktok-api', 'instagram-api', 'shortform-strategy', 'shortform-ideation', 'shortform-packaging', 'shortform-editing', 'viral-score', 'linkedin-api', 'linkedin-strategy', 'linkedin-content', 'linkedin-carousels', 'linkedin-outreach', 'medium-writing', 'medium-publishing', 'medium-strategy'] },
   { title: 'Connect & automate', ids: ['stripe', 'email-connector', 'google-workspace', 'notion-connector', 'whatsapp-telegram', 'automation-flows', 'api-connector-builder', 'webhooks', 'data-scraper', 'spreadsheet-ops', 'calendar-scheduling', 'document-processing', 'e-signature'] },
   { title: 'Automation platforms', ids: ['automation-strategy', 'n8n', 'make', 'zapier', 'power-automate'] },
   { title: 'Data & analytics', ids: ['analytics', 'dashboard', 'kpi-framework', 'reporting', 'ab-testing', 'forecasting', 'data-cleaning', 'business-intelligence'] },

package/scripts/skill-migration-brief.md

@@ -0,0 +1,192 @@
+# skill-migration-brief — how to move one skill to the Claude-5-era rubric
+
+This is the working brief for the catalog-wide migration. One agent, one skill, one worktree, one
+branch, one PR. `scripts/skill-rubric.md` is the spec; this is how to apply it to an existing skill.
+
+## Why this exists
+
+Anthropic's *The new rules of context engineering for Claude 5 generation models* (Jul 2026) reports
+that >80% of Claude Code's system prompt was removed with no measurable eval loss, and names the
+patterns that stopped paying: **repeating yourself across layers**, **over-constraining with rules
+where judgment suffices**, and **enumerating examples where an expressive interface would do**.
+
+Applied here: a skill's `description` is in context on **every turn it is installed**, invoked or
+not. Across 257 skills that was 207 KB. The body is loaded when the skill fires. Both are paid for
+by every user, so length is a cost, never a credit.
+
+## The pass
+
+1. `git checkout -b skill/<id>`
+2. Read `scripts/skill-rubric.md`, then `skills/<id>/SKILL.md`.
+
+### The description
+
+Shape: **what it does · when to use it · an explicit `NOT <x> (that is \`sibling\`)` boundary.**
+
+- Delete any `Triggers: '…', '…'` phrase list. The model matches by meaning; keyword lists in three
+  languages are pure per-turn cost, and the body usually instructs semantic matching right next to
+  them — a self-contradiction.
+- Name a **real** sibling in the boundary. Verify it exists under `skills/`.
+- Target ≤350 chars. Hard limit 1024 (schema-enforced). Third person, opens with "Use when/to".
+- The test is **discrimination, not coverage**: could a reader choose this skill over its nearest
+  sibling from the description alone?
+
+### The body
+
+The goal is the smallest body that still routes correctly. 400 lines is a ceiling; there is no floor.
+
+**Remove:**
+
+- Rule banks that restate the flow — "Iron rules (non-negotiable)", "Rationalizations — STOP".
+  A rule worth keeping moves next to the step it governs, and says *why* it is absolute instead of
+  shouting NON-NEGOTIABLE. A rule in an appendix is skimmed; a rule in context is followed.
+- Re-teaching of what another skill owns. The accompaniment dial belongs to `init`; the SDD method
+  belongs to `sdd`. Read the profile and point; do not restate, or the two drift apart.
+- "When to use" sections that restate the description, and trailing reference indexes whose links
+  already appear inline at point of use.
+
+**Keep — these are not padding:**
+
+- The **anti-patterns table**. The rubric requires one, and it is a different animal from a
+  rationalization table: it names concrete failure modes, not rules already stated above it.
+
+  **The hybrid case, which is common:** a table titled something like *"Anti-patterns /
+  rationalizations — STOP"*, with an *Excuse → Reality* framing. Do not delete it and do not leave
+  it as-is. **Keep every row, re-column it to `Anti-pattern | Do instead`, and drop the STOP /
+  excuse framing.** The rows are the value; the borrowed urgency wrapper is what dimension 7
+  forbids. Handling this the same way everywhere is what keeps the catalog consistent — deleting it
+  in one skill and keeping it in the next is worse than either choice applied uniformly.
+- Decision tables where the flow genuinely branches.
+- Tables specific to *this* skill's phase (e.g. what to show at each checkpoint) — that is not the
+  generic dial.
+- Worked bad/good pairs that teach judgment by demonstration.
+- Result-envelope blocks, chain position, and output contracts where they already exist. Do **not**
+  add one that was never there: that is a content change, not a format change.
+
+**Invariant:** every file under `skills/<id>/references/` must be linked from the body. An unlinked
+reference is never loaded, so it is dead weight in the package. Folding a tail index into inline
+mentions is fine — the link just has to survive. `scripts/`, `evals/` and `assets/` need no link.
+
+**Preserve substance exactly.** This is a context-engineering pass, not a content rewrite. Do not
+change recommendations, versions, commands, figures, or add claims.
+
+## Verify
+
+Your worktree has **no `node_modules`**, so:
+
+- Run: `bash scripts/eval-lint.sh 2>&1 | grep -i '^<id>'` → must report PASS.
+- Check the description length and that every `references/` file is linked.
+- Do **not** run `npm test` or `npm run validate` — they need dependencies you do not have. The
+  orchestrator runs them once, globally, after merge.
+- Do **not** edit `manifest.json`. It is derived, and parallel edits from hundreds of agents would
+  all conflict on the same lines. The orchestrator regenerates it once at the end.
+
+## Ship
+
+Commit only `skills/<id>/`. Subject `refactor(<id>): <what you actually did>`. The body says what you
+removed **and why**, and — just as important — what you deliberately **kept** and why.
+
+**Authorship is Eric, never Claude.** No `Co-Authored-By` for any AI, no "Generated with Claude Code"
+footer, nothing attributing the work to a tool — in the commit *or* the PR body. This is the hard
+rule the `ship` skill enforces (`skills/ship/SKILL.md`), and it applies to this migration like
+everything else in the repo. Verify before pushing:
+
+```bash
+git log -1 --format='%b' | grep -iE 'co-authored-by.*(claude|anthropic|ai)|generated with|claude code' \
+  && echo "AUTHORSHIP VIOLATION — strip it" || echo "authorship clean"
+```
+
+Then `git push -u origin skill/<id>` and `gh pr create`. The PR body carries before/after description
+chars, before/after body bytes, what went, what stayed, and the eval-lint result — and no AI
+attribution line.
+
+## Judgment
+
+If the skill already meets the rubric, **say so and change only the description.** A small honest
+diff beats a large invented one. Several skills in the pilot needed 5-line diffs; that is a good
+outcome, not a failed pass. Never pad, and never cut substance to hit a number.
+
+---
+
+# For the orchestrator
+
+Everything above is for the agent doing one skill. This half is for whoever is driving the fleet.
+
+## Resuming, from nothing
+
+There is no state file to keep in sync, on purpose. **The remote branches are the ledger:**
+
+```bash
+# what is done
+git ls-remote --heads origin 'refs/heads/skill/*'
+# what is left = skills/ minus those, minus what is already merged to main
+```
+
+So a cold session resumes with: *read this brief, compute the skills with no `skill/*` branch, launch
+one agent per skill in its own worktree.* Nothing from any previous conversation is required.
+
+## Order: by profile, not alphabetically
+
+A skill's `description` is in context for everyone who installs it, so migrate by blast radius:
+
+1. `minimal` profile — in every rsc install.
+2. `core` profile — the default install (the SDD chain plus the control plane).
+3. High-install stack skills — `nextjs`, `react`, `fastapi`, `postgresdb`, `design`, `typescript`,
+   `python`, `go`, `flutter`, `secure-coding`, `deployment`.
+4. Everything else.
+
+If a run is cut short, this ordering means the part that was finished is the part that everyone pays for.
+
+## Sharp edges (each one cost a real mistake)
+
+- **`manifest.json` is derived.** Agents must never touch it — hundreds of parallel edits collide on
+  the same lines. Regenerate once, centrally, with `npm run manifest` after merging.
+- **A fresh worktree has no `node_modules`** (it is gitignored, so it is not checked out). `npm test`
+  and `npm run validate` cannot run there. `scripts/eval-lint.sh` can — it uses python3.
+- **Result-envelope blocks are asymmetric.** `specify`, `tasks`, `implement`, `verify`, `ship`,
+  `parallel` and `sdd` have one; `plan`, `analyze`, `clarify`, `constitution`, `review` and `debug`
+  do not. Tell each agent which case it is in, or it will helpfully invent one.
+- **`author-skill` is special.** It teaches how to write skills, so it documented the *old*
+  conventions. There, rewriting the guidance IS the migration — and the change has to reach its
+  `references/` and `evals/`, which graded produced skills against the old rubric.
+- **Short ids break greps.** `go`, `rag`, `php` match half of `eval-lint`'s output. Give those agents
+  an anchored pattern (`grep -E '^go +'`).
+- **Compound bash commands are denied whole.** The `ship-guard` hook rejects the entire call if any
+  part matches `git checkout main`, so a chained `commit && push && checkout main` runs *nothing*.
+  Split them.
+- **The id `parallel` is unusable in a git command.** A sandbox guard aimed at GNU `parallel` matches
+  the substring, so `git checkout -b skill/parallel` is refused. That skill's branch has to be
+  created from the pushed commit with `gh api` instead. Any future id containing a blocked tool name
+  will behave the same way.
+
+## Content problems found while migrating — do NOT fix them in a format pass
+
+Agents surfaced these and correctly left them alone. They need their own change:
+
+- `sdd` claims every phase ends with a parseable envelope; six phases have none (see above).
+- **`evals/cases.yaml` files carry stale claims about what the catalog contains, in both
+  directions.** Three agents hit this independently: `course-storytelling` routes a negative to
+  `deep-research`, which does not exist; `flutter` routes its Compose/SwiftUI negatives to `"none"`
+  on the grounds those skills are "not in this catalog", though `compose-multiplatform` and
+  `swift-ios` now are; `postgresdb` said the same of ORM traps, stale since `prisma-orm` and
+  `drizzle-orm` shipped. This drifts every time the catalog grows.
+
+  The root cause is that `eval-lint` does not actually verify a `route_to` names a real skill,
+  even though the rubric lists exactly that as a deterministic gate — so the gate is decorative.
+  (The 1024-char description limit had the same problem; that one is now enforced in
+  `schema/frontmatter.schema.json`.) Fixing the linter is worth more than fixing the instances:
+  it converts a recurring drift into a build error.
+- `clarify`'s body calls itself "the fourth phase" while the chain it prints puts it third.
+- `cold-outreach` never names `linkedin-outreach` in its route table, though the reverse link exists.
+- `data-policy` says "walk five columns" and then lists six.
+- `marketing/references/seo-geo.md` (20 KB) and marketing's landing-section material substantially
+  duplicate the standalone `seo-geo` and `landing-copy` skills. Three skills, one body of content,
+  paid for three times by anyone who installs all three. Needs a content-level de-duplication pass,
+  not a format one.
+
+## Return value
+
+```json
+{"skill":"<id>","pr":"<url|null>","descBefore":0,"descAfter":0,"bytesBefore":0,"bytesAfter":0,
+ "evalLint":"PASS|FAIL","removed":["…"],"kept":["…"],"notes":"anything the orchestrator must know"}
+```

package/skills/ab-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ab-testing
-description: "Use when designing or analyzing a controlled experiment — writing a falsifiable hypothesis, sizing a test from a minimum detectable effect, reading significance/confidence intervals/power, or rescuing a test that 'won't go significant'. Triggers: 'how many users do I need to detect a 2% lift', 'is this result significant', 'control 540/10000 vs variant 590/10000', 'why is my A/B test inconclusive', 'we keep peeking and stopping early', 'set up CUPED to speed up the test', 'sample ratio mismatch', 'cuántos usuarios necesito para el test', 'el experiment no surt significatiu'. NOT recurring metric tracking (that is analytics), NOT defining north-star/KPI trees (that is kpi-framework), NOT projecting a metric forward (that is forecasting)."
+description: "Use when designing or analyzing a controlled experiment — falsifiable hypothesis, sample size from an MDE, reading significance/CI/power, CUPED, or rescuing tests that won't go significant. NOT recurring metric tracking (that is `analytics`), NOT north-star/KPI trees (that is `kpi-framework`), NOT projecting metrics forward (that is `forecasting`)."
 tags: [ab-testing, experimentation, statistics, cuped, sample-size, hypothesis-testing]
 recommends: [analytics, kpi-framework, forecasting, data-cleaning, python, reporting]
 origin: risco
@@ -13,23 +13,9 @@ It is a dashboard you stare at until it tells you what you wanted to hear. The d
 entirely *before* traffic ships: a falsifiable hypothesis, one primary metric, a sample size derived
 from the smallest effect worth detecting, and a stop rule you cannot renegotiate at 2pm on day four.
 
-Do the math first. This skill is opinionated about refusing to declare a winner from a peeked dashboard.
-
-## When to use
-
-- Designing an A/B or multivariate test: hypothesis, primary + guardrail metrics, randomization unit.
-- Computing required sample size / duration from a baseline rate, a minimum detectable effect (MDE), and power.
-- Analyzing a finished test: two-proportion z-test or Welch t-test, lift, confidence interval, p-value.
-- Reducing required traffic with CUPED (pre-experiment covariate adjustment).
-- Diagnosing an "inconclusive" test: underpowered, peeked, sample-ratio mismatch, multiple comparisons.
-
-For the failure-mode math (peeking, sequential methods, FDR corrections, SRM, Simpson's paradox) see
-`references/pitfalls.md`. For full runnable sizing/CUPED/SRM snippets and a worked numeric example see
-`references/sample-size-and-cuped.md`.
-
 ## Pre-test checklist — every line true before any traffic
 
-Refuse to ship until all of these exist on paper. Each one is a place experiments die silently.
+Each one is a place experiments die silently.
 
 - [ ] A **falsifiable hypothesis** — names the change, the direction, and the metric it moves.
 - [ ] Exactly **ONE primary metric**. More than one primary = multiple comparisons = inflated false positives.
@@ -90,7 +76,8 @@ n = TTestIndPower().solve_power(effect_size=effect, alpha=0.05, power=0.80, rati
 
 Then convert n to a calendar plan: `days = ceil((n_per_arm * num_arms) / daily_eligible_users)`. If that
 is 9 days, run a clean **two full weeks** anyway — weekday/weekend mix is part of the population, and a
-6-day test oversamples whoever shows up Tuesday. Full worked example in `references/sample-size-and-cuped.md`.
+6-day test oversamples whoever shows up Tuesday. Full worked example (12% baseline, +1.5pp MDE, 80%
+power) plus runnable sizing, n→duration, CUPED θ and SRM snippets: `references/sample-size-and-cuped.md`.
 
 ## Step 3 — Run discipline
 
@@ -101,12 +88,14 @@ inflates the Type-I error far above 5% — with enough looks, a null test crosse
 If you genuinely need to stop early, use a *sequential / always-valid* method (confidence sequences,
 e.g. Netflix's anytime-valid CIs) that holds Type-I error under continuous monitoring. Sequential is
 strong for **killing losers early** and weak for **calling winners early** — for a confident win, the
-fixed-horizon read is tighter. Details and the peeking math: `references/pitfalls.md`.
+fixed-horizon read is tighter.
 
 **Gate on SRM before you trust anything.** Compute a chi-square test on the observed split versus the
 intended ratio. If p < 0.001 the assignment or logging is broken — a bot filter dropping one arm, a
-redirect, a caching bug. Fix the instrumentation and rerun; do not "adjust for it." See the SRM snippet
-in references.
+redirect, a caching bug. Fix the instrumentation and rerun; do not "adjust for it."
+
+The peeking Type-I math, sequential/always-valid options, SRM diagnosis, novelty/primacy effects,
+Simpson's paradox in segments and HARKing all live in `references/pitfalls.md`.
 
 ## Step 4 — Analyze
 
@@ -148,20 +137,6 @@ with the outcome, or — the cardinal sin — a covariate measured *after* assig
 estimate. The covariate MUST be pre-treatment and independent of which arm a user lands in. Runnable
 θ-via-OLS snippet in `references/sample-size-and-cuped.md`.
 
-## Decision table
-
-| Question | Use |
-|---|---|
-| Metric is a binary conversion | Two-proportion z-test |
-| Metric is continuous, large n | Welch's t-test |
-| Metric is revenue / heavy-tailed | Mann-Whitney U or t-test on log/winsorized |
-| 1–3 decision-critical metrics | Bonferroni correction |
-| Many exploratory metrics/segments | Benjamini-Hochberg (FDR) |
-| Need to stop early to kill a loser | Sequential / always-valid CIs |
-| Want a confident winner | Fixed horizon, read once at planned n |
-| Recurring users + pre-period signal | Add CUPED |
-| Brand-new users / no pre-period data | Skip CUPED |
-
 ## Anti-patterns
 
 | Bad | Why it is wrong | Do instead |
@@ -176,13 +151,6 @@ estimate. The covariate MUST be pre-treatment and independent of which arm a use
 | Decide the hypothesis after seeing results (HARKing) | Turns the whole analysis into a fishing expedition | Pre-register hypothesis + primary metric before launch |
 | Run 6 days because it "looks significant" | Oversamples one weekday slice of the population | Run full weeks; honor the fixed horizon |
 
-## References
-
-- `references/sample-size-and-cuped.md` — full runnable snippets (proportion sizing, continuous sizing,
-  n→duration, CUPED θ via OLS, SRM chi-square) and a worked example: 12% baseline, +1.5pp MDE, 80% power.
-- `references/pitfalls.md` — peeking Type-I math, sequential/always-valid options, Bonferroni vs FDR with
-  the 17-vs-12 example, SRM diagnosis, novelty/primacy effects, Simpson's paradox in segments, HARKing.
-
 ## Checkable artifact
 
 When this skill emits a Python sizing/analysis script or an experiment-design doc, run

package/skills/accessibility/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: accessibility
-description: "Use when making a web UI conform to WCAG 2.2 Level AA — fixing axe-core violations, a low Lighthouse a11y score, adding keyboard support, focus management, ARIA roles/labels, skip links, live regions, accessible names, or checking contrast and tap-target size. Triggers: 'make this accessible', 'fix the contrast', 'keyboard navigation is broken', 'screen reader can't read this', 'axe says button-name / color-contrast', 'the modal doesn't trap focus', 'tab order is wrong', 'our tap targets are smaller than 24px', 'fes-ho accessible', 'el lector de pantalla no lee los errores'. NOT general performance / LCP tuning (that is performance), NOT setting up the Jest/RTL test runner itself (that is testing-web)."
+description: "Use when making a web UI conform to WCAG 2.2 Level AA — axe-core or Lighthouse a11y violations, keyboard operability, focus management, ARIA roles/names/live regions, contrast, tap-target size. NOT palette or visual intent (that is `design`), NOT test-runner setup (that is `testing-web`), NOT LCP/page-speed (that is `performance`)."
 tags: [wcag, accessibility, a11y, aria, axe-core]
 recommends: [testing-web, e2e-testing, design, react, performance]
 origin: risco
@@ -76,7 +76,7 @@ Everything a mouse can do, a keyboard must do.
 2. **Trap focus** inside while open — Tab from the last element wraps to the first.
 3. **Escape closes**, and **focus returns to the trigger** that opened it.
 
-Composite widgets (menus, tabs, grids) use **roving tabindex**: one element is `tabindex="0"`, the rest `-1`, arrow keys move the `0`. Full keyboard tables per pattern → `references/aria-patterns.md`.
+Composite widgets (menus, tabs, grids) use **roving tabindex**: one element is `tabindex="0"`, the rest `-1`, arrow keys move the `0`. Full keyboard tables per pattern — modal, disclosure, tabs, combobox, menu, toast → `references/aria-patterns.md`.
 
 ## Visible focus & the WCAG 2.2 deltas
 
@@ -144,7 +144,7 @@ Mental model: **Name, Role, Value.** Every custom control needs an accessible *n
 
 ## Automate it (versioned, 2026-06-02)
 
-Three layers — each catches what the cheaper one can't. Restate the ceiling: **automation ≈ 57% coverage**, the rest is manual.
+Three layers — each catches what the cheaper one can't.
 
 **Lint (static, JSX only) — `eslint-plugin-jsx-a11y` 6.10.2.** Catches missing `alt`, label-less inputs, positive `tabindex`, invalid roles, at edit time.
 
@@ -190,7 +190,7 @@ Do these by hand before you call it done:
 - [ ] **`prefers-reduced-motion`** honored — no autoplay parallax/animation that ignores it.
 - [ ] **Alt text is meaningful, not decorative-as-content** — informative images describe; decorative images use `alt=""`.
 
-Full AA checklist grouped by POUR, with the per-item auto/manual split → `references/wcag22-checklist.md`.
+Full AA checklist grouped by POUR, with the per-item auto/manual split and the 6 new 2.2 criteria flagged → `references/wcag22-checklist.md`.
 
 ## Anti-patterns
 
@@ -207,10 +207,8 @@ Full AA checklist grouped by POUR, with the per-item auto/manual split → `refe
 | Shipping on a green axe run                    | Covers ~57%; keyboard/SR/cognitive untested              | run the manual checklist                            |
 | Autoplaying motion, no reduced-motion guard    | Triggers vestibular disorders (2.3.3)                    | gate behind `prefers-reduced-motion`                |
 
-## Where to go next
+## Hand off to
 
-- Full WCAG 2.2 AA checklist (POUR, auto/manual tags, the 6 new criteria flagged) → `references/wcag22-checklist.md`
-- Copy-ready accessible patterns with keyboard tables (modal, disclosure, tabs, combobox, menu, toast) → `references/aria-patterns.md`
 - Test harness, render setup, fixtures, CI runner mechanics → `../testing-web/SKILL.md` (this skill supplies the a11y *assertions* that run inside it)
 - Full browser-driven flow orchestration → `../e2e-testing/SKILL.md`
 - Visual intent, color palette, spacing scale → `../design/SKILL.md` (this skill checks the contrast/target-size *outcome*, not the aesthetic)

package/skills/ads/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ads
-description: "Use when you need to run or fix paid acquisition on Google or Meta — structuring campaigns (Performance Max, Demand Gen, Search, Advantage+), writing platform-fit creative, allocating budget, and deciding scale-vs-kill on ROAS. Use when a campaign spends but won't convert, conversions dropped after Consent Mode v2 or iOS, or you need the break-even ROAS math. Triggers: 'set up our Google Ads', 'our Performance Max isn't converting', 'what ROAS do we need to break even', 'how much budget per campaign and how fast can we scale', 'our Meta CPA is too high', 'platform ROAS looks great but the bank account disagrees', 'configura una campaña de Google Ads', 'qué ROAS necesito para no perder dinero', 'la campanya de Meta no converteix'. NOT writing the landing page the ad clicks into (that is landing-copy), NOT designing the experiment's statistics and sample size (that is ab-testing), NOT the whole-funnel channel-mix plan (that is marketing)."
+description: "Use when running or fixing paid acquisition on Google or Meta — campaign structure (Performance Max, Demand Gen, Search, Advantage+), platform-fit creative, budget/scaling rules, break-even ROAS math, and Consent Mode v2 / CAPI tracking gaps. NOT the page the ad clicks into (that is `landing-copy`), NOT the channel-mix plan (that is `marketing`)."
 tags: [paid-ads, google-ads, meta-ads, roas, performance-max, ppc, paid-acquisition]
 recommends: [marketing, landing-copy, brand-voice, ab-testing, analytics, dashboard, forecasting, lead-gen]
 origin: risco
@@ -14,12 +14,9 @@ budget → ROAS**. Your subject is the live account and its economics — the ca
 shape, the asset sets, the bid/budget config, and the math that says *keep scaling*
 or *kill it*.
 
-You do **not** own the page the ad clicks into (that is `landing-copy`), the voice
-the copy speaks in (that is `brand-voice`), or the statistics of an experiment (that
-is `ab-testing`). The nearest miss is `marketing`: it decides *whether to run paid at
-all and the channel mix*; you execute *the Google/Meta buy inside that plan* down to
-asset groups, bids, and break-even ROAS. "Should we even do paid?" → that is
-`../marketing/SKILL.md`. "Structure and scale the account" → that is you.
+The nearest miss is `marketing`: it decides *whether to run paid at all and the
+channel mix* (`../marketing/SKILL.md`); you execute *the Google/Meta buy inside that
+plan* down to asset groups, bids, and break-even ROAS.
 
 ## ROAS first — it gates everything
 
@@ -85,16 +82,17 @@ Good: 1 prospecting campaign above the conversion-data floor, untouched 4 weeks,
       then act on the data.
 ```
 
-PMax allows max **25 asset groups** per campaign — start with **1–2**. The full
-structure detail is in `references/platform-specs.md`.
+PMax allows max **25 asset groups** per campaign — start with **1–2**. Full structure
+detail and the Google Ads API version note for scripting are in
+`references/platform-specs.md`.
 
 ## Creative
 
 Write the ad-surface copy only. It must obey the brand's voice (`../brand-voice/SKILL.md`)
 and click into a page you do not write (`../landing-copy/SKILL.md`).
 
-Per-surface caps (summary — full tables, image/video orientations and sizes in
-`references/platform-specs.md`):
+Per-surface caps (summary — full tables, image/video orientations and sizes, and the
+Low/Good/Best rotation playbook in `references/platform-specs.md`):
 
 | Surface | Headlines | Descriptions | Media |
 |---|---|---|---|
@@ -157,19 +155,6 @@ the signal; they build the read-out.
 
 ## Handoff
 
-- **Destination page** the ad clicks into → `../landing-copy/SKILL.md`.
-- **Voice/tone** the copy must obey → `../brand-voice/SKILL.md`.
 - **Real experiment design** (sample size, significance) → the `ab-testing` skill.
-- **Reporting & dashboards** of the numbers → the `analytics` / `dashboard` skills.
 - **Blended/next-quarter revenue projection** → the `forecasting` skill.
-- **"Should we run paid at all?" / channel mix** → `../marketing/SKILL.md`.
 - **Top-of-funnel B2B prospect lists** (not paid media) → the `lead-gen` skill.
-
-## References
-
-- `references/platform-specs.md` — full asset spec tables per surface, image/video
-  orientations and sizes, the Low/Good/Best rotation playbook, the 25-asset-group rule,
-  and the Google Ads API version note for scripting.
-- `references/roas-model.md` — worked break-even and target-ROAS math, the
-  platform-ROAS vs MER vs incrementality table, a geo-holdout test design, and the
-  scale/hold/kill decision rule.

package/skills/agent-eval/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-eval
-description: "Use when you need to measure whether an LLM or agent system actually got better and gate merges on it — before/after a prompt or model change, building a golden set, fixing a noisy or inflated LLM-as-judge, scoring a RAG pipeline (faithfulness, contextual recall) or an agent trajectory (tool-correctness, task-completion), or choosing between DeepEval / Inspect AI / promptfoo / Braintrust. Triggers: 'is the new prompt actually better', 'build a golden set / regression suite', 'our judge gives everything a 9/10', 'fail the PR when answer quality drops', 'score the tool path not just the final answer', 'medir si el agente mejoró', 'tenim un eval que dona puntuacions inflades', 'montar un golden set'. NOT building the agent loop/tools/RAG plumbing (that is building-agents)."
+description: "Use when measuring whether an LLM or agent system actually got better and gating merges on it: golden sets, fixing an inflated LLM-as-judge, scoring RAG (faithfulness, contextual recall) or agent trajectories (tool correctness, completion), or picking an eval framework. NOT building the agent loop, tools or RAG plumbing (that is `building-agents`)."
 tags: [evals, llm, agents, llm-as-judge, regression-gate, ai]
 recommends: [building-agents, prompt-engineering, observability]
 origin: risco
@@ -10,24 +10,7 @@ origin: risco
 
 Turn "the agent feels better" into a number you can put in a PR check. You own the eval dataset, the scorer mix, the LLM-as-judge calibration, and the block-on-regression CI gate — framework-neutral, provider-neutral.
 
-## The one rule
-
-> A score you do not trust is worse than no score. Calibrate the scorer against human labels and report the agreement **before** you gate anything on it. An uncalibrated judge gives false confidence, which is more dangerous than admitted ignorance.
-
-> Build your own golden set. A public leaderboard number is not your number — identical model weights swing SWE-Bench Verified by 10–20 points just by changing the harness. Measure *your* task on *your* data.
-
-## When to use / When NOT
-
-**Use when:**
-- "Is the new prompt/model actually better?" — before/after on a fixed dataset.
-- "Build a golden set / regression suite for this agent."
-- "Our judge gives everything 9/10 / the scores are inflated" — judge calibration.
-- "Fail the PR when answer quality / faithfulness / tool-call accuracy drops" — CI gate.
-- Scoring a RAG pipeline (faithfulness, answer relevancy, contextual recall/precision).
-- Scoring an agent's *trajectory* — tool calls, task completion — not just the final string.
-- Picking between DeepEval / Inspect AI / promptfoo / Braintrust.
-
-**Do NOT use — route instead:**
+## Do NOT use — route instead
 
 | The ask | Route to | Why it is not this skill |
 | --- | --- | --- |
@@ -39,8 +22,6 @@ Turn "the agent feels better" into a number you can put in a PR check. You own t
 | Per-token cost budgets and accounting | `cost-tracking` | You report cost-per-task as one metric; the discipline lives there. |
 | A/B stats on product/funnel metrics | `ab-testing` | Web experiments, not offline model comparison on a fixed set. |
 
-(`building-agents`, `ab-testing`, `chatbot` are linkable siblings here; the rest are KNOWN ids you name but cannot link yet.)
-
 ## The eval anatomy
 
 Every framework instantiates the same five-stage pipeline. Learn it once; the tool is a detail.
@@ -56,7 +37,7 @@ DeepEval, Inspect AI, and promptfoo are all just opinionated wrappers around thi
 
 ## Build the dataset first
 
-The dataset is the asset. Everything else is replaceable. Rules:
+Build your own golden set — a public leaderboard number is not your number, because identical model weights swing SWE-Bench Verified by 10–20 points just by changing the harness. Measure *your* task on *your* data. The dataset is the asset; everything else is replaceable. Rules:
 
 - **50–200 hand-labeled cases per failure mode**, not per total. Coverage of how the system fails beats raw volume. 80 real failure cases > 1000 generic ones.
 - **Never synthetic-only.** A set the model wrote will not surface the model's blind spots. Mine real traffic / tickets / transcripts and hand-label.
@@ -112,13 +93,13 @@ class FaithfulnessJudge:
 
 ## LLM-as-judge you can trust
 
-A judge is a scorer, so the one rule applies hardest here. Each rule, with its why:
+A score you do not trust is worse than no score: an uncalibrated judge gives false confidence, which is more dangerous than admitted ignorance. Each rule, with its why:
 
 - **Judge model ≥ system under test.** A weaker judge cannot reliably rank a stronger system — it scores noise.
 - **The rubric must force a written rationale before the score.** Rationale-first judging is what pushes judge–human agreement to ~85% — higher than two humans agree with each other. A bare number is a vibe with a decimal point.
 - **Pairwise beats pointwise for stability.** "Is A or B better?" is more reproducible than "rate A from 1–10," which inflates and clusters at 8–9.
 - **Swap positions and average.** Judges favor whichever answer came first; run A-then-B and B-then-A to cancel position bias.
-- **Calibrate against human gold and report agreement** before you trust a single judge score.
+- **Calibrate against human gold and report the agreement before you gate anything on the judge.** Not a formality — this is the step that makes every number downstream defensible.
 
 > Bad judge prompt: "Rate this answer 1–10." → everything lands 8–9, useless.
 > Good: "Compare answer A and answer B against the reference. First write one sentence on each per the rubric, then output the better label." → forces reasoning, gives a stable signal.
@@ -139,7 +120,7 @@ Score the path, not only the destination. Beyond exact/judge:
 - **Task completion / goal accuracy** — did it finish the job, not just produce plausible text.
 - **Trajectory scoring** — grade the sequence of steps. A correct final answer from a wrong path will fail differently next time; only trajectory scoring catches it.
 
-The system side of these (how the loop and tools are built) is `../building-agents/SKILL.md`.
+The system side of these (how the loop and tools are built) is `../building-agents/SKILL.md`; a common system-under-test is `../chatbot/SKILL.md`.
 
 ## The regression gate
 
@@ -199,15 +180,8 @@ Pick by where the eval runs and what it must do. Versions as of 2026-06 — re-v
 
 ## Project grounding
 
-If the workspace has a `02-DOCS/` harness, record the eval policy in `02-DOCS/wiki/stack/evals.md`: dataset location, scorer mix, gate baseline file, judge model, and the failure modes covered. 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`), `timestamp` in ISO 8601, and standard markdown links — never wikilinks. Index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer). This is **recorded, not gated** — skip silently if there is no harness.
+If the workspace has a `02-DOCS/` harness, record the eval policy in `02-DOCS/wiki/stack/evals.md`: dataset location, scorer mix, gate baseline file, judge model, and the failure modes covered. Follow the harness [`wiki-article-template.md`](../harness/references/wiki-article-template.md) (`type: stack`) and index it in `02-DOCS/wiki/index.md`. This is **recorded, not gated** — skip silently if there is no harness.
 
 ## verify.sh
 
 `scripts/verify.sh` is read-only and tool-detecting. It validates that every `*.jsonl` golden set in the project parses and that each line carries the required `id`, `input`, `expected` keys; checks the shape of any `eval-report.json`; and runs `ruff` / `mypy` on example Python and `markdownlint` on docs when those tools are installed. Every missing tool prints a yellow WARN and is skipped — never a failure. An empty or clean target exits 0.
-
-## See also
-
-- `../building-agents/SKILL.md` — builds the agent/RAG/tool system you score here.
-- `../chatbot/SKILL.md` — a common system-under-test for these evals.
-- KNOWN siblings to route to (not yet linkable): `prompt-engineering`, `observability`, `agent-safety`, `cost-tracking`, `testing-py`, `ab-testing`.
-- External (no link): RAGAS, DeepEval, Inspect AI, promptfoo, Braintrust.

package/skills/agent-safety/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-safety
-description: "Use when putting guardrails on an LLM agent that already runs — limiting its task scope, gating its tools to least privilege, defending against prompt injection from untrusted content (web pages, emails, RAG docs), requiring human approval on irreversible actions, capping runtime, or after an agent did something it should not have. Triggers: 'lock down the MCP tools', 'the agent deleted prod', 'an email told it to wire money and it did', 'our support agent can run any shell command', 'the agent keeps repeating a wrong instruction across sessions', 'review what this autonomous agent is allowed to do before we ship', 'posa límits a l'agent', 'l'agent ha fet una cosa que no tocava'. NOT building the agent loop, tools, or RAG (that is building-agents)."
+description: "Use when bounding an LLM agent that already runs — scoping its task domain, gating tools to least privilege, defending against prompt injection in untrusted web/email/RAG text, requiring human approval on irreversible actions, capping runtime and cost, or triaging what it already did. NOT building the loop, tools, or RAG (that is `building-agents`)."
 tags: [agent-security, guardrails, prompt-injection, least-privilege, owasp-agentic]
 recommends: [building-agents, secure-coding, agent-eval]
 origin: risco
@@ -11,9 +11,14 @@ origin: risco
 You are the security review for an agent's **agency**, not for its code. The loop works,
 tools are wired, memory persists — your job is to make that autonomy *bounded*. If you
 want to review ordinary endpoints, auth, or secrets handling, that is
-`../secure-coding/SKILL.md`. If the loop or tools do not exist yet, that is
+`../secure-coding/SKILL.md` — this skill is the *Agentic* Top 10, the risks that exist only
+because a model has tools and autonomy. If the loop or tools do not exist yet, that is
 `../building-agents/SKILL.md`. You arrive *after* both.
 
+`references/threat-model.md` carries the OWASP Agentic Top 10 2026 risks mapped to the
+controls below, the pre-ship guardrail checklist, and the incident-triage flow for "the
+agent did X" — open it when you are reviewing before ship or reconstructing an incident.
+
 ## The ownership split
 
 Agent security splits into four layers — **Model · Harness · Tools · Environment**. The
@@ -162,15 +167,3 @@ Log every tool call (arguments redacted) and alert on repeated approval-bypass a
 | Scope/limits stated only in the prompt         | Prompt is advisory; the model can be talked out of it         | Enforce at the tool/harness boundary                |
 | No loop / cost / rate cap                       | A hijacked or looping agent runs until it runs out of money   | Hard fail-closed kill-switches                      |
 | Redact PII only in the UI                       | The secret was already written to memory/logs                 | Redact before persistence, at the source            |
-
-## References
-
-- `references/threat-model.md` — OWASP Agentic Top 10 2026 risks mapped to the controls
-  above, a pre-ship guardrail checklist, and an incident-triage flow for "the agent did X".
-
-## Related
-
-- `../building-agents/SKILL.md` — builds the loop, tools, RAG, MCP server. Hand off here once
-  it exists; it recommends secure-coding, agent-safety is the deeper guardrail layer.
-- `../secure-coding/SKILL.md` — STRIDE/OWASP for ordinary code and web endpoints. agent-safety
-  is the *Agentic* Top 10: risks that exist only because a model has tools and autonomy.

package/skills/ai-media/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ai-media
-description: "Use when turning a creative goal into a finished media file by orchestrating multiple generative-media models and gluing the pieces with ffmpeg — narrated explainer, product teaser, faceless short, AI voiceover, image-to-video clip, background score, or muxing/ducking/normalizing/stitching existing assets. Triggers: 'make a narrated video with AI voice and B-roll', 'generate a voiceover and mix it over the footage', 'duck the music under the voiceover', 'stitch the scene clips into one MP4 and normalize loudness', 'turn this still into a 9:16 clip with a music bed', 'genérame una voz en off y un vídeo para este guion con música de fondo', 'posa música de fons i abaixa-la quan parla la veu'. NOT still-image generation/editing (that is replicate-images)."
+description: "Use when a creative goal must become a finished media file: pick and order generative-media models per modality — AI voiceover, image-to-video clips, score — then glue them with ffmpeg (mux, duck, loudnorm, concat). NOT still-image generation/editing (that is `replicate-images`); NOT code-rendered React compositing (that is `remotion-video`)."
 tags: [ai-media, text-to-speech, image-to-video, voiceover, music-generation, ffmpeg, media-pipeline, elevenlabs]
 recommends: [replicate-images, fal, replicate, remotion-video, video-shorts]
 origin: risco
@@ -10,19 +10,15 @@ origin: risco
 
 You are the cross-modal director. You decide **which** generative-media model to call per modality, in **what order**, with **what params**, then **assemble** the pieces with ffmpeg into one finished file. You do not own a single provider's API surface and you do not prompt still images — you orchestrate and glue.
 
-## The one rule
-
-**Plan the whole pipeline before you generate a single asset.** Media generation is slow and metered: a re-roll of a 10 s Veo clip or a 90 s music track costs real money and minutes. Lock the scene list, the aspect ratio, the target loudness, and the model per modality *first*, then generate once. A draft pass at low res/short duration is cheaper than discovering at mux time that your clips are 9:16 and your VO is the wrong sample rate.
-
 ## Pipeline shape — decide what the goal needs
 
-Map the goal to modalities and an ordered step list. The "delegate to" column is where the actual call mechanics live — you pick the model and params, those skills run the call.
+Map the goal to modalities and an ordered step list, and **lock that plan before you generate a single asset** — media generation is slow and metered, so a re-roll of a 10 s Veo clip or a 90 s music track costs real money and minutes. Fixing the scene list, aspect ratio, target loudness and model per modality *first* is cheaper than discovering at mux time that your clips are 9:16 and your VO is the wrong sample rate. The "delegate to" column is where the actual call mechanics live — you pick the model and params, those skills run the call.
 
 | Goal | Needs | Ordered steps | Delegate calls to |
 |------|-------|---------------|-------------------|
 | Narrated explainer | stills + img→video + VO + music | script → per-scene stills → clip per scene → VO → music → conform → concat → mix+duck → loudnorm → MP4 | `replicate-images`, `fal`/`replicate` |
 | Product teaser (1 hero) | 1 still + img→video + music | still → clip → music → mix → loudnorm → MP4 | `replicate-images`, `fal`/`replicate` |
-| Faceless short | stills + img→video + VO + music + captions | (explainer pipeline) + burn captions | `replicate-images`, `video-shorts` for the script |
+| Faceless short | stills + img→video + VO + music + captions | (explainer pipeline) + burn captions | `replicate-images`; `../video-shorts/SKILL.md` for the script |
 | Just a voiceover | VO only | script → TTS → loudnorm | — |
 | Just a clip from a still | img→video only | still (input) → clip | `fal`/`replicate` |
 | Code-rendered explainer | none of the above | render from React/TS | **stop — route to `remotion-video`** |
@@ -96,7 +92,7 @@ Costs are per-minute and plan-dependent — treat them as approximate and **veri
 
 ## Assembly with ffmpeg
 
-Four operations. Each is a copy-paste recipe; full filter graphs and pitfalls are in `references/ffmpeg-assembly.md`.
+Four operations. Each is a copy-paste recipe; full filter graphs, caption burning and pitfalls are in `references/ffmpeg-assembly.md`.
 
 **(a) Mux VO onto video** — map both streams, copy video, take the shorter duration:
 
@@ -182,15 +178,3 @@ Emit this as a runnable script. `scripts/verify.sh` lints it (loudnorm present,
 | Shipping generated music without checking rights | "generated" ≠ "licensed to sell" — legal exposure | confirm commercial rights per model/plan |
 | Prompting/editing the still inside this skill | duplicates `replicate-images`' job, worse prompts | delegate the still, consume it here |
 | Mastering loudness by cranking the TTS | clipping, no true-peak control | set level with `loudnorm`, not the generator |
-
-## Hand-offs
-
-- Still-image generation/editing (the source frames) → `../replicate-images/SKILL.md`
-- The per-provider call mechanics (queue, webhook, FileOutput, cost) → `../fal/SKILL.md`, `../replicate/SKILL.md`
-- Code-rendered, frame-exact compositing in React/TS → `../remotion-video/SKILL.md`
-- Writing the short's script + cut direction → `../video-shorts/SKILL.md`
-
-## References
-
-- `references/models-and-params.md` — current per-modality model map (TTS tiers + output_format codes + per-char cost; img→video duration/aspect/fps/control/native-audio/open-source + fal & replicate endpoint ids; music cost/licensing/duration).
-- `references/ffmpeg-assembly.md` — full ffmpeg cookbook: mux, two-pass loudnorm, sidechaincompress with worked filter graphs, amix fallback, concat demuxer vs filter, conforming res/fps/SAR, burning captions, pitfalls.