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

package/skills/shared/skill-scout/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: skill-scout
+description: "Use when 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, when the work just delivered was a repeatable procedure worth turning into a skill or an agent, or when auditing coverage for holes. Resolves against what already exists — installed skills, catalog skills and agent files — then names the gap and emits the install command. NOT routing among skills you already have (that is `suggest`), NOT writing the artifact when none exists (that is `author-skill` for skills, `building-agents` for agents)."
+tags: [skill-discovery, capability-gap, meta, recommendations, coverage-audit]
+recommends: [suggest, author-skill, context-budget, continuous-learning, knowledge-ops]
+origin: ai-hub
+---
+
+# skill-scout — find the skill you don't have
+
+You are the **gap detector** for the skills catalog. Before a task starts, in the middle of one that is dragging, or right after delivering work that turned out to be a procedure — 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 the verdicts in the table below:
+
+- **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. |
+| An installed **agent** already does this work | AGENT-COVERS | Name it, use it (delegate), propose nothing. Agents are listed by `npx ai-hub capabilities`; they are invisible to the catalog, so a scan that skips them proposes duplicates. |
+| 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.
+
+## The automation gap — the trigger that fires *after* the work
+
+Everything above is preventive: you scan *before* generic reasoning does a specialist's job. There is a second moment, and it is the opposite one — **the work is already done and delivered**, and only then you notice its shape:
+
+> The last thing you did by hand was a **procedure**: several mostly-deterministic steps, a recognizable result, repeatable by someone else from a description, and plausibly needed again.
+
+Then, in this order and never skipping ahead:
+
+1. **Deliver first.** This never delays, conditions or replaces the work asked for. Raising it beforehand turns a simple request into a conversation about harness architecture.
+2. **Enumerate what exists** — `npx ai-hub capabilities` lists installed skills (with their scope), **agent files** and the catalog ids in one pass. Read it; do not recall it. Add `--full` for catalog descriptions, or use `catalog --available` when you need to match by meaning — the default stays cheap on purpose. If the command cannot run, **propose nothing** and say the check did not happen: never propose building on a check that did not occur.
+3. **Something covers it** → use it (install with the usual one-word confirm if it is catalog-only), and **propose nothing**. Proposing to build what already exists is the worst outcome available here — it costs attention and it spends the credibility of every later suggestion.
+4. **Nothing covers it** → one sentence at the end of the work: the procedure you saw, and whether it fits as a skill or an agent. Then stop; the user decides. Their "no" ends it for this procedure for the rest of the session.
+5. **Record it either way** — `npx ai-hub capabilities gap-log --procedure "<what YOU observed doing>" --verdict <covered-installed|covered-catalog|covered-agent|proposed-accepted|proposed-declined>`.
+
+**One sentence, always.** In the `orient` voice: one line ("this looked like a procedure — worth a skill?") plus why it qualified. Explain the skill-vs-agent difference only if the user asks; for a `non-technical` reader (`technical_level` in `02-DOCS/wiki/harness/user-profile.md`), use an analogy. Brevity never removes the observation.
+
+**The privacy boundary is yours to hold**, not the command's — it validates shape and nothing else, and it cannot tell your description from a paraphrase of the request. `--procedure` carries *your* account of the work you did. Never the user's words. The test: if the line could be reconstructed from what they typed, it does not belong in the log.
+
+**Which log:** this one (`.ai-hub/automation-gaps.md`, verdicts `covered-*`/`proposed-*`) is for the after-the-work automation gap. The coverage-audit log below (`skill-gaps.jsonl`, verdicts `MISSING`/`NONEXISTENT`) is for a deliberate catalog audit. One event, one log — never both.
+
+**Silence is a correct and common outcome.** A one-off, an exploration, a one-liner, or work that failed is not a procedure — a procedure is extracted from something that worked. There is no switch to turn this off, which is exactly why the bar is high: propose on everything and the feature becomes noise a user cannot escape.
+
+### Skill or agent
+
+Decided by the nature of the work, never its size:
+
+| | Fits a **skill** | Fits an **agent** |
+| --- | --- | --- |
+| Shape | Knowledge + procedure that must **fire at the right moment**, in the conversation, user present | Work you want to **delegate**: its own context, possibly in parallel, possibly another model |
+| Tell | "Whenever X comes up, do it this way" | "Go do X and come back with the result" |
+| Build with | `../author-skill/SKILL.md` | `../building-agents/SKILL.md` |
+
+When both fit, name the cheaper one to try and say the other is possible. When it is genuinely ambiguous, ask instead of choosing. On a target with no file-based agents (`capabilities` says so), the agent option does not exist — do not offer it.
+
+## 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.
+- `../building-agents/SKILL.md` — designing the agent when the gap is delegated work rather than in-conversation procedure (see *Skill or agent* above).
+- `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/shared/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/shared/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/shared/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/shared/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