rsc-universal 0.1.1

package/skills/shortform-strategy/scripts/verify.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural linter for a produced shortform strategy doc.
+#
+# WHAT IT DOES (read-only; never edits, writes, or hits the network)
+#   Static checks over ONE strategy/decisions file you point it at
+#   (markdown — e.g. 02-DOCS/wiki/shortform/strategy.md):
+#     1. Required structure -> FAIL each missing:
+#        - a positioning / one-promise statement,
+#        - a cadence number (a per-week figure),
+#        - a completion / hook KPI mention,
+#        - a trend ride-or-skip rule,
+#        - at least one DATED decision record (a YYYY-MM-DD heading).
+#     2. WARN (heuristic, never fails without --strict):
+#        - cadence reads > 10/week (over the dilution ceiling),
+#        - the ledger logs only likes/views (no completion / sends / saves),
+#        - identical-creative cross-posting mentioned as a plan
+#          (Originality Score suppresses it).
+#   A clean OR empty/whitespace-only file exits 0 — never a false failure.
+#   --strict promotes warnings to a failure (for a CI gate).
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh 02-DOCS/wiki/shortform/strategy.md
+#   ./verify.sh strategy.md --strict
+#
+# EXIT CODES
+#   0  clean, warnings only (without --strict), or empty/no-content file
+#   1  a hard failure (missing required structure) — or any warning under --strict
+#   2  bad usage (no file given, or file does not exist)
+#
+# Targets stock macOS bash 3.2: no mapfile, no associative arrays, no bc.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+FILE=""
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    --strict) STRICT=1; shift ;;
+    -*) printf '%sunknown option: %s%s\n' "$RED" "$1" "$NC" >&2; usage; exit 2 ;;
+    *) if [ -z "$FILE" ]; then FILE="$1"; fi; shift ;;
+  esac
+done
+
+if [ -z "$FILE" ]; then
+  printf '%sno strategy file given%s\n' "$RED" "$NC" >&2; usage; exit 2
+fi
+if [ ! -f "$FILE" ]; then
+  printf '%sfile not found: %s%s\n' "$RED" "$FILE" "$NC" >&2; exit 2
+fi
+
+# Empty / whitespace-only file: nothing to check, do not false-fail.
+if [ ! -s "$FILE" ] || ! grep -q '[^[:space:]]' "$FILE" 2>/dev/null; then
+  ok "empty file — nothing to check"
+  exit 0
+fi
+
+printf 'shortform-strategy verify — %s\n\n' "$FILE"
+
+has() { grep -Eiq "$1" "$FILE" 2>/dev/null; }
+
+# --- 1. required structure (hard) ---------------------------------------------
+
+# Positioning / one-promise.
+if has 'position|one[- ]promise|niche|lane|for whom|who it is for'; then
+  ok "positioning / one-promise statement present"
+else
+  fail "no positioning / one-promise / lane statement found"
+fi
+
+# A cadence number: some "<n>/week" or "<n> per week" or "<n> posts a week".
+if has '[0-9]+ *(-|to|–) *[0-9]+ *(reels|posts)?/? *(per +week|/ *week|a +week|wk)'; then
+  ok "cadence number present"
+elif has '[0-9]+ *(reels|posts)? *(per +week|/ *week|a +week|/wk)'; then
+  ok "cadence number present"
+else
+  fail "no cadence number found (e.g. '4-7 Reels/week', '3-5 posts a week')"
+fi
+
+# Completion / hook KPI.
+if has 'completion|watch[- ]?time|first 3|3 ?sec|hook'; then
+  ok "completion / hook KPI present"
+else
+  fail "no completion / hook / watch-time KPI found"
+fi
+
+# Trend ride-or-skip rule.
+if has 'ride[- ]or[- ]skip|ride.*skip|skip.*trend|trend.*skip|whether to (jump|ride)|sound.*niche'; then
+  ok "trend ride-or-skip rule present"
+else
+  fail "no trend ride-or-skip rule found"
+fi
+
+# At least one dated decision record: a YYYY-MM-DD heading-ish line.
+DEC_N="$(grep -Ec '^#{1,6} *[0-9]{4}-[0-9]{2}-[0-9]{2}' "$FILE" 2>/dev/null || true)"
+DEC_N="${DEC_N:-0}"
+if [ "$DEC_N" -ge 1 ]; then
+  ok "dated decision record present (${DEC_N} found)"
+else
+  # Fall back: any dated line near a 'decision' word.
+  if grep -Eiq '[0-9]{4}-[0-9]{2}-[0-9]{2}' "$FILE" 2>/dev/null && has 'decision'; then
+    ok "dated decision record present (loose match)"
+  else
+    fail "no dated decision record (a '## YYYY-MM-DD — decision' block)"
+  fi
+fi
+
+# --- 2. heuristic warnings ----------------------------------------------------
+
+# Cadence over the ~10/week ceiling. Pull weekly figures and flag any > 10.
+CADENCE_HITS="$(grep -Eio '[0-9]+ *(reels|posts)? *(per +week|/ *week|a +week|/wk)' "$FILE" 2>/dev/null || true)"
+OVER=0
+if [ -n "$CADENCE_HITS" ]; then
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    n="$(printf '%s' "$line" | grep -Eo '[0-9]+' | head -1)"
+    [ -z "$n" ] && continue
+    if [ "$n" -gt 10 ]; then OVER=$((OVER + 1)); fi
+  done <<EOF
+$CADENCE_HITS
+EOF
+fi
+if [ "$OVER" -gt 0 ]; then
+  warn "cadence reads >10/week — past the dilution ceiling (consistency beats volume)"
+else
+  ok "no cadence over the ~10/week ceiling"
+fi
+
+# Ledger logs only vanity metrics.
+if has 'like|view'; then
+  if has 'completion|sends?|saves?'; then
+    ok "ledger logs completion / sends / saves (not only vanity)"
+  else
+    warn "likes/views mentioned but no completion / sends / saves — log the signals that move reach"
+  fi
+else
+  ok "no vanity-only metric set detected"
+fi
+
+# Identical-creative cross-posting as a plan.
+if has 'identical (creative|video)|same (creative|clip).*(both|all).*platform|repost.*same|cross[- ]?post.*identical'; then
+  warn "identical-creative cross-posting mentioned — Originality Score suppresses recycled content; re-cut natively"
+else
+  ok "no identical-creative cross-posting plan detected"
+fi
+
+# --- summary ------------------------------------------------------------------
+printf '\n'
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d hard failure(s), %d warning(s)%s\n' "$RED" "$fail_count" "$warn_count" "$NC"
+  exit 1
+fi
+if [ "$warn_count" -gt 0 ]; then
+  if [ "$STRICT" -eq 1 ]; then
+    printf '%s%d warning(s) — failing under --strict%s\n' "$YELLOW" "$warn_count" "$NC"
+    exit 1
+  fi
+  printf '%s%d warning(s), 0 hard failures%s\n' "$YELLOW" "$warn_count" "$NC"
+  exit 0
+fi
+printf '%sall checks passed%s\n' "$GREEN" "$NC"
+exit 0

package/skills/skill-scout/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: skill-scout
+description: "Use when about to do a task and a specialized skill probably exists but is not loaded, when a task feels harder than it should because generic reasoning is doing a domain skill's job, or when auditing a workspace's skill coverage for holes. Triggers: 'is there a skill for this?', 'what skill am I missing?', 'should I install a skill before doing this?', 'audit my .claude/skills against what this repo does', 'this feels like reinventing something we already have a skill for', 'qué skill me falta', 'quina skill em falta'. Names the absent skill and emits an install command, or routes to author-skill when none exists. NOT routing among skills you already have (that is suggest), and NOT writing the skill when none exists (that is author-skill)."
+tags: [skill-discovery, capability-gap, meta, recommendations, coverage-audit]
+recommends: [suggest, author-skill, context-budget, continuous-learning, knowledge-ops]
+origin: risco
+---
+
+# skill-scout — find the skill you don't have
+
+You are the **gap detector** for the skills catalog. Before a task starts — or in the middle of one that is dragging — you answer exactly one question: *is there a skill that should be handling this, and is it loaded?* You do **not** do the work. You name what to load, then get out of the way.
+
+Every run ends in one of three verdicts:
+
+- **INSTALLED-elsewhere** — the skill exists in the catalog and on disk somewhere (user scope, another project, a plugin) but is not active *here*. → emit a scope-fix / install command.
+- **MISSING** — the skill exists in the catalog but is not installed at all. → emit an install command and a one-line why.
+- **NONEXISTENT** — no catalog skill fits the task. → route to `../author-skill/SKILL.md`. Stop. Do not improvise a half-skill.
+
+Why this matters: skills load by **progressive disclosure**. At session start Claude reads only the YAML frontmatter (`name` + `description`, ~30–50 tokens each) and pulls the body in only when a task matches. A skill that is absent — or present with a description too vague to fire — is invisible to the router. That invisibility is the gap you exist to surface.
+
+## The decision (this is where the flow branches)
+
+| Task signal | Verdict | Action |
+| --- | --- | --- |
+| Clear catalog match, not in the active set | MISSING | Emit the install command + one-line why. Then continue the task with it loaded. |
+| Clear match, exists at user scope but not in this project (or vice versa) | INSTALLED-elsewhere | Emit the scope-fix (copy to the missing scope) + why. |
+| 2–3 plausible candidates, none dominant | AMBIGUOUS | Name the top 2 with a one-line distinction; ask which fits. Do not guess. |
+| Present skill already covers this task | NO GAP | Say so and hand to `../suggest/SKILL.md` (routing among present skills) — that is its job, not yours. |
+| Catalog match present but its description is too vague to ever fire | WEAK-DESCRIPTION | Treat as a gap; route to `../author-skill/SKILL.md` to fix the frontmatter. |
+| No catalog id fits at all | NONEXISTENT | Route to `../author-skill/SKILL.md`. Do not fabricate an id. |
+
+The branch you must never collapse: **MISSING vs NONEXISTENT.** Confusing them either sends the user to write a skill that already exists, or has them wait for an install command for a skill that was never authored.
+
+## Symptoms that the task should have a skill
+
+Watch for these. Any one is enough to run a scan:
+
+- **Reinventing a known workflow** — you are about to hand-derive steps for something the catalog names (auth flows, webhook verification, RAG retrieval, invoice generation).
+- **Generic prose where a domain skill exists** — your answer reads like a Wikipedia summary of a domain we have a dedicated skill for. The skill would carry it; you are carrying it raw.
+- **Repeated manual steps** — the user says "I do this lead-gen sequence by hand every week", "cada semana repito esto". A recurring pattern is a skill-shaped hole.
+- **The task literally names a catalog domain** — "Stripe webhook", "Postgres migration", "Next.js route handler". If the noun is a catalog id, check whether the skill is loaded before you type another line.
+- **A task feels harder than it should** — friction is a signal. Generic reasoning straining against a problem a specialist would walk through is the clearest tell.
+
+## Matching procedure
+
+Run in order. Precision here is the whole job.
+
+1. **Read the catalog ids and their descriptions**, not your memory of them. The `name` + `description` frontmatter is exactly what the router sees; match against the same surface.
+2. **Match on situation + symptom, not keyword.** A keyword hit is not a match. The description's `Use when …` clause and `NOT … (that is sibling)` boundary tell you whether the skill actually owns *this* situation.
+3. **Score the top 1–3 candidates.** If one clearly dominates, that is your recommendation. If two are close, surface both and ask.
+4. **NEVER invent an id outside the known catalog set.** Recommending a skill that does not exist is the single most damaging failure mode — it sends the user chasing a phantom. If nothing in the set fits, the verdict is NONEXISTENT, not "probably there's a `<made-up>` skill".
+
+```text
+# Bad — keyword match, wrong situation
+Task: "write the launch email for our new pricing tier"
+Scout: "→ install `email-deliverability`"   # 'email' keyword hit; that skill is about
+                                             # DNS/SPF/inboxing, not copy. Wrong owner.
+
+# Good — situation + symptom match
+Task: "write the launch email for our new pricing tier"
+Scout: "Situation = marketing copy for a launch. → MISSING: `newsletter` (or `landing-copy`
+        if it's a page, not an email). Install one; here's why."
+```
+
+## Scope check
+
+A gap is not always "never authored". It is often "present, but not *here*". Claude Code builds its available-skills list from **user scope** (`~/.claude/skills/`), **project scope** (`.claude/skills/`), plugin-provided skills, and built-ins.
+
+- Skill present at **user scope** but this project doesn't see the body firing → it should still be available; if it isn't, check the project hasn't shadowed it.
+- Skill committed to **another project's** `.claude/skills/` but absent here → INSTALLED-elsewhere; copy it into this project's scope (version-controlled with the repo) or install at user scope.
+- **Pick the scope by reuse breadth:** a general-purpose skill you'll want everywhere → **user scope**; a skill specific to one repo's conventions → **project scope**, committed with the code. Recommending project scope for a general skill is a smell (see anti-patterns).
+
+## Emit the recommendation
+
+State the verdict, the id, a one-line why, and a copy-paste install command. Three forms — pick by what the user has:
+
+```bash
+# 1) From a plugin marketplace (skill lives in a published repo)
+/plugin marketplace add <user>/<repo>
+/plugin install <name>@<marketplace>
+```
+
+```bash
+# 2) Interactive — browse and pick scope (User = all projects, Project = this repo)
+/plugin            # → Discover tab → install → choose User or Project scope
+```
+
+```bash
+# 3) Direct file drop (you have the SKILL.md already)
+mkdir -p .claude/skills/<id>
+cp -R <source>/<id>/* .claude/skills/<id>/   # project scope; ~/.claude/skills for user scope
+```
+
+One why-line per recommendation, never a paragraph:
+
+> MISSING: `webhooks` — you're about to hand-verify a signature; this skill carries replay-protection and the verify pattern. Install at **project** scope (repo-specific endpoint). `/plugin install webhooks@<marketplace>`
+
+The full menu — marketplace mechanics, the `/plugin` browser flow, user-vs-project semantics, the `curl | tar` pattern — is offloaded → `references/install-commands.md`. Keep this body a decision tool.
+
+## The weak-description trap
+
+A skill can be installed and still be a gap. If its description is vague — no `Use when …`, no concrete triggers, no boundary — the router never pulls it in. It is present but invisible.
+
+Why it bites: the body might be excellent, but progressive disclosure means the body is never read if the description doesn't fire. Treat a weak description as a coverage hole and route to `../author-skill/SKILL.md` to **fix the frontmatter**, not to rewrite the body. Do not "work around" an invisible skill by doing its job manually.
+
+## Optional artifact — record the gap as data
+
+When auditing coverage (not for one-off in-flight checks), append one line per gap to `skill-gaps.jsonl` so holes are auditable over time:
+
+```json
+{"task": "verify a Stripe webhook signature", "verdict": "MISSING", "recommended_id": "webhooks", "scope": "project", "reason": "hand-deriving replay protection", "date": "2026-06-02"}
+```
+
+One JSON object per line, append-only. `recommended_id` must be a real catalog id (omit it for NONEXISTENT). `scripts/verify.sh` validates exactly this: every line is well-formed JSON and every `recommended_id` is in the known catalog set — the check that catches a hallucinated id before it misleads anyone.
+
+## Anti-patterns / rationalizations → STOP
+
+| Rationalization | Reality / fix |
+| --- | --- |
+| "There's probably a `<plausible-name>` skill for this" | If it's not in the known catalog set, it does not exist. Verdict is NONEXISTENT → route to author-skill. A fabricated id is the worst failure you can ship. |
+| "I'll just do the task; finding the skill is overhead" | You are the procurement step, not the worker. Doing the work yourself defeats the point — name the skill and load it. |
+| "A skill is already loaded that covers this, but I'll recommend another anyway" | That's NO GAP. Hand to `../suggest/SKILL.md` (routing among present skills). Recommending over an existing skill is noise. |
+| "The word 'email' is in the task, so → email skill" | Keyword ≠ situation. Match on the `Use when …` clause and the symptom, not the noun. |
+| "Recommend it at project scope to be safe" | A general-purpose skill at project scope means re-installing it in every repo. Scope by reuse breadth: broad → user scope. |
+| "Five skills could touch this, list them all" | One task → at most the top 1–2. Over-recommending buries the one that matters and stalls the task. |
+| "The skill's there but never fires, so I'll just do it manually" | That's the weak-description trap. Route to author-skill to fix the description; don't paper over an invisible skill. |
+
+## Hand-offs
+
+- `../suggest/SKILL.md` — routing among the skills you already have. suggest is routing; you are procurement. If the right skill is already present, it's suggest's job, not yours.
+- `../author-skill/SKILL.md` — building a new skill when none exists. You own the *exists / missing / nonexistent* decision; the moment the verdict is NONEXISTENT (or WEAK-DESCRIPTION), hand off here.
+- `context-budget` — when the loaded set is too heavy for the window. That is token budgeting of what *is* loaded; orthogonal to finding what is *absent*. (Not yet on disk; do not link until it ships.)
+- `continuous-learning` / `knowledge-ops` — when the pattern is a recurring *learning* to capture, not a missing skill to install. (Not yet on disk.)

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

@@ -0,0 +1,12 @@
+# skill-scout evals — how to run
+
+`cases.yaml` is read by the catalog eval runner. The `should_trigger` / `should_not_trigger` sets
+check the description's routing precision: each `should_trigger` prompt should pull this skill in,
+and each `should_not_trigger` prompt should route to its named sibling instead (the sharp edges are
+against `suggest` — routing among skills you already have — and `author-skill` — writing the skill
+that doesn't exist; the rest guard `context-budget`, `continuous-learning`, and `knowledge-ops`).
+The `capability` case is a manual/LLM-graded rubric: run the scenario with the skill loaded and
+confirm every `must_include` line is satisfied — especially that it never fabricates a catalog id
+and never does the implementation itself. No network or credentials needed; everything is local and
+static. To sanity-check the optional artifact path, run `scripts/verify.sh` against a directory
+containing a `skill-gaps.jsonl` (it is a clean no-op on an empty or absent file).

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

@@ -0,0 +1,56 @@
+skill: skill-scout
+
+# skill-scout is the catalog gap detector: it finds the skill you DON'T have and
+# emits an install command, or routes to author-skill when none exists. These
+# cases pin the boundary against suggest (routing among present skills) and
+# author-skill (writing the skill that's missing).
+
+should_trigger:
+  - prompt: "I'm about to hand-write a Stripe webhook signature verifier — is there already a skill for this?"
+    why: "Clear catalog match (webhooks / stripe) not loaded; the task names a catalog domain and the user is asking whether to procure before reinventing it."
+
+  - prompt: "qué skill me falta para hacer este endpoint de FastAPI"
+    why: "Spanish gap framing on a task that names a catalog domain (fastapi). Tests the non-English trigger and the situation+symptom match."
+
+  - prompt: "This feels like I'm reinventing something we already have a skill for."
+    why: "Non-obvious trigger — no skill is named and no keyword domain appears; the symptom (reinventing a known workflow) alone should fire the scan."
+
+  - prompt: "Audit our .claude/skills against what this repo actually does and tell me the coverage holes."
+    why: "Coverage-audit framing — the core auditing use, distinct from any single in-flight task. Should produce verdicts (MISSING / INSTALLED-elsewhere / NONEXISTENT) per hole."
+
+  - prompt: "I keep running this lead-gen outreach sequence by hand every week — should I be loading something for this?"
+    why: "Repeated manual pattern that maps to a catalog domain (lead-gen / cold-outreach). The recurring-steps symptom is a skill-shaped hole, not a one-off."
+
+  - prompt: "This Postgres migration task feels way harder than it should — am I missing a skill?"
+    why: "Friction-as-signal — a task straining under generic reasoning where a specialist (db-migrations / postgresdb) would carry it. Non-obvious phrasing of the gap."
+
+should_not_trigger:
+  - prompt: "Which of my loaded skills should I use for this PR review?"
+    route_to: suggest
+    why: "Routing among skills already present — suggest's job. skill-scout is about what is absent, not picking from what's loaded."
+
+  - prompt: "No catalog skill fits our internal billing-export format — write one."
+    route_to: author-skill
+    why: "The skill genuinely does not exist and the user wants it created. skill-scout stops at the NONEXISTENT verdict; creation is author-skill."
+
+  - prompt: "My context window is full mid-task — what should I unload?"
+    route_to: context-budget
+    why: "Token budgeting of what IS loaded — orthogonal to finding what's missing. context-budget owns the loaded-set optimization."
+
+  - prompt: "Save this debugging lesson so we remember the fix next time."
+    route_to: continuous-learning
+    why: "Capturing a recurring learning into the knowledge base, not detecting a missing skill. continuous-learning owns capture."
+
+  - prompt: "Consolidate our scattered runbooks into one searchable knowledge base."
+    route_to: knowledge-ops
+    why: "Organizing existing knowledge artifacts, not procuring an absent skill. knowledge-ops owns the wiki/runbook consolidation."
+
+capability:
+  - scenario: "Mid-task, the user is about to manually wire OAuth login plus a Postgres user table from scratch, with no domain skill loaded. Show how skill-scout behaves before any code is written."
+    must_include:
+      - "Identifies the gap as real (a specialist would carry this), not generic friction to push through"
+      - "Names candidate skills only from the known catalog set (e.g. an OAuth/auth-capable skill and postgresdb / db-migrations) — never a fabricated id"
+      - "Gives a copy-paste install command and an explicit scope choice (user vs project) with a one-line reason"
+      - "One concise why-line per recommendation, not a paragraph"
+      - "If no catalog skill fits a part of the task, returns NONEXISTENT and routes to author-skill rather than inventing an id"
+      - "Does NOT implement the OAuth or Postgres wiring itself — it procures, it does not do the work"

package/skills/skill-scout/references/install-commands.md

@@ -0,0 +1,76 @@
+# Install commands & scope mechanics
+
+The full menu skill-scout emits once it has a verdict. The SKILL.md body keeps only the three
+common forms; the rest lives here so the body stays a decision tool.
+
+## Where Claude Code looks for skills
+
+The available-skills list is built by scanning, in order:
+
+- **User scope** — `~/.claude/skills/<id>/SKILL.md`. Available in *every* project on this machine.
+- **Project scope** — `.claude/skills/<id>/SKILL.md`. Version-controlled with the repo; available
+  only inside it. A project-scope skill of the same id shadows a user-scope one.
+- **Plugin-provided** — skills bundled in an installed plugin/marketplace.
+- **Built-ins** — shipped with the harness.
+
+"Present but not here" is therefore a real gap: a skill at user scope is invisible inside a repo
+that doesn't pick it up, and a skill committed to one repo's `.claude/skills/` does not follow you
+to another.
+
+## Choosing scope (the only decision that matters here)
+
+| Choose **User** (`~/.claude/skills/`) when… | Choose **Project** (`.claude/skills/`) when… |
+| --- | --- |
+| The skill is general-purpose — you'll want it across repos | The skill encodes this repo's conventions / endpoints |
+| It is your personal tooling, not the team's | It should travel with the code for everyone who clones |
+| You don't want it in version control | You want it reviewed and versioned in the repo |
+
+Default heuristic: **broad reuse → user; repo-specific → project, committed.**
+
+## Form 1 — plugin marketplace
+
+When the skill is published in a marketplace repo:
+
+```bash
+/plugin marketplace add <user>/<repo>     # register the marketplace once
+/plugin install <name>@<marketplace>      # install the named skill from it
+```
+
+## Form 2 — interactive browser
+
+When you'd rather browse and pick scope by hand:
+
+```bash
+/plugin            # opens the plugin UI
+                   # → Discover tab → find the skill → Install
+                   # → choose User (all projects) or Project (this repo) scope
+```
+
+## Form 3 — direct file drop
+
+When you already hold the `SKILL.md` (e.g. copying from another project or a tarball):
+
+```bash
+# project scope (committed with the repo)
+mkdir -p .claude/skills/<id>
+cp -R <source>/<id>/* .claude/skills/<id>/
+
+# user scope (all projects)
+mkdir -p ~/.claude/skills/<id>
+cp -R <source>/<id>/* ~/.claude/skills/<id>/
+```
+
+## Form 4 — curl | tar (remote tarball)
+
+When the skill ships as a downloadable archive rather than a marketplace entry:
+
+```bash
+mkdir -p .claude/skills/<id>
+curl -fsSL <url>/<id>.tar.gz | tar -xz -C .claude/skills/<id> --strip-components=1
+```
+
+## After installing
+
+The new skill is picked up on the next session/scan. Confirm the description is trigger-rich enough
+to actually fire — a freshly installed skill with a weak description is still an invisible gap.
+If the description is vague, that is an author-skill job, not a re-install.

package/skills/skill-scout/scripts/verify.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+#
+# verify.sh — validator for skill-scout's optional artifact: skill-gaps.jsonl.
+#
+# WHAT IT DOES (read-only; never edits or writes a file)
+#   Static, network-free checks over a skill-gaps.jsonl produced by skill-scout.
+#   You may point it at the file directly or at a directory containing it:
+#     1. Every non-blank line is well-formed JSON                  -> FAIL each bad line.
+#     2. Every "recommended_id" present is a member of the known   -> FAIL each unknown id.
+#        catalog id set (the skill's worst failure mode is
+#        hallucinating an id that does not exist).
+#
+#   skill-scout can run in advice-only mode and emit no artifact at all. So an
+#   absent file, an empty file, or a whitespace-only file is a clean PASS — the
+#   verifier never invents a failure where there is nothing to check.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                              # checks ./skill-gaps.jsonl if it exists
+#   ./verify.sh path/to/skill-gaps.jsonl     # check a specific file
+#   ./verify.sh path/to/dir                  # check <dir>/skill-gaps.jsonl
+#
+# EXIT CODES
+#   0  clean, or nothing to check (absent / empty file)
+#   1  a malformed JSON line, or a recommended_id not in the known catalog set
+#   2  bad usage (target path given but does not exist)
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays. Uses python3
+# for JSON parsing when available, with a conservative grep/sed fallback.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; NC=''
+fi
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$NC" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED"   "$NC" "$*"; }
+
+# --- known catalog id set (keep in sync with the catalog manifest) ------------
+KNOWN_IDS="analyze author-skill building-agents clarify constitution course-storytelling debug deployment design fastapi flutter go harness implement init marketing nextjs parallel plan postgresdb presentations review sdd secure-coding ship specify suggest tasks verify worktrees finance-ops invoicing bookkeeping pricing sales-pipeline lead-gen cold-outreach proposals contracts customer-support client-onboarding retention hiring people-ops inventory logistics-ops procurement meeting-notes sop-builder project-ops 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 pitch-deck investor-materials financial-model fundraising unit-economics grants gdpr-privacy terms-conditions compliance data-policy ip-trademark 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 analytics dashboard kpi-framework reporting ab-testing forecasting data-cleaning business-intelligence rag embeddings-search prompt-engineering llm-pipeline agent-eval chatbot ai-media replicate-images structured-extraction agent-safety cost-tracking react react-native vue-nuxt nodejs django laravel rails swift-ios kotlin-android rust api-design wordpress shopify no-code-app chrome-extension mysql redis prisma-orm db-migrations backups clickhouse-analytics code-review security-scan testing-py testing-web testing-go e2e-testing accessibility performance error-handling observability docker github-actions git-workflow domains-dns monitoring email-deliverability scaling knowledge-ops codebase-onboarding research-ops decision-records continuous-learning skill-scout context-budget course-builder technical-writing translation-l10n 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 typescript python java csharp-dotnet php ruby cpp elixir bash-scripting sql angular svelte astro solid-js htmx nestjs spring-boot phoenix tauri electron expo compose-multiplatform mongodb supabase neon planetscale sqlite-turso drizzle-orm firebase dynamodb vector-db duckdb vercel netlify cloudflare railway render fly-io coolify hetzner digitalocean aws-essentials gcp-essentials replicate runpod modal huggingface ollama together-fireworks fal"
+
+is_known() {
+  # whole-word membership test against the space-delimited set
+  case " $KNOWN_IDS " in
+    *" $1 "*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# --- resolve the target -------------------------------------------------------
+TARGET="${1:-skill-gaps.jsonl}"
+
+if [ -d "$TARGET" ]; then
+  FILE="$TARGET/skill-gaps.jsonl"
+else
+  FILE="$TARGET"
+fi
+
+# Absent artifact: advice-only mode, nothing to check.
+if [ ! -e "$FILE" ]; then
+  # If the user explicitly named a path that doesn't exist (and isn't the
+  # default), that's a usage error; otherwise it's a clean no-op.
+  if [ "${1:-}" != "" ] && [ ! -d "${1:-}" ]; then
+    ok "no skill-gaps.jsonl at '$FILE' — advice-only mode, nothing to check"
+    exit 0
+  fi
+  ok "no skill-gaps.jsonl found — advice-only mode, nothing to check"
+  exit 0
+fi
+
+# Empty / whitespace-only: nothing to check.
+if [ ! -s "$FILE" ] || ! grep -q '[^[:space:]]' "$FILE" 2>/dev/null; then
+  ok "empty skill-gaps.jsonl — nothing to check"
+  exit 0
+fi
+
+printf 'skill-scout verify — %s\n\n' "$FILE"
+
+HAVE_PY=0
+if command -v python3 >/dev/null 2>&1; then HAVE_PY=1; fi
+
+fail_count=0
+checked=0
+lineno=0
+
+while IFS= read -r line || [ -n "$line" ]; do
+  lineno=$((lineno + 1))
+  # skip blank lines
+  case "$line" in
+    ''|*[!\ ]*) : ;;
+  esac
+  if ! printf '%s' "$line" | grep -q '[^[:space:]]'; then
+    continue
+  fi
+  checked=$((checked + 1))
+
+  if [ "$HAVE_PY" -eq 1 ]; then
+    # Parse JSON and print the recommended_id (or empty) on success; fail loudly.
+    rid="$(printf '%s' "$line" | python3 -c '
+import sys, json
+try:
+    obj = json.loads(sys.stdin.read())
+except Exception as e:
+    sys.stderr.write("BADJSON")
+    sys.exit(3)
+if not isinstance(obj, dict):
+    sys.stderr.write("NOTOBJ")
+    sys.exit(3)
+rid = obj.get("recommended_id", "")
+sys.stdout.write(rid if isinstance(rid, str) else "")
+' 2>/tmp/skill_scout_err.$$ )" || {
+      reason="$(cat /tmp/skill_scout_err.$$ 2>/dev/null || true)"
+      rm -f /tmp/skill_scout_err.$$
+      if [ "$reason" = "NOTOBJ" ]; then
+        fail "line $lineno: JSON is not an object"
+      else
+        fail "line $lineno: malformed JSON"
+      fi
+      fail_count=$((fail_count + 1))
+      continue
+    }
+    rm -f /tmp/skill_scout_err.$$
+  else
+    # Fallback without python3: shallow well-formedness + id extraction.
+    # Must look like a single JSON object.
+    case "$line" in
+      \{*\}) : ;;
+      *) fail "line $lineno: does not look like a JSON object (no python3 to verify deeply)"
+         fail_count=$((fail_count + 1)); continue ;;
+    esac
+    rid="$(printf '%s' "$line" \
+      | sed -n 's/.*"recommended_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')"
+  fi
+
+  if [ -n "$rid" ]; then
+    if is_known "$rid"; then
+      ok "line $lineno: recommended_id '$rid' is a known catalog id"
+    else
+      fail "line $lineno: recommended_id '$rid' is NOT in the known catalog set (hallucinated id?)"
+      fail_count=$((fail_count + 1))
+    fi
+  else
+    ok "line $lineno: valid JSON (no recommended_id — e.g. a NONEXISTENT verdict)"
+  fi
+done < "$FILE"
+
+printf '\n'
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d problem(s) across %d line(s)%s\n' "$RED" "$fail_count" "$checked" "$NC"
+  exit 1
+fi
+printf '%sall %d line(s) valid%s\n' "$GREEN" "$checked" "$NC"
+exit 0