@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/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/shared/author-skill/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: author-skill
+description: "Use when authoring a NEW ai-hub skill or editing an existing one — scoping it to one job, writing the description that decides whether it ever loads, splitting the body into references/, writing its evals, auditing it against the rubric. NOT building a product feature (that is `specify`) and NOT designing an agent loop (that is `building-agents`)."
+tags: [skill, authoring, meta]
+recommends: []
+origin: ai-hub
+---
+
+# author-skill — write skills that trigger and teach
+
+This is the **meta skill**: it authors and edits the other skills in the ai-hub 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. Treat them as two separate engineering problems with two separate quality bars.
+
+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.
+
+**Not this skill — delegate:** a product feature specced or planned → `../specify/SKILL.md`, `../plan/SKILL.md`. An autonomous agent or tool-calling loop → `../building-agents/SKILL.md`. Generic project docs or a wiki article → the `../harness/SKILL.md` 02-DOCS engine. Bootstrapping a workspace or profiling the user → `../init/SKILL.md`.
+
+Read `02-DOCS/wiki/harness/user-profile.md` and speak in the register its `technical_level` records (technical terms, or plain words with analogies); `../init/SKILL.md` sets it, and `orient` owns the voice. With no profile, use analogies and ask once "technical or with analogies?" — skill authoring is itself a technical act, so a non-technical author needs each convention explained, not just named.
+
+## 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.
+
+## The description — the single highest-leverage line
+
+The description sits in context on **every turn the skill is installed**, invoked or not. The body is only paid for when the skill fires; the description is paid for always. So length here is a cost, never a credit. A vague description is a skill that never fires; an over-broad one 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. **Discriminative, not exhaustive.** Lead with a `Use when …` clause naming the *situation*, then only the capabilities that separate this skill from its neighbours. Do **not** append a `Triggers: '…', '…'` phrase list: the model matches on meaning, so a keyword bank in three languages buys nothing and is charged on every turn. The test is *discrimination, not coverage* — could a reader pick this skill over its nearest sibling from this line alone?
+3. **Draw the boundary.** End with a `NOT <x> (that is <sibling>)` clause, naming a sibling that actually exists under `skills/`. Negative space prevents hijacking as much as positive matching causes firing.
+4. **Aim ≤ 350 characters; 1024 is the schema-enforced hard limit.** One physical line, wrapped in double quotes, internal quotes escaped or avoided. If it does not parse, the skill does not load.
+5. **`origin: ai-hub`** on its own line. This marks it as ours.
+
+```yaml
+# Good — situation, the few capabilities that discriminate, a real boundary
+description: "Use when X happens or the user shows symptom Y — doing A, fixing B, choosing C. NOT Z (that is `sibling`)."
+
+# Bad — first person, no situation, no boundary; competes with every sibling on every turn
+description: "I help you write great skills and make them work."
+```
+
+The full recipe, the 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. Write **the smallest body that still routes correctly**: 400 lines is a ceiling, not a target, and there is no floor — a skill that does its job in 60 lines beats the same skill padded to 200. Push anything long, reference-like, or rarely-needed into `references/<topic>.md` and link it inline at the point of use ("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 |
+
+Every file under `references/` must be linked from the body. An unlinked reference is never loaded, so it is dead weight in the package — link it or delete it.
+
+## 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 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)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **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 rules 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 ai-hub voice (see below). Tag every code/example fence with a language. Add a 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, and link each one inline.
+6. **Write the evals** — `cases.yaml` then `README.md`. → `references/eval-authoring.md`.
+7. **Wire it into the ai-hub plumbing** (`tags`, `recommends`, `npm run manifest`, and indexing any artifact in `02-DOCS/wiki/index.md` — the Knowledge map; root `CLAUDE.md` keeps only a short pointer). → `references/skill-conventions.md`.
+8. **Self-audit against the rubric** (below). Fix every miss or justify it.
+
+## The ai-hub 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").
+- A rule gets stated where it applies, with a one-line *why* that makes it obviously absolute — not a lecture, and not a shouted NON-NEGOTIABLE.
+- Concrete over abstract: a number, a path, a Bad→Good pair beats an adjective.
+- Original prose. Mine ideas from anywhere; the words are the author's (Daner Alejandro Salazar Colorado). 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 ai-hub identity is its own.
+- Cross-reference siblings by name or `../<sibling>/SKILL.md`, only ones that actually exist.
+
+## Match the form to the failure
+
+Before you write an instruction, name the **failure** it's meant to prevent — then pick the form
+that actually fixes *that* failure. The instinct is to write a prohibition ("don't do X") for
+everything. That instinct is wrong for most failures, and measurably counter-productive for one
+class: **a prohibition aimed at output shape tends to summon the very thing it forbids** (the model
+attends to the named token), and can do *worse* than saying nothing at all. Match deliberately:
+
+| The failure is… | Use this form | Why, and example |
+| --- | --- | --- |
+| **Discipline** — the agent knows the rule but skips it under pressure (time, sunk cost, "just this once") | **The rule stated at the step it governs, with its why** — plus one row in the anti-patterns table | A rule in an appendix is skimmed; a rule in context is followed. "Do not ship a failing test — a red test merged is a lie in the suite", written at the ship step. Do not build a separate rationalization bank restating rules already in the flow; it is paid for on every load and read as decoration. |
+| **Wrong-shaped output** — tone, verbosity, format, structure come out wrong | **Positive recipe / contract** (show the target shape) | A prohibition ("don't be verbose", "no marketing fluff") makes it *more* likely — the model fixates on the banned shape. Give the shape to hit instead: "Reply in ≤3 sentences, lead with the verdict." Demonstrate, don't forbid. |
+| **Omitted element** — the agent forgets a required piece | **Required structural slot** (a checklist item or a template field it must fill) | You can't prohibit an absence. Make the slot mandatory so its emptiness is visible — a `Done-of-done` checkbox, a template section, a result-envelope field. |
+| **Conditional behavior** — right action depends on the situation | **Predicate-keyed conditional** ("When X → do Y; otherwise Z") | A flat rule fires in the wrong context. Key the behavior to its trigger so the agent branches correctly instead of over- or under-applying. |
+
+So: an anti-patterns table earns its place when it names concrete **failure modes** the flow above
+does not already state. A table that re-lists rules from the body is pure cost — delete it and move
+each rule to its step. And when you catch yourself writing "don't make it X" about the *shape* of an
+output, rewrite it as the shape to hit.
+
+## 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: ai-hub` present.
+- [ ] **Description** third-person, `Use when…` lead, an explicit `NOT … (that is sibling)` boundary naming a real sibling, ≤ 350 chars target / ≤ 1024 hard limit — judged on discrimination against the nearest sibling, not coverage.
+- [ ] **One job.** The body never drifts into a second skill's territory; it delegates instead.
+- [ ] **Body ≤ 400 lines** — a ceiling, not a target, with no floor. Long/branch-specific material lives in `references/`.
+- [ ] **Every `references/` file linked** inline from the body; none orphaned.
+- [ ] **Every fence language-tagged**; no placeholder/TODO prose; examples concrete.
+- [ ] **Checklist/decision table only where a flow branches**; an **anti-patterns table** present, naming failure modes rather than restating rules.
+- [ ] **Orient voice honored** — reads `technical_level` from the profile and picks the register; short sentences, every answer understandable on its own.
+- [ ] **Artifacts under `02-DOCS/wiki/`** and indexed in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer), 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.
+- [ ] **Every `must_include` item discriminates** — answerable by the scenario's task, plausibly caused by the skill and plausibly missed without it. An item *both* arms fail measures nothing and lowers the absolute; it has turned a real PASS into a FAIL here. → `references/eval-authoring.md`.
+- [ ] **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 ai-hub plumbing steps → `references/skill-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
+
+| Failure mode | Reality / fix |
+| --- | --- |
+| Description written last, once the body is done | The description is *why the body ever runs*, and drafting it first forces the scope clear. Write it first, to bar. |
+| Description padded for coverage — more phrasings, more languages, more verbs | It is in context on every turn, invoked or not. Prune until it discriminates against the nearest sibling and stops. |
+| One skill covering specify + plan + implement | Multi-job skills trigger fuzzily and teach poorly. One skill, one job — split it. |
+| Body grown past ~400 lines "because the topic is rich" | The agent skims what it cannot hold. Extract a reference and link it inline. |
+| A `references/` folder added to look thorough, or a reference nothing links to | An unlinked reference is never loaded — dead weight in the package. Link it at point of use or delete it. |
+| Evals skipped: "I'll just test it by hand once" | Unverifiable = does not ship. Write `cases.yaml`, near-misses with `route_to` included. |
+| `verify.sh` added to a process skill for rigor | A process skill has no artifact to grep. Its rigor is the capability eval. |
+| `../foo/SKILL.md` linked to something not in this repo | A dead link is a defect. Verify the directory exists under `skills/`. |
+| Another catalog mirrored wholesale ("it's basically superpowers' writing-skills") | Mine the idea, write it in the ai-hub voice. Copied artifacts or phrasing are a defect. |
+
+## 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 index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer), 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.

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

@@ -0,0 +1,66 @@
+# Eval harness — `author-skill`
+
+Evaluates the `author-skill` meta skill (the ai-hub 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 ai-hub 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, only the capabilities that
+  discriminate it from its nearest sibling, a `NOT … (sibling)` boundary, valid single-line quoted
+  YAML aiming ≤ 350 chars (1024 hard limit), `origin: ai-hub`.
+- **Progressive disclosure** — the smallest body that still routes (400 lines is a ceiling, not a
+  target) pointing 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.
+- **ai-hub wiring** named: `tags` + `recommends` frontmatter, `npm run manifest` regenerated,
+  `npm run validate` / `manifest:check` passing, `eval-lint.sh` passing.
+- **Original ai-hub 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/shared/author-skill/evals/cases.yaml

@@ -0,0 +1,75 @@
+skill: author-skill
+
+# Cases for the ai-hub "author-skill" meta skill.
+# author-skill authors or edits a SKILL.md to the skill catalog bar: a discriminating
+# third-person description (~350 chars, valid YAML, origin: ai-hub), a focused body with
+# progressive disclosure into references/, the best-practice rubric, and an
+# evals/cases.yaml + README for the NEW skill, plus the manifest.yaml integration (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 400-line ceiling 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 manifest.yaml integration (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 skills of ai-hub 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 docs/."
+    route_to: "harness"
+    why: "Generic docs/wiki consolidation is the harness 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 catalog bar."
+    must_include:
+      - "Reads the register from AGENTS.md (or asks once 'technical or with analogies?' if absent) and explains in that register, without any verbosity level"
+      - "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, only the capabilities that discriminate it from its nearest sibling, a 'NOT … (that is `sibling`)' boundary, valid single-line quoted YAML aiming <=350 chars (1024 hard limit), with origin: ai-hub"
+      - "Produces the smallest body that still routes (400 lines is a ceiling, not a target) 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 manifest.yaml wiring: set tags + recommends in frontmatter, run npm run manifest:build to regenerate core/manifest.json, and confirm npm run manifest:check passes"
+      - "Keeps the prose original in the voice of ai-hub — 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 situation clause causes misses"
+      - "Rewrites to third-person with a 'Use when…' situation lead and concrete verb phrases"
+      - "Keeps only the capabilities that discriminate deployment work from its nearest siblings, rather than padding a keyword list for coverage"
+      - "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, aims <=350 chars against the 1024 hard limit, and keeps origin: ai-hub"
+      - "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/shared/author-skill/references/description-recipe.md

@@ -0,0 +1,85 @@
+# The description recipe
+
+The description is the only line the router reads on every turn to decide whether to load the skill — and it sits in context on every turn the skill is installed, invoked or not. It is a *retrieval problem*, not a marketing problem. Write it to be matched, not admired, and keep it short: length here is a cost, never a credit.
+
+## The shape
+
+```text
+"Use when <SITUATION / SYMPTOM> — <verb phrase>, <verb phrase>, <verb phrase>.
+ NOT <out-of-scope thing> (that is `sibling`) [and NOT <other> (that is `sibling`)]."
+```
+
+Three 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 model matches situations better than nouns. "Use when a skill mis-triggers" beats "skill quality tool".
+2. **Name only the discriminating capabilities.** Right after the lead, name the few things the skill does that its neighbours do not, as verbs ("writing a description", "splitting the body", "repairing cases.yaml"). Stop there. Do **not** append a `Triggers: '…', '…'` phrase list: the model matches on meaning, so a keyword bank — especially one repeated in three languages — buys no routing accuracy and is charged on every turn.
+3. **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, and verify it exists under `skills/`.
+
+## The test: discrimination, not coverage
+
+Do not ask "does this cover every way someone might phrase it?" — ask **"could a reader pick this skill over its nearest sibling from this line alone?"** Coverage is what tempts you to pad; discrimination is what actually routes. If two versions route the same, the shorter one is better.
+
+## The hard constraints
+
+- **Aim ≤ 350 characters; 1024 is the schema-enforced hard limit.** Over budget = trim verb phrases 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".
+- **State when it fires and where the boundary is — never the workflow.** The description says *when* to fire and *what it is not*. It must **not** summarize the procedure the body owns (the steps, the phase count, "does X then Y then Z"). This is not a style nit — it changes behavior. A description that pre-summarizes the steps becomes a *substitute* for reading the body: the agent acts on the summary and skips the real instructions. (Observed in the wild: a skill whose description said it runs *two* reviews made the agent run only *one*, because the summary was treated as the spec; deleting the workflow summary made the agent read the body and do both.) The verb phrases in move #2 name *capabilities* ("repairing cases.yaml"), not an ordered recipe ("first lint, then split, then validate"). If your description tells the reader how the skill works step by step, cut it back to situation + boundary.
+
+## Budget tactics when you are over
+
+In priority order, cut:
+
+1. Verb phrases that name a capability the nearest sibling shares — they add no discrimination.
+2. Verb phrases already implied by the `Use when` lead.
+3. Any "Knows…" / "Understands…" clause.
+4. Shorten the boundary to one `NOT` clause naming the single most-confused sibling.
+
+Never cut: the `Use when` lead, or the last `NOT` boundary.
+
+## Worked before → after
+
+**Before** (first person, no situation, 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`; nothing that says *when* this fires; no boundary, so it competes with `building-agents`, `specify`, and `init` on every "make a thing" turn.
+
+**After** (third person, situation + discriminating verbs + boundary, valid YAML, ~300 chars):
+
+```yaml
+description: "Use when authoring a NEW skill or editing an existing one — writing the description that decides whether it loads, splitting a long body into references/, repairing evals/cases.yaml, or fixing a skill that never fires. 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 reader tell from this line alone *when* to fire it? (situation present)
+- Could the reader pick it over its nearest sibling from this line alone? (discriminates)
+- Does it say what it is **not**, naming a sibling that exists? (boundary present)
+- Is anything in it there for coverage rather than discrimination? (cut it)
+- Does it describe *when/what-not*, and **never** the step-by-step procedure? (no workflow summary — if a reader could skip the body and act on the description alone, it leaks the workflow)
+- 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") == "ai-hub", "missing origin: ai-hub"
+print("name:", meta["name"])
+print("description chars:", len(d))
+assert len(d) <= 1024, "description over 1024"
+print("OK — parses, origin present, <=1024")
+PY
+```