skill-scout

skill-scout

The safety layer for growing your Claude Code setup. Every directory online ranks popularity; none tells you if an extension will read your .env or rug-pull after you trust it. skill-scout adds the missing signal: it finds the good ones and vets them.

SKILL_DIR below = the folder this file lives in. Run the CLI as python3 SKILL_DIR/scripts/scout.py ... (no cd needed). Requires Python 3.9+ and git; the gh CLI is optional but removes GitHub rate limits.

Golden rules (never break)

1. Never promise "safe". This is static analysis + reputation. Always give the caveat

(references/verdict-template.md) and separate "what I scanned in the code" (facts) from "what is a reputation signal" (inference).

1. Never install without explicit approval, and never offer install for band 4-5.
2. SHA-pin every install and record it, so a future update can be re-vetted (rug-pull defense).
3. Respond in the user's language. No em-dashes - use a hyphen.
4. The vetter never runs the cloned code. Don't work around that.

Mode A - Discover ("find me a skill for…")

Use when the user wants ideas, or has a goal but not a specific repo.

1. Understand them first (don't ask what you can read). Skim their Claude Code setup: CLAUDE.md, any memory file, recent history, installed extensions. Form a one-line hypothesis of what they do and where an extension could help.

2. Ask 2-4 sharp questions (use AskUserQuestion). Pick what's actually unclear:

• •General sweep or a specific idea in mind?
• •The goal behind it (what would "great" look like)?
• •Which ecosystems are in scope - Skills / MCP servers / plugins / commands? (default: all)
• •Any hard constraints (no cloud, no API key, must be free)?

3. Translate intent to English search terms - the directories are English-indexed, even if the user writes in another language.

4. Run discovery (once per ecosystem in scope):

python3 SKILL_DIR/scripts/scout.py discover "<english query>" --eco skill --limit 8

(0-100 Tier-1 reputation), score_band, stars, source, repo_url, requires_code_execution.

5. Present the shortlist per references/verdict-template.md (table: # · name · what it does · outputs · score 1-100 · why/why-not · link), in the user's language. State plainly that the score is reputation, not a code audit. Close by offering a deep vet on any of them.

Mode B - Vet ("is this safe?")

Use when the user names a specific extension, or picks one from the shortlist.

1. Run the deep static scan:

python3 SKILL_DIR/scripts/scout.py vet <repo_url> [--ref <branch-or-sha>]

Returns JSON: band (1-5), band_label, sha (the exact commit scanned), findings (category · severity · file:line · snippet), green_flags, severity_counts.

2. Adjudicate findings yourself (this is the LLM half of "hybrid").

• •band 1-2: trust the scan. Summarize.
• •band 3+ or any HIGH/CRITICAL: do NOT just relay the scanner. **Read the actual flagged

lines** (fetch the file - raw GitHub URL or git show) and judge real-vs-false-positive. The scanner is deliberately trigger-happy; your job is to confirm intent.

• •Borderline trust: escalate reputation - a quick WebSearch/WebFetch on the publisher +

repo (or spawn a research subagent) for incidents, age, who they are.

3. Give the final verdict per references/verdict-template.md: risk band + label, the code facts, the reputation signal, green flags, one honest bottom line, and the mandatory caveat. Optionally collapse to a 1/2/3 shorthand (rubric) but keep the 1-5 band in any record.

4. Scoring meaning lives in references/scoring-rubric.md; the detection rules in references/threat-model.md. Read them if unsure how a number was reached.

Install on approval (only after a vet)

For band 1-2 (or band 3 the user explicitly accepts after your review):

python3 SKILL_DIR/scripts/scout.py install <repo_url> --name <name> --sha <sha> --band <N> --score <N>

This clones the exact vetted commit into ~/.claude/skills/<name>/, strips .git (static copy), records it in ~/.claude/skill-scout/registry.json, and reports whether a SKILL.md loaded. Then tell the user: it's pinned to <sha>; if it updates later, ask skill-scout to re-vet before pulling the new version.

• •MCP / plugins (Phase 2): install returns the exact claude mcp add / /plugin install

command for the user to run - it does not auto-execute these yet. Hand them the command + your verdict; never run it silently.

• •band 4-5: never offer install. State it's not recommended and why, in one clear line.

Honesty discipline

• •Mark every claim: scanned-in-code vs reputation-signal.
• •"Clean scan" = "no known red flags found", not "proven safe". Say it that way.
• •If a source failed or returned nothing (e.g. a flaky directory), say so - don't imply full

coverage.

Scope notes

• •This release fully covers the Skills ecosystem (discover + vet + install). MCP / plugins /

commands: discovery works now; deep MCP-poisoning + hooks scanning and auto-install are planned. Be honest about that boundary when asked.

• •Sources are config: references/sources.yaml. The skills.sh audit is a cross-check, never sole

truth.