@ericrisco/rsc 0.1.44 → 0.1.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "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,104 @@
+# 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.
+- 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. Close with:
+
+```text
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
+```
+
+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. Close it with:
+
+```text
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+```
+
+## 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.
+
+## 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.

package/skills/analytics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: analytics
-description: "Use when instrumenting product or web analytics — adding GA4 or PostHog to an app, designing an event taxonomy, wiring funnels, or making event collection consent-compliant. Triggers: 'set up GA4', 'install PostHog', 'track signup and checkout', 'design the event taxonomy', 'our purchase events fire twice / double-counting', 'PII leaking into event props', 'Consent Mode v2 broke our Google Ads conversions', 'missing client_id / distinct_id', 'instrumentar analítica de producto', 'añade GA4 / PostHog', 'los eventos se cuentan dos veces', 'consentiment abans de capturar dades'. NOT charting the captured data (that is dashboard), NOT choosing which metrics matter (that is kpi-framework), NOT experiment math (that is ab-testing), NOT the legal cookie text (that is gdpr-privacy)."
+description: "Use when instrumenting product or web analytics — GA4/PostHog SDK wiring, event taxonomy, funnels, double-counted events, consent gating, PII scrubbing. NOT charting that data (that is dashboard), NOT choosing which metrics matter (that is kpi-framework), NOT experiment math (that is ab-testing), NOT cookie-policy text (that is gdpr-privacy)."
 tags: [analytics, ga4, posthog, event-tracking, telemetry, consent-mode, funnels, privacy]
 recommends: [kpi-framework, ab-testing, gdpr-privacy, nextjs, dashboard, clickhouse-analytics]
 origin: risco
@@ -14,23 +14,7 @@ artifacts — an event taxonomy, tracking code (GA4 and/or PostHog), and a conse
 downstream of capture (charts, KPI choice, experiment stats, raw-event SQL, legal text) belongs to a
 sibling; see the routing table below.
 
-## The one rule that governs everything
-
-**An event name is a contract. Design the taxonomy before you write a single SDK call, and never rename a
-live event in production.** Why: every funnel, audience, dashboard, and saved insight downstream is keyed
-by the exact event name and property keys. Rename `signup_completed` to `sign_up` after launch and you
-silently fork the metric into two — the old funnel flatlines, the new one starts from zero, and nobody
-notices for a week. You can add events forever; you can never safely rename one. So the order of work is
-fixed: **taxonomy → SDK wiring → consent gate → PII scrub → funnel + validation.**
-
-## When to use
-
-- "Add analytics to my app", "set up GA4", "install PostHog", "track signups and checkout".
-- Designing or auditing an **event taxonomy** — naming convention, event-vs-property, identify-vs-anonymous.
-- Defining a **funnel** (signup → activation → purchase) and the events that feed it.
-- Debugging **double-counting**, missing `client_id`/`distinct_id`, or events that fire on every render.
-- Making collection **privacy-safe**: Consent Mode v2, opt-out, redacting emails/tokens from props.
-- **Server-side** events for actions off the browser (webhook, cron, payment confirmation).
+The order of work is fixed: **taxonomy → SDK wiring → consent gate → PII scrub → funnel + validation.**
 
 ## When NOT to use
 
@@ -46,9 +30,6 @@ fixed: **taxonomy → SDK wiring → consent gate → PII scrub → funnel + val
 | Predict future values from a series | `forecasting` |
 
 The load-bearing line: `analytics` = events flow **in**; `dashboard`/`reporting` = events flow **out**.
-`kpi-framework` decides *what* to measure; `analytics` makes the measurement *happen in code*.
-`ab-testing` owns the experiment math; `analytics` owns the event the experiment reads. `gdpr-privacy`
-owns the legal text; `analytics` owns the `gtag('consent', ...)` call and the PII scrubber.
 
 ## Decision: GA4 vs PostHog vs both
 
@@ -63,6 +44,12 @@ thing everywhere. Do not let the two tools drift into two naming schemes.
 
 ## Step 1 — Event taxonomy first, code second
 
+**An event name is a contract: design the taxonomy before you write a single SDK call, and never rename a
+live event in production.** Every funnel, audience, dashboard, and saved insight downstream is keyed by the
+exact event name and property keys. Rename `signup_completed` to `sign_up` after launch and you silently
+fork the metric into two — the old funnel flatlines, the new one starts from zero, and nobody notices for a
+week. You can add events forever; you can never safely rename one.
+
 Name events `object_action` in `snake_case`: `signup_completed`, `checkout_started`, `invoice_paid`. The
 **object** is the noun, the **action** is a past-tense verb. Detail goes in **properties**, never in the
 name — `cta_clicked` with `{ location: "navbar" }`, not three events `navbar_cta`, `hero_cta`, `footer_cta`.
@@ -208,12 +195,3 @@ the ≤ 40-char / leading-letter / charset rule; GA present without a `gtag('con
 | Server `user_id` ≠ browser `user_id` | Creates duplicate users; funnel splits | Use the same stable id on both sides; stitch within 48h |
 | `posthog.init` with no proxy host | Ad-blockers eat ~20-40% of events | Serve SDK + ingest under a first-party path (`/ingest`) |
 | Email as GA4 `user_id` | PII leak + Google policy violation | A stable opaque id (DB id / UUID) |
-
-## References
-
-- `references/ga4-setup.md` — gtag + Next.js install, full Consent Mode v2 with region-scoped defaults,
-  Measurement Protocol server event, recommended-event param tables, DebugView.
-- `references/posthog-setup.md` — `init` options, `identified_only`, EU vs US host, reverse proxy,
-  `@posthog/next` server capture, feature-flag read, autocapture tuning, `optIn`/`optOut`.
-- `references/event-taxonomy.md` — naming rules, starter SaaS + e-commerce catalog, property conventions,
-  identify vs group, the anti-rename rule.