rsc-universal 0.1.1

package/skills/astro/scripts/verify.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# verify.sh — Astro project static gate.
+#
+# Usage:
+#   bash scripts/verify.sh            # run from the Astro project root
+#
+# What it does (read-only, grep-based, no install required):
+#   1. FAIL  if a v6 project still uses src/content/config.ts instead of
+#            src/content.config.ts (the legacy path is removed on v6 →
+#            LegacyContentConfigError).
+#   2. WARN  on over-hydration smells: many `client:load`, or `client:only`
+#            with no framework string.
+#   3. CHECK content schemas import from `astro:content`.
+#   4. If the `astro` binary resolves, OPTIONALLY run `npx astro check`
+#      (type/diagnostic check; read-only). Skipped if not resolvable.
+#
+# Exit code: non-zero ONLY on a real FAIL. Warnings are advisory. On an empty
+# or clean tree it prints OK and exits 0 (no false failure).
+#
+# Portability: targets stock macOS bash 3.2. No `mapfile`, no jq, no node
+# required for the grep checks. `set -e` is intentionally NOT used; `set -u` is.
+
+set -u
+
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+failures=0
+warnings=0
+have() { command -v "$1" >/dev/null 2>&1; }
+fail() { printf '%s\n' "${RED}FAIL: $1${RESET}"; failures=$((failures + 1)); }
+warn() { printf '%s\n' "${YELLOW}WARN: $1${RESET}"; warnings=$((warnings + 1)); }
+ok()   { printf '%s\n' "${GREEN}OK: $1${RESET}"; }
+skip() { printf '%s\n' "${YELLOW}SKIP: $1${RESET}"; }
+
+# Is this even an Astro project? If not, exit clean (no false failure).
+if [ ! -f astro.config.mjs ] && [ ! -f astro.config.ts ] && [ ! -f astro.config.js ] \
+   && ! grep -rq '"astro"' package.json 2>/dev/null; then
+  ok "no Astro project detected here — nothing to check"
+  exit 0
+fi
+
+# Source files to scan (skip node_modules / dist / .astro). Empty list is fine.
+src_files() {
+  find . \( -name node_modules -o -name dist -o -name .astro -o -name .vercel \
+            -o -name .netlify \) -prune -o \
+    -type f \( -name '*.astro' -o -name '*.ts' -o -name '*.tsx' \
+               -o -name '*.jsx' -o -name '*.mdx' \) -print 2>/dev/null
+}
+
+# Detect Astro major version (best-effort, bash-3.2 safe). Echoes a bare integer or nothing.
+astro_major() {
+  [ -f node_modules/astro/package.json ] || return 0
+  ver="$(grep -m1 '"version"' node_modules/astro/package.json 2>/dev/null \
+         | sed -e 's/.*"version"[^0-9]*//' -e 's/[^0-9].*//')"
+  [ -n "$ver" ] && printf '%s' "$ver"
+}
+
+# --- 1. content config path ------------------------------------------------
+# On v6 the only valid path is src/content.config.ts. The old src/content/config.ts
+# is removed (LegacyContentConfigError). Treat its presence as a FAIL on v6, a WARN if version unknown.
+if [ -f src/content/config.ts ]; then
+  amajor="$(astro_major)"
+  if [ -n "$amajor" ] && [ "$amajor" -ge 6 ] 2>/dev/null; then
+    fail "src/content/config.ts exists on Astro ${amajor} — rename to src/content.config.ts (legacy path removed in v6)"
+  else
+    warn "src/content/config.ts found — on Astro 6 this must be src/content.config.ts"
+  fi
+elif [ -f src/content.config.ts ]; then
+  ok "content config at src/content.config.ts"
+else
+  skip "no content config found — collections not in use"
+fi
+
+# --- 2. content schema imports ---------------------------------------------
+# A content config should import defineCollection/z from astro:content.
+if [ -f src/content.config.ts ]; then
+  if grep -q 'astro:content' src/content.config.ts; then
+    ok "content schema imports from astro:content"
+  else
+    warn "src/content.config.ts does not import from astro:content — schemas may be untyped"
+  fi
+fi
+
+# --- 3. over-hydration smell -----------------------------------------------
+# Count client:load occurrences and flag a high count; flag client:only without a framework.
+load_count=0
+only_bad=0
+files="$(src_files)"
+if [ -n "$files" ]; then
+  load_count="$(printf '%s\n' "$files" | xargs grep -ho 'client:load' 2>/dev/null | grep -c 'client:load')"
+  # client:only that is NOT immediately followed by ="<framework>"
+  only_bad="$(printf '%s\n' "$files" \
+    | xargs grep -hoE 'client:only(="[^"]+")?' 2>/dev/null \
+    | grep -c 'client:only$' )"
+fi
+[ -z "$load_count" ] && load_count=0
+[ -z "$only_bad" ] && only_bad=0
+
+if [ "$load_count" -gt 5 ] 2>/dev/null; then
+  warn "client:load appears ${load_count} times — prefer client:visible/idle/media; first-paint JS hurts LCP"
+elif [ "$load_count" -gt 0 ] 2>/dev/null; then
+  ok "client:load used sparingly (${load_count})"
+else
+  ok "no client:load directives (static-first)"
+fi
+
+if [ "$only_bad" -gt 0 ] 2>/dev/null; then
+  warn "client:only used without a framework string (e.g. client:only=\"react\") in ${only_bad} place(s)"
+fi
+
+# --- 4. optional astro check ----------------------------------------------
+if [ -x node_modules/.bin/astro ] || have astro; then
+  printf '%s\n' "Running astro check... (read-only diagnostics)"
+  if [ -x node_modules/.bin/astro ]; then
+    if node_modules/.bin/astro check; then ok "astro check"; else fail "astro check"; fi
+  elif have npx; then
+    if npx --no-install astro check; then ok "astro check"; else fail "astro check"; fi
+  fi
+else
+  skip "astro binary not resolvable — skipping astro check"
+fi
+
+# --- summary ---------------------------------------------------------------
+printf '\n'
+if [ "$warnings" -gt 0 ]; then
+  printf '%s\n' "${YELLOW}verify.sh: ${warnings} warning(s) — advisory${RESET}"
+fi
+if [ "$failures" -gt 0 ]; then
+  printf '%s\n' "${RED}verify.sh: ${failures} check(s) failed${RESET}"
+  exit 1
+fi
+printf '%s\n' "${GREEN}verify.sh: all runnable checks passed${RESET}"
+exit 0

package/skills/author-skill/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: author-skill
+description: "Use when authoring a NEW skill or editing an existing one for the rsc catalog — writing or fixing a SKILL.md, crafting a trigger-rich third-person description that fires on the right prompts, deciding what goes in references/ vs the body, writing evals/cases.yaml + evals/README.md, or wiring a skill into the catalog (tags, recommends, manifest). Triggers: 'write a skill', 'author a skill', 'create a new skill', 'escribe una skill', 'haz una skill nueva', 'edit this skill', 'improve this skill', 'my skill never triggers', 'my skill always fires', 'fix the description', 'the frontmatter is invalid', 'write evals for this skill', 'add this skill to the catalog', 'audit this skill against the rubric', 'progressive disclosure', 'SKILL.md too long'. Knows the rsc conventions: hybrid layout, tags/recommends frontmatter, manifest.json, the npx rsc CLI, the Knowledge map. NOT building runtime features (that is the SDD chain) and NOT general docs."
+tags: [skill, authoring, meta]
+recommends: []
+origin: risco
+---
+
+# author-skill — write skills that trigger and teach
+
+This is the **meta skill**: it authors and edits the other skills in the rsc catalog. A skill is two things bolted together — a **description that fires at the right moment**, and a **body that makes the agent better once it fires**. Most skills fail on the first. This skill exists to get both right, to the bar the rsc catalog already holds.
+
+It lives in `rsc-core` next to `init` and `harness`, the same way those govern the workspace. Where the SDD chain (`specify` → `plan` → … → `ship`) builds *product*, `author-skill` builds *the tools that build product*. Use it whenever a skill is born or edited.
+
+## When to use / when NOT to use
+
+Use when:
+
+- Writing a brand-new skill from a one-line intent ("I keep re-explaining how we do X — make it a skill").
+- Editing an existing skill: tightening the description, splitting the body into `references/`, adding a checklist or anti-patterns table.
+- A skill mis-triggers — never fires when it should, or fires on everything.
+- Writing or repairing `evals/cases.yaml` + `evals/README.md`.
+- Wiring a finished skill into the catalog — `tags`, `recommends`, and the manifest (the rsc plumbing).
+- Auditing a skill against the rubric below before it ships.
+
+Do NOT use when (delegate or decline):
+
+- The user wants to *build a product feature* with a written spec/plan — that is the SDD chain (`../specify/SKILL.md` → `../plan/SKILL.md` → …), not a skill.
+- The user wants to design an autonomous agent / tool-calling loop — that is `../building-agents/SKILL.md`.
+- The user wants generic project docs or a wiki article — that is the `../harness/SKILL.md` 02-DOCS engine.
+- Bootstrapping a workspace or profiling the user — that is `../init/SKILL.md`.
+
+## Read the user profile first (accompaniment dial)
+
+Before writing, read `02-DOCS/wiki/harness/user-profile.md` for the technical level and the accompaniment dial, and **adapt**:
+
+- **L0** — draft the whole skill, show it, move on. Minimal narration.
+- **L1** — one line of *why* per major choice (why this trigger, why split that reference).
+- **L2** — justify each structural decision as you make it.
+- **L3** — explain everything, ask before committing to a name/scope, walk the rubric out loud.
+
+When no profile exists, default to non-technical framing and ask the two gauging questions (technical level + dial) before going deep. Skill authoring is itself a technical act — many users will want L2/L3 here even if they run L0 elsewhere.
+
+## What a skill is (the anatomy)
+
+```text
+skills/<id>/
+├── SKILL.md              the body: frontmatter (name + description + origin) then the prose
+├── references/           progressive-disclosure detail, loaded only when the body points to it
+│   └── <topic>.md
+├── evals/
+│   ├── cases.yaml        trigger + capability test cases
+│   └── README.md         how to run the evals, honestly
+└── scripts/              optional; verify.sh + helpers for skills with a checkable artifact
+    └── verify.sh
+```
+
+The **frontmatter** decides *if* the skill loads. The **body** decides *how good* the agent is once it does. Treat them as two separate engineering problems with two separate quality bars.
+
+## The description — the single highest-leverage line
+
+The description is the only part of a skill the agent reads at *every* turn to decide whether to pull the skill in. A vague description is a skill that never fires; an over-broad one is a skill that hijacks unrelated turns. Get this right before anything else.
+
+Rules, all enforced:
+
+1. **Third person, present tense.** "Use when authoring a new skill…" — never "I help you…" or "You should…". The agent is reading *about* the skill.
+2. **Trigger-rich.** Lead with a `Use when …` clause naming the *situations* and *symptoms*, then a `Triggers:` list of concrete phrasings — including non-obvious ones and at least one other language the user actually writes in (rsc users mix Spanish/Catalan). The router matches on these.
+3. **Draw the boundary.** End with what it is **NOT** and which sibling owns that instead. Negative space prevents hijacking as much as positive triggers cause firing.
+4. **≤ 1024 characters, valid single-line quoted YAML.** One physical line, wrapped in double quotes, internal quotes escaped or avoided. If it does not parse, the skill does not load.
+5. **`origin: risco`** on its own line. This marks it as ours.
+
+```yaml
+# Good — situation + symptoms + phrasings + boundary
+description: "Use when X happens or the user shows symptom Y — doing A, fixing B, choosing C. Triggers: 'phrase one', 'frase en español', 'a non-obvious one'. NOT Z (that is `sibling`)."
+
+# Bad — first person, no triggers, no boundary, would never route well
+description: "I help you write great skills and make them work."
+```
+
+The full description recipe, the character-budget tactics, and a worked before/after → `references/description-recipe.md`.
+
+## Progressive disclosure — the body is an index, not an encyclopedia
+
+The body is loaded in full whenever the skill fires, so every line competes for the agent's attention. Keep the body **~120–400 lines**: the method, the rules, the decision points, and *pointers* to depth. Push anything long, reference-like, or rarely-needed into `references/<topic>.md` and link to it inline ("full table → `references/foo.md`").
+
+Decide where a paragraph lives:
+
+| Put it in the body when… | Move it to references/ when… |
+| --- | --- |
+| The agent needs it on *every* run | It is needed only in a specific branch |
+| It is a rule, a gate, or a decision point | It is a long table, a catalog, or a template |
+| It is short and load-bearing | It is reference detail that would bloat the body |
+| Cutting it would change behavior | It is an example that illustrates but does not instruct |
+
+If the body creeps past ~400 lines, that is the signal to extract a reference — not to keep scrolling. A skill the agent half-reads is worse than a short one it reads fully.
+
+## The hybrid structure — when each piece earns its place
+
+- **SKILL.md** — always. Frontmatter + focused body.
+- **references/** — only when the body genuinely needs offloaded depth. Do not create an empty `references/` to look complete; a 150-line single-file skill is fine.
+- **evals/** — always. `cases.yaml` + `README.md`. A skill with no evals is unverifiable and does not ship.
+- **scripts/verify.sh** — only when the skill produces a *checkable artifact* (code, config, copy with a ban-list). **Process skills** — those judged on the safety rails they install in the agent's behavior, like the SDD-phase skills or this one — do **not** ship a `verify.sh`; their evals carry a capability scenario instead.
+
+## Orientation footer (required in every new skill)
+
+Every new skill MUST end with the orientation footer so the harness never leaves the user in seco. Append verbatim:
+
+````markdown
+
+## Orientación (siempre)
+
+Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)
+````
+
+The full protocol lives once in the `orient` skill; the footer only references it.
+
+## The authoring workflow
+
+Run in order. Each step gates the next.
+
+1. **Name & scope.** One skill, one job. Pick a short kebab-case `<id>` that is the job, not the domain. If you can not say the job in one sentence, the scope is wrong — split it. Check no sibling already owns this; if one half-owns it, decide *edit the sibling* vs *new skill* before writing.
+2. **Draft the description.** Per the recipe above. This first, because writing it forces the scope clear. → `references/description-recipe.md`.
+3. **Outline the body.** Method, rules, decision points. Mark what becomes a reference.
+4. **Write the body** in the rsc voice (see below). Tag every code/example fence with a language. Add a copy-able checklist or decision table *only where the flow actually branches* — not as decoration. Add a short anti-patterns table.
+5. **Extract references** for anything long or branch-specific.
+6. **Write the evals** — `cases.yaml` then `README.md`. → `references/eval-authoring.md`.
+7. **Wire it into the rsc plumbing** (`tags`, `recommends`, `npm run manifest`, Knowledge map). → `references/rsc-conventions.md`.
+8. **Self-audit against the rubric** (below). Fix every miss or justify it.
+
+## The rsc voice
+
+Match the catalog, do not invent a new register:
+
+- Direct, second-person-to-the-agent instruction ("Read the profile first", "Cut any section with no job").
+- Rules stated as non-negotiables with a one-line *why*, not a lecture.
+- Concrete over abstract: a number, a path, a Bad→Good pair beats an adjective.
+- Original prose. Mine ideas from anywhere; the words are Eric's. Do **not** reproduce another ecosystem's signature artifacts or phrasing — no borrowed "1% chance" urgency blocks, no copied rationalization wording, no `*-reviewer-prompt.md` files, no verbatim flowcharts. The rsc identity is its own.
+- Cross-reference siblings by name or `../<sibling>/SKILL.md`, only ones that actually exist.
+
+## The best-practice rubric (audit before shipping)
+
+A skill ships only when every box is checked or a miss is consciously justified.
+
+- [ ] **Frontmatter parses** as YAML; `name` matches the directory `<id>`; `origin: risco` present.
+- [ ] **Description ≤ 1024 chars**, third-person, `Use when…` lead, concrete `Triggers:` (incl. a non-obvious and a non-English phrasing), and a `NOT … (that is sibling)` boundary.
+- [ ] **One job.** The body never drifts into a second skill's territory; it delegates instead.
+- [ ] **Body 120–400 lines**, focused; long/branch-specific material lives in `references/`.
+- [ ] **Progressive disclosure** real — references are pointed to inline, not orphaned.
+- [ ] **Every fence language-tagged**; no placeholder/TODO prose; examples concrete.
+- [ ] **Checklist/decision table only where a flow branches**; an **anti-patterns table** present.
+- [ ] **Accompaniment dial honored** — reads the profile, adapts verbosity.
+- [ ] **Artifacts under `02-DOCS/wiki/`** and indexed in the root CLAUDE.md Knowledge map, if the skill produces any.
+- [ ] **Concrete tooling delegated** to the stack skills rather than reinvented.
+- [ ] **evals present** — `cases.yaml` (≥5 `should_trigger` incl. non-obvious, ≥4 `should_not_trigger` each with a real-sibling `route_to`, ≥1 `capability` with a `must_include` rubric) + an honest `README.md`. `scripts/eval-lint.sh` passes — but it only checks presence and the counts (≥5/≥4/≥1) and that those keys are lists; the `route_to`-points-at-a-real-sibling, non-obvious phrasings, and `must_include` quality are yours to verify here, not the linter's.
+- [ ] **verify.sh** present iff the skill has a checkable artifact; process skills rely on evals.
+- [ ] **Sibling links resolve** — every `../x/SKILL.md` points to a skill that exists.
+- [ ] **Wired** — `tags` + `recommends` set, `npm run manifest` re-run, and `npm run validate` / `npm run manifest:check` pass (manifest current, no dangling recommends).
+
+Full rubric rationale and the rsc plumbing steps → `references/rsc-conventions.md`.
+
+### Two ship gates: document AND behavior
+
+The rubric above scores the skill as a **document**. That is one of two gates — a skill ships
+only when **both** are green:
+
+1. **Static** — the rubric above / `scripts/skill-rubric.md`, weighted score ≥ 8.5.
+2. **Behavioral** — `scripts/skill-behavior-rubric.md`: run the skill on its `capability`
+   scenarios **with and without** it loaded, blind-grade both outputs, require `absolute ≥ 8.5`
+   **and** `lift ≥ +1.0`. Run it:
+
+   ```bash
+   # 1) execute + grade — invoke the Workflow tool:
+   #      scriptPath: scripts/skill-behavior-eval.workflow.js   args: "<skill-id>"
+   #    save the returned object to /tmp/<skill>-raw.json
+   # 2) score + gate (exit 0 pass / 1 fail):
+   node scripts/skill-behavior-eval.js --score /tmp/<skill>-raw.json
+   ```
+
+   A failing `lift` means the body adds nothing a bare agent didn't already do — fix the body,
+   don't game the checklist.
+
+## Anti-patterns / rationalizations → STOP
+
+| Rationalization | Reality / fix |
+| --- | --- |
+| "I'll polish the description later, the body matters more" | The description is *why the body ever runs*. Write it first, to bar. |
+| "More triggers = fires more = better" | Over-broad descriptions hijack unrelated turns. Add the `NOT` boundary and prune. |
+| "One skill that does specify + plan + implement is convenient" | One skill, one job. A multi-job skill triggers fuzzily and teaches poorly. Split it. |
+| "The body is long because the topic is rich" | Past ~400 lines the agent skims. Extract references; keep the body an index. |
+| "I'll skip evals, I'll just test it by hand once" | Unverifiable = does not ship. Write `cases.yaml`, including near-misses with `route_to`. |
+| "It's basically superpowers' writing-skills, I'll mirror it" | Mine the idea, write it in the rsc voice. Copied artifacts/phrasing are a defect. |
+| "I'll add a `references/` folder so it looks thorough" | Empty references are noise. Add depth only where the body points to it. |
+| "verify.sh on every skill is more rigorous" | A process skill has no artifact to grep. Its rigor is the capability eval. |
+| "Linking `../foo/SKILL.md` is fine even if foo isn't in this repo" | A dead link is a defect. Reference only siblings that exist. |
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+When authoring produces a durable design note (a skill's scope decision, a description rationale worth keeping), persist it under `02-DOCS/wiki/sdd/` and add a row to the root CLAUDE.md `## Knowledge map`, per the `../harness/SKILL.md` convention — never a stray file at the repo root. The skill's own `evals/` is the executable record of intent; the wiki note is the human-readable why.
+
+## See Also
+
+- `../harness/SKILL.md` — the 02-DOCS Knowledge-map convention these artifacts live in; the bar this catalog holds.
+- `../init/SKILL.md` — the front door that profiles the user and sets the dial this skill reads.
+- `../building-agents/SKILL.md` — for autonomous agents/tool-loops, a different craft than authoring a skill.
+- `../specify/SKILL.md` — when the user wants a *product feature* specced, not a skill authored.
+- References: `references/description-recipe.md`, `references/eval-authoring.md`, `references/rsc-conventions.md`.

package/skills/author-skill/evals/README.md

@@ -0,0 +1,66 @@
+# Eval harness — `author-skill`
+
+Evaluates the `author-skill` meta skill (the rsc-core tool that authors/edits other skills)
+on two axes: **triggering** (does it fire on the right prompts and stay quiet on near-misses)
+and **capability** (does loading it measurably improve the skill the agent produces). Cases
+live in `cases.yaml`. These run via an **agent harness**, not a deterministic script — a human
+or a driver agent feeds prompts to Claude Code and judges the result against the rubrics.
+
+## What's in `cases.yaml`
+
+- `should_trigger` (7) — prompts that MUST invoke `author-skill`, including a non-obvious
+  symptom phrasing ("my skill never triggers") and a non-English one ("escribe una skill nueva").
+- `should_not_trigger` (5) — near-misses that must route elsewhere; `route_to` names the real
+  sibling that owns each (`plan`, `building-agents`, `init`, `harness`, `specify`).
+- `capability` (2) — scenarios with `must_include` rubrics to grade WITH vs WITHOUT the skill:
+  authoring a new skill end-to-end, and repairing a broken triggering description.
+
+## A. Triggering eval
+
+1. Load **only** `author-skill` into the agent (no other rsc skills available, so routing is honest).
+2. For each `should_trigger` prompt: open a fresh session, paste the prompt verbatim, and record
+   whether `author-skill` activates (the agent should lead with scope/description work, not jump
+   into building a product feature). Run **3–5 trials** per prompt.
+3. For each `should_not_trigger` prompt: same procedure, but a **pass** = `author-skill` does NOT
+   fire. Where a `route_to` sibling exists, sanity-check that the prompt genuinely belongs there
+   (e.g. "turn this spec into a plan" really is `plan`, not skill authoring).
+4. Score: a prompt passes if the **majority of its trials** go the expected way.
+
+**Pass bar:** ≥ 90% trigger accuracy across all `should_trigger` + `should_not_trigger` prompts
+(at most 1 of the 12 prompts may misbehave).
+
+## B. Capability eval
+
+1. **Without the skill:** fresh session, skill NOT loaded, give the `scenario` prompt. Save output A.
+2. **With the skill:** fresh session, `author-skill` loaded, same prompt. Save output B.
+3. Grade each output against that scenario's `must_include` points — count points clearly covered.
+4. Repeat across **3 trials** per scenario per condition and average the coverage.
+
+**Pass bar:** WITH the skill covers **≥ 80%** of `must_include` points; WITHOUT the skill is
+materially lower (target a ≥ 30-point gap). If the skill doesn't measurably beat the baseline,
+the skill — or these rubrics — needs work.
+
+## The headline differentiators
+
+What a WITH-skill answer should show that a baseline misses:
+
+- **Description first**, to the recipe: third-person `Use when…` lead, concrete `Triggers:`
+  (incl. a non-obvious and a non-English phrasing), a `NOT … (sibling)` boundary, valid
+  single-line quoted YAML ≤ 1024 chars, `origin: risco`.
+- **Progressive disclosure** — a focused 120–400 line body that points into `references/`, not
+  an encyclopedia and not an orphaned references folder.
+- **evals authored** to the minimums, with `route_to` siblings that actually exist.
+- **No `verify.sh` on a process skill** — rigor comes from the capability eval.
+- **rsc wiring** named: `tags` + `recommends` frontmatter, `npm run manifest` regenerated,
+  `npm run validate` / `manifest:check` passing, `eval-lint.sh` passing.
+- **Original rsc voice** — no copied artifacts/phrasing from other skill ecosystems.
+
+## Judging notes (honest caveats)
+
+- This is **LLM-as-judge / human-in-the-loop**, not deterministic. Use a consistent grader
+  (same model + rubric) across A/B to keep the comparison fair.
+- `scripts/eval-lint.sh` deterministically checks only the *case-count minimums* of any
+  `cases.yaml` this skill produces; it does not judge prose quality — that is the human/LLM grade.
+- Watch the key confusables: building a *product feature* (the SDD chain) and designing an
+  *agent loop* (`building-agents`) are different artifacts than authoring a *skill*.
+- Re-run after any edit to `SKILL.md` or its `description`, since both axes are wording-sensitive.

package/skills/author-skill/evals/cases.yaml

@@ -0,0 +1,75 @@
+skill: author-skill
+
+# Cases for the rsc-core "author-skill" meta skill.
+# author-skill authors or edits a SKILL.md to the rsc catalog bar: a trigger-rich
+# third-person description (<=1024, valid YAML, origin: risco), a focused body with
+# progressive disclosure into references/, the best-practice rubric, and an
+# evals/cases.yaml + README for the NEW skill, plus the rsc plumbing (tags,
+# recommends, manifest.json, Knowledge map). It is NOT for building a
+# product feature (the SDD chain), NOT for agent loops (building-agents), and NOT
+# for generic project docs (harness).
+
+should_trigger:
+  - prompt: "I keep re-explaining how we do code reviews to the agent every session. Turn that into a skill."
+    why: "Canonical 'born a skill' moment phrased as a symptom, no skill jargon — author-skill's core job is turning a recurring instruction into a SKILL.md with a triggering description and evals."
+
+  - prompt: "Escribe una skill nueva para generar informes de incidencias."
+    why: "Non-English (Spanish) verbatim 'write a new skill' request — the description must match the user's actual language, and author-skill owns new-skill authoring end to end."
+
+  - prompt: "My skill never triggers even when it obviously should. What's wrong with it?"
+    why: "Non-obvious symptom phrasing (no mention of 'skill authoring') pointing straight at the description craft — diagnosing/repairing a description that fails to route is exactly this skill's highest-leverage area."
+
+  - prompt: "This SKILL.md is 600 lines and feels bloated. Help me restructure it."
+    why: "Edit/refactor of an existing skill toward progressive disclosure — author-skill's body-vs-references decision table and the 120-400 line target are the direct fix."
+
+  - prompt: "Write the evals/cases.yaml for the skill I just drafted, with trigger and capability tests."
+    why: "Eval authoring for a skill is squarely owned here (the should_trigger/should_not_trigger/route_to and capability rubric minimums) — a deliberately specific, non-obvious trigger."
+
+  - prompt: "Audit this skill against our best-practice rubric before I add it to the catalog and run npm run manifest."
+    why: "Combines the rubric audit and the rsc plumbing (tags, recommends, manifest) — both are author-skill responsibilities; this exercises the wiring + rubric surface."
+
+  - prompt: "The frontmatter on my skill won't parse and the description is over 1024 chars. Fix it."
+    why: "A concrete description/frontmatter defect (valid YAML, <=1024) — the description recipe and the YAML/length verifier are author-skill's, not any stack skill's."
+
+should_not_trigger:
+  - prompt: "I have a written spec for a new feature — turn it into an implementation plan."
+    route_to: "plan"
+    why: "Building a PRODUCT feature from a spec is the SDD chain (plan), not authoring a reusable skill. author-skill builds the tools that build product, not the product."
+
+  - prompt: "Help me design an autonomous agent with a tool-calling loop and memory."
+    route_to: "building-agents"
+    why: "Designing an agent/tool-loop is building-agents. A 'skill' (a SKILL.md that loads into the agent) is a different artifact than an autonomous agent runtime."
+
+  - prompt: "Bootstrap my workspace and figure out which rsc bundles I need."
+    route_to: "init"
+    why: "Profiling the user and recommending bundles is the front door (init). author-skill assumes a skill is being written; it does not gauge the user or recommend bundles to install."
+
+  - prompt: "Consolidate my scattered project notes into a wiki article under 02-DOCS."
+    route_to: "harness"
+    why: "Generic docs/wiki consolidation is the harness 02-DOCS engine. author-skill writes SKILL.md + evals, not project knowledge articles, even though it persists the occasional design note via harness."
+
+  - prompt: "Turn this fuzzy product idea into a clear spec of what and why."
+    route_to: "specify"
+    why: "Specifying a product's intent is the specify phase of the SDD chain. A spec is not a skill; author-skill would only be relevant if the artifact being authored were itself a skill."
+
+capability:
+  - scenario: "A user says: 'I keep telling the agent how to write our PR descriptions. Make that into a skill called pr-describe.' Show how author-skill produces it to the rsc bar."
+    must_include:
+      - "Reads 02-DOCS/wiki/harness/user-profile.md for the accompaniment dial (or asks the two gauging questions if absent) and adapts verbosity"
+      - "Confirms scope is one job and checks no existing sibling already owns PR-description authoring before creating a new skill"
+      - "Drafts the description FIRST: third-person, 'Use when…' lead, concrete Triggers including a non-obvious symptom phrasing and a non-English one, a 'NOT … (that is `sibling`)' boundary, valid single-line quoted YAML <=1024 chars, with origin: risco"
+      - "Produces a focused body (~120-400 lines) with progressive disclosure — long/branch-specific detail pushed to references/ and pointed to inline, not an orphaned references/ folder"
+      - "Language-tags every code/example fence and includes an anti-patterns table; adds a checklist/decision table only where a flow actually branches"
+      - "Writes evals/cases.yaml meeting the minimums (>=5 should_trigger incl. non-obvious, >=4 should_not_trigger each with a real-sibling route_to, >=1 capability with a must_include rubric) plus an honest evals/README.md describing the two-axis run"
+      - "Decides NO scripts/verify.sh because a PR-description skill is a process skill judged on its capability eval, OR includes verify.sh only if it emits a checkable artifact — and justifies the choice"
+      - "States the rsc wiring: set tags + recommends in frontmatter, run npm run manifest to regenerate manifest.json, and confirm npm run validate / manifest:check / scripts/eval-lint.sh pass"
+      - "Keeps the prose original in the rsc voice — does not reproduce another ecosystem's signature artifacts or phrasing"
+
+  - scenario: "A user pastes a skill whose description is 'I help you with deployments' and says 'it fires on everything and also misses real deploy questions — fix the triggering.' Show the description repair."
+    must_include:
+      - "Diagnoses the two failure modes: first-person + no boundary causes hijacking; no concrete Triggers/situation causes misses"
+      - "Rewrites to third-person with a 'Use when…' situation lead and concrete verb phrases"
+      - "Adds a Triggers: list of real phrasings including a non-obvious symptom and a non-English one"
+      - "Adds a 'NOT … (that is `sibling`)' boundary naming the real sibling(s) that own the excluded turns to stop hijacking"
+      - "Verifies the result is valid single-line quoted YAML and <=1024 chars (e.g. via the python YAML/length check) and keeps origin: risco"
+      - "Recommends updating evals/cases.yaml (especially should_not_trigger with route_to) and re-running the triggering eval, since description edits are wording-sensitive"

package/skills/author-skill/references/description-recipe.md

@@ -0,0 +1,84 @@
+# The description recipe
+
+The description is the only line the router reads on every turn to decide whether to load the skill. It is a *retrieval problem*, not a marketing problem. Write it to be matched, not admired.
+
+## The shape
+
+```text
+"Use when <SITUATION / SYMPTOM> — <verb phrase>, <verb phrase>, <verb phrase>.
+ Triggers: '<phrase>', '<frase en español>', '<non-obvious phrase>', ….
+ [Optional one clause naming what it KNOWS / owns.]
+ NOT <out-of-scope thing> (that is `sibling`) and NOT <other> (that is `sibling`)."
+```
+
+Four moves, in order:
+
+1. **Lead with the situation.** The first clause is a `Use when …` that names *when in the user's day* this fires — the moment, the symptom, the pain. The router matches situations better than nouns. "Use when a skill mis-triggers" beats "skill quality tool".
+2. **List concrete verb phrases.** Right after the lead, name the 3–6 things the skill actually does, as verbs ("writing a description", "splitting the body", "repairing cases.yaml"). These are dense match surface.
+3. **Add a `Triggers:` phrase list.** Real phrasings a user types — quoted. Include:
+   - at least one **non-obvious** phrasing (a symptom, not the skill's name): e.g. "my skill never triggers".
+   - at least one **non-English** phrasing (rsc users write Spanish/Catalan): e.g. "escribe una skill".
+   - the slash-command form if relevant.
+4. **Close with the boundary.** One or two `NOT … (that is `sibling`)` clauses. This is not optional decoration — negative space is what stops the skill from hijacking adjacent turns. Name the *real* sibling that owns the excluded job.
+
+## The hard constraints
+
+- **≤ 1024 characters.** Count them. Over budget = trim verb phrases and trigger duplicates first, never the boundary.
+- **Valid single-line quoted YAML.** The description is one physical line wrapped in double quotes. No raw newlines inside the value. Avoid characters that break YAML in double quotes; if you need an apostrophe inside, it is fine (single quotes are literal inside double-quoted YAML). Never put an unescaped `"` inside.
+- **Third person, present tense.** The agent reads *about* the skill. "Use when…", "Triggers on…", "Knows…". Never "I", never "you should".
+
+## Budget tactics when you blow 1024
+
+In priority order, cut:
+
+1. Duplicate triggers that match the same situation ("write a skill" + "create a skill" — keep one).
+2. Verb phrases already implied by a trigger phrase.
+3. The optional "Knows…" clause.
+4. Shorten the boundary to one `NOT` clause naming the single most-confused sibling.
+
+Never cut: the `Use when` lead, at least 3 distinct triggers, one non-English trigger, one `NOT` boundary.
+
+## Worked before → after
+
+**Before** (first person, no triggers, no boundary — 71 chars, would route badly):
+
+```yaml
+description: "I help you write and improve skills so they work well."
+```
+
+Problems: first person; no `Use when`; zero concrete phrasings for the router; no boundary, so it competes with `building-agents`, `specify`, and `init` on every "make a thing" turn.
+
+**After** (third person, situation + verbs + phrasings + boundary, valid YAML, well under 1024):
+
+```yaml
+description: "Use when authoring a NEW skill or editing an existing one — writing a trigger-rich description, splitting a long body into references/, repairing evals/cases.yaml, or fixing a skill that never fires. Triggers: 'write a skill', 'escribe una skill', 'my skill never triggers', 'the description is too broad', 'audit this skill'. NOT building a product feature (that is `specify`) and NOT designing an agent loop (that is `building-agents`)."
+```
+
+## Quick test
+
+Before committing a description, ask:
+
+- Could the router tell from this line alone *when* to fire it? (situation present)
+- Are there phrasings a real user would type, in their language? (triggers present)
+- Does it say what it is **not**, naming the sibling? (boundary present)
+- Does it parse as YAML and fit 1024? (run the check)
+
+If any answer is no, it is not done.
+
+## Verify the YAML and length
+
+```bash
+python3 - "$PWD/skills/<id>/SKILL.md" <<'PY'
+import sys, yaml
+p = sys.argv[1]
+text = open(p).read()
+fm = text.split('---', 2)[1]
+meta = yaml.safe_load(fm)
+d = meta["description"]
+assert meta.get("origin") == "risco", "missing origin: risco"
+print("name:", meta["name"])
+print("description chars:", len(d))
+assert len(d) <= 1024, "description over 1024"
+print("OK — parses, origin present, <=1024")
+PY
+```