skillscout-cli 0.1.0__py3-none-any.whl

skillscout/__init__.py

@@ -0,0 +1 @@
+"""Keep an agent's skills current: find what's new, diff what changed, scan everything, install only what you approve."""

skillscout/cli.py

@@ -0,0 +1,97 @@
+"""skillscout command line."""
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __doc__ as ABOUT, core, schedule
+
+EXAMPLE = Path(__file__).resolve().parent / "profile.example.toml"
+USER_PROFILE = Path.home() / ".skillscout" / "profile.toml"
+
+
+def notify(text: str) -> None:
+    if sys.platform == "darwin" and shutil.which("osascript"):
+        subprocess.run(["osascript", "-e", f'display notification "{text}" with title "skillscout"'], check=False)
+    elif shutil.which("notify-send"):
+        subprocess.run(["notify-send", "skillscout", text], check=False)
+
+
+def main(argv: list[str] | None = None) -> None:
+    p = argparse.ArgumentParser(prog="skillscout", description=ABOUT)
+    p.add_argument("--profile", type=Path, default=None, help="default: ~/.skillscout/profile.toml, else the example")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("init", help="copy the example profile to ~/.skillscout/profile.toml")
+    d = sub.add_parser("discover", help="search GitHub, scan and score skills, write a report")
+    d.add_argument("--full", action="store_true", help="ignore caches: fetch every repo and re-scan every skill")
+    d.add_argument("--notify", action="store_true", help="desktop notification with the summary (macOS, or Linux with notify-send)")
+    ls = sub.add_parser("list", help="show scored candidates")
+    ls.add_argument("--all", action="store_true", help="include zero-relevance skills")
+    ls.add_argument("-n", type=int, default=30)
+    sh = sub.add_parser("show", help="print a candidate's flags and full SKILL.md")
+    sh.add_argument("id")
+    ap = sub.add_parser("approve", help="install one skill into ~/.claude/skills and pin it")
+    ap.add_argument("id")
+    ap.add_argument("--accept-risk", action="store_true", help="install despite high-risk flags")
+    ap.add_argument("--update", action="store_true", help="replace a copy skillscout installed earlier")
+    rm = sub.add_parser("remove", help="uninstall a skill skillscout installed")
+    rm.add_argument("id")
+    sub.add_parser("installed", help="show pinned skills")
+    sub.add_parser("updates", help="diff pinned skills against upstream; applies nothing")
+    sub.add_parser("schedule", help="set up weekly discovery for this OS (you turn it on)")
+    a = p.parse_args(argv)
+
+    paths = core.Paths()
+    if a.cmd == "init":
+        if USER_PROFILE.exists():
+            raise SystemExit(f"{USER_PROFILE} already exists")
+        USER_PROFILE.parent.mkdir(parents=True, exist_ok=True)
+        USER_PROFILE.write_text(EXAMPLE.read_text())
+        print(f"wrote {USER_PROFILE}; edit [keywords] to match your work, then run `skillscout discover`")
+        return
+    profile = core.load_profile(a.profile or (USER_PROFILE if USER_PROFILE.exists() else EXAMPLE))
+    cands = core._read(paths.candidates, [])
+
+    if a.cmd == "discover":
+        cands = core.discover(profile, paths, full=a.full)
+        out, summary = core.report(cands, profile, paths)
+        print(f"{summary}\nreport: {out}")
+        if a.notify:
+            notify(summary)
+    elif a.cmd == "list":
+        rows = [c for c in cands if a.all or c["relevance"] > 0][: a.n]
+        for c in rows:
+            tag = "installed" if c["installed"] else ("REC" if core.recommended(c, profile) else "")
+            print(f"{c['score']:.2f}  {c['risk'] or '-':6}  {tag:9}  {c['id']}")
+    elif a.cmd == "show":
+        c = core.find(cands, a.id)
+        print(json.dumps({k: c[k] for k in ("id", "score", "stars", "license", "commit", "risk", "matched", "conflicts")}, indent=2))
+        for f in c["flags"]:
+            print(f"  [{f['level']}] {f['reason']} — {f['where']}")
+        src = core.source_dir(c, paths)
+        print(f"\nfiles: {', '.join(sorted(str(x.relative_to(src)) for x in src.rglob('*') if x.is_file()))}\n")
+        print((src / "SKILL.md").read_text(errors="ignore"))
+    elif a.cmd == "approve":
+        c = core.find(cands, a.id)
+        print(f"installed {c['id']} -> {core.approve(c, paths, a.accept_risk, a.update)}")
+    elif a.cmd == "remove":
+        print(f"removed {core.remove(a.id, paths)}")
+    elif a.cmd == "installed":
+        for cid, e in core._read(paths.lock, {}).items():
+            print(f"{cid}  @{e['commit'][:10]}  {e['installed_at']}")
+    elif a.cmd == "updates":
+        found = core.updates(paths)
+        for cid, commit, diff in found:
+            print(f"\n=== {cid} -> {commit[:10]}\n{diff}")
+        print(f"\n{len(found)} pinned skill(s) changed upstream." + (" Re-run `approve <id> --update` after reading the diff." if found else ""))
+    elif a.cmd == "schedule":
+        files, message = schedule.here(paths.state)
+        schedule.write(files)
+        print(message)
+
+
+if __name__ == "__main__":
+    main()

skillscout/core.py

@@ -0,0 +1,293 @@
+"""Discovery, reporting, approval and update checks."""
+
+import difflib
+import hashlib
+import json
+import shutil
+import tomllib
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import asdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+import os
+
+from . import github
+from .scan import HIGH, RULES, scan, worst
+from .score import combined, conflicts, freshness, popularity, relevance
+from .skill import find_skills, parse_frontmatter
+
+HOME = Path.home()
+STATE = HOME / ".skillscout"
+SKILLS_DIR = HOME / ".claude" / "skills"
+PLUGIN_CACHE = HOME / ".claude" / "plugins" / "cache"
+
+
+class Paths:
+    def __init__(self, state: Path = STATE, skills: Path = SKILLS_DIR, plugins: Path = PLUGIN_CACHE):
+        self.state, self.skills, self.plugins = state, skills, plugins
+        self.cache = state / "repos"
+        self.candidates = state / "candidates.json"
+        self.repos = state / "repos.json"     # each repo's metadata, push time, checkout and commit at the last run
+        self.lock = state / "skills.lock.json"
+        self.reports = state / "reports"
+
+
+def load_profile(path: Path) -> dict:
+    return tomllib.loads(path.read_text())
+
+
+def _read(path: Path, default):
+    return json.loads(path.read_text()) if path.exists() else default
+
+
+def _write(path: Path, data) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
+
+
+def digest(folder: Path) -> str:
+    h = hashlib.sha256()
+    for f in sorted(p for p in folder.rglob("*") if p.is_file() and not p.is_symlink()):
+        h.update(str(f.relative_to(folder)).encode() + b"\0" + f.read_bytes())
+    return h.hexdigest()
+
+
+def installed_skills(paths: Paths) -> dict[str, str]:
+    """name -> description for user skills and plugin skills (plugin ones as `plugin:name`)."""
+    out = {}
+    for root, prefix in ((paths.skills, ""), (paths.plugins, "plugin")):
+        if not root.exists():
+            continue
+        for md in root.rglob("SKILL.md"):
+            if ".git" in md.parts or "node_modules" in md.parts:
+                continue
+            meta = parse_frontmatter(md.read_text(errors="ignore"))
+            name = meta.get("name") or md.parent.name
+            out[f"{prefix}:{name}" if prefix else name] = meta.get("description", "")
+    return out
+
+
+def follow_lists(repos: dict, s: dict, fetch=github) -> dict:
+    """Repos linked from curated lists: the profile's `lists` plus any found repo named awesome-*.
+    Each link costs one API lookup, so at most `max_list_repos` are looked up per run; the same filters
+    (stars, freshness, size) then apply as to search results."""
+    if not s.get("follow_lists", True) or not hasattr(fetch, "readme"):
+        return {}
+    lists = set(s.get("lists", [])) | {n for n in repos if "awesome" in n.split("/")[-1].lower()}
+    known = {n.lower() for n in repos}
+    names, via = [], {}
+    for lst in sorted(lists):
+        try:
+            text = fetch.readme(lst)
+        except Exception as e:
+            print(f"list {lst}: {e}")
+            continue
+        for n in github.linked_repos(text):
+            if n.lower() not in known and n.lower() != lst.lower() and n not in via:
+                names.append(n)
+                via[n] = lst
+    cap = s.get("max_list_repos", 300 if github.token() else 40)
+
+    def look(n):
+        try:
+            return {**fetch.repo(n), "via": via[n]}
+        except Exception:                           # renamed, deleted or private: skip quietly
+            return None
+
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        found = [r for r in pool.map(look, names[:cap]) if r]
+    if lists:
+        print(f"followed {len(lists)} lists: {len(names)} linked repos, looked up {min(len(names), cap)}"
+              + (f"; {len(names) - cap} more need a token or a higher max_list_repos" if len(names) > cap else ""))
+    return {r["full_name"]: r for r in found if r["full_name"].lower() not in known}
+
+
+def discover(profile: dict, paths: Paths, fetch=github, full: bool = False) -> list[dict]:
+    """Search, clone, scan and score. Writes candidates.json and returns the candidates, best first.
+    Repos with no new pushes aren't fetched and unchanged skills aren't re-scanned, unless `full`."""
+    s = profile["search"]
+    seen = {} if full else _read(paths.repos, {})
+    repos, failed = {}, False
+    for q in s["queries"]:
+        try:
+            for r in fetch.search(q, s.get("per_query", 30)):
+                repos.setdefault(r["full_name"], r)
+        except Exception as e:                      # a failed search falls back to last run's repos below
+            print(f"search {q!r} failed: {e}")
+            failed = True
+    for name in s.get("trusted", []):
+        try:
+            repos[name] = repos.get(name) or fetch.repo(name)
+        except Exception as e:
+            print(f"lookup {name} failed: {e}")
+            failed = True
+    repos.update(follow_lists(repos, s, fetch))
+    if failed:
+        for name, e in seen.items():
+            repos.setdefault(name, e["meta"])
+
+    now = datetime.now(timezone.utc)
+    trusted = set(s.get("trusted", []))
+    keep = [r for r in repos.values() if r["full_name"] in trusted or (
+        not r["archived"] and r["stars"] >= s.get("min_stars", 0)
+        and r.get("size_kb", 0) <= s.get("max_repo_mb", 300) * 1024
+        and freshness(r["pushed_at"], now) > 1 - s.get("max_age_days", 365) / 365)]
+
+    installed = installed_skills(paths)
+    locked = _read(paths.lock, {})
+    previous = {c["id"]: c for c in _read(paths.candidates, [])}
+    stale = set()           # repos whose refresh failed: don't record their push time, so the next run retries
+    if not github.token():
+        print("tip: set GITHUB_TOKEN or run `gh auth login` for higher GitHub API limits (5,000 requests an hour instead of 60)")
+
+    def pull(r):
+        last = seen.get(r["full_name"])
+        if last and last["meta"]["pushed_at"] == r["pushed_at"] and (Path(last["root"]) / ".git").exists():
+            return r, Path(last["root"]), last["commit"]      # nothing pushed since the last run: no fetch
+        try:
+            return r, *fetch.sync(r["full_name"], paths.cache)
+        except github.Stale as e:
+            print(f"{r['full_name']}: {e}")
+            stale.add(r["full_name"])
+            return r, e.root, e.commit
+        except Exception as e:                      # one bad repo shouldn't stop the run
+            print(f"skip {r['full_name']}: {e}")
+            return None
+
+    with ThreadPoolExecutor(max_workers=s.get("workers", 16)) as pool:
+        synced = [x for x in pool.map(pull, keep) if x]
+    _write(paths.repos, {**seen, **{r["full_name"]: {"meta": r, "root": str(root), "commit": commit}
+                                    for r, root, commit in synced if r["full_name"] not in stale}})
+    print(f"fetched {sum(1 for r, *_ in synced if seen.get(r['full_name'], {}).get('meta', {}).get('pushed_at') != r['pushed_at'])} "
+          f"of {len(synced)} repos; the rest had no new pushes")
+
+    candidates, reused = [], 0
+    for r, root, commit in synced:
+        try:
+            tree_of = github.trees(root)
+        except Exception:
+            tree_of = {}
+        licensed = any((root / n).exists() for n in ("LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING"))
+        for sk in find_skills(root):
+            rel, hits = relevance(f"{sk.name} {sk.description}", profile["keywords"])
+            cid = f"{r['full_name']}:{sk.name}"
+            tree = tree_of.get(str(sk.path.relative_to(root)))
+            key = f"{RULES}:{tree}:{int(licensed)}" if tree else None
+            old = previous.get(cid)
+            if key and old and old.get("scan_key") == key and not full:     # same files, same rules: the old result stands
+                flags, reused = old["flags"], reused + 1
+            else:
+                flags = [asdict(f) for f in scan(sk.path, root)]
+            candidates.append({
+                "id": cid, "repo": r["full_name"], "name": sk.name, "description": sk.description,
+                "path": str(sk.path.relative_to(root)), "commit": commit, "stars": r["stars"],
+                "license": r["license"], "pushed_at": r["pushed_at"], "trusted": r["full_name"] in trusted,
+                "relevance": round(rel, 3), "matched": hits,
+                "score": combined(rel, popularity(r["stars"]), freshness(r["pushed_at"], now), r["full_name"] in trusted),
+                "flags": flags, "risk": worst(flags), "scan_key": key,
+                "conflicts": conflicts(sk.name, sk.description, installed, profile["scoring"]["overlap_at"]),
+                "installed": cid in locked, "new": cid not in previous,
+            })
+    print(f"scanned {len(candidates) - reused} skills, reused {reused} unchanged")
+    candidates.sort(key=lambda c: c["score"], reverse=True)
+    _write(paths.candidates, candidates)
+    return candidates
+
+
+def recommended(c: dict, profile: dict) -> bool:
+    sc = profile["scoring"]
+    return (c["score"] >= sc["recommend_at"] and c["relevance"] >= sc.get("min_relevance", 0.3) and c["risk"] != HIGH
+            and not c["conflicts"] and not c["installed"])
+
+
+def report(candidates: list[dict], profile: dict, paths: Paths, top: int = 25) -> tuple[Path, str]:
+    rec = [c for c in candidates if recommended(c, profile)]
+    flagged = [c for c in candidates if c["risk"] == HIGH and c["relevance"] > 0]
+    new = [c for c in candidates if c["new"]]
+    summary = f"{len(new)} new, {len(rec)} recommended, {len(flagged)} flagged high-risk"
+    lines = [f"# Skill report {datetime.now():%Y-%m-%d}", "", summary, "", "## New since last run", ""]
+    fresh = [c for c in rec if c["new"]]
+    if new and len(new) == len(candidates):
+        lines.append("First run: everything is new. From the next run, this section lists only what appeared since.")
+    elif fresh:
+        lines += [f"- **`{c['id']}`** ({c['stars']}★, score {c['score']:.2f}): {c['description'][:140]}" for c in fresh[:top]]
+    else:
+        lines.append("Nothing new that fits your profile.")
+    lines += ["", "Run `skillscout updates` to see what changed in the skills you already have.", "",
+              "## Recommended", "", "| Score | Skill | Stars | Risk | Matched | Why |", "|---|---|---|---|---|---|"]
+    for c in rec[:top]:
+        lines.append(f"| {c['score']:.2f} | `{c['id']}`{' 🆕' if c['new'] else ''} | {c['stars']} | {c['risk'] or 'none'} "
+                     f"| {', '.join(c['matched'][:4])} | {c['description'][:110]} |")
+    lines += ["", "Install one with `skillscout approve <id>` after reading it with `skillscout show <id>`.", "",
+              "## Relevant but blocked", ""]
+    for c in [c for c in candidates if c["relevance"] > 0 and not recommended(c, profile) and not c["installed"]][:top]:
+        why = c["conflicts"] + [f"{f['level']}: {f['reason']} ({f['where']})" for f in c["flags"] if f["level"] == HIGH]
+        if why:
+            lines.append(f"- `{c['id']}`: {'; '.join(why[:3])}")
+    paths.reports.mkdir(parents=True, exist_ok=True)
+    out = paths.reports / f"{datetime.now():%Y-%m-%d}.md"
+    out.write_text("\n".join(lines) + "\n")
+    return out, summary
+
+
+def find(candidates: list[dict], cid: str) -> dict:
+    match = [c for c in candidates if c["id"] == cid] or [c for c in candidates if c["id"].endswith(":" + cid)]
+    if len(match) != 1:
+        raise SystemExit(f"{'no' if not match else 'ambiguous'} candidate matches {cid!r}; run `skillscout list`")
+    return match[0]
+
+
+def source_dir(c: dict, paths: Paths) -> Path:
+    return paths.cache / c["repo"].replace("/", "__") / c["path"]
+
+
+def approve(c: dict, paths: Paths, accept_risk: bool = False, replace: bool = False) -> Path:
+    """Copy one skill into ~/.claude/skills and pin it in the lockfile."""
+    if c["risk"] == HIGH and not accept_risk:
+        raise SystemExit(f"{c['id']} has high-risk flags; read it with `show`, then pass --accept-risk")
+    src, dest = source_dir(c, paths), paths.skills / c["name"]
+    locked = _read(paths.lock, {})
+    if dest.exists():
+        ours = locked.get(c["id"], {}).get("digest") == digest(dest)
+        if not (replace and ours):
+            raise SystemExit(f"{dest} already exists" + ("" if ours else " and wasn't installed by skillscout"))
+        shutil.rmtree(dest)
+    # Symlinks are dropped: following one could copy files from outside the skill (e.g. ~/.ssh)
+    shutil.copytree(src, dest, ignore=lambda d, names: [n for n in names if n == ".git" or Path(d, n).is_symlink()])
+    # Pin what is actually in the cache now (an `update` check may have moved it past discovery time)
+    commit = github.git("rev-parse", "HEAD", cwd=paths.cache / c["repo"].replace("/", "__"))
+    locked[c["id"]] = {"repo": c["repo"], "path": c["path"], "commit": commit, "digest": digest(dest),
+                       "dest": str(dest), "installed_at": datetime.now(timezone.utc).isoformat(timespec="seconds")}
+    _write(paths.lock, locked)
+    return dest
+
+
+def remove(cid: str, paths: Paths) -> Path:
+    locked = _read(paths.lock, {})
+    if cid not in locked:
+        raise SystemExit(f"{cid} isn't in the lockfile")
+    dest = Path(locked.pop(cid)["dest"])
+    if dest.exists():
+        shutil.rmtree(dest)
+    _write(paths.lock, locked)
+    return dest
+
+
+def updates(paths: Paths, fetch=github) -> list[tuple[str, str, str]]:
+    """(id, new commit, unified diff) for each pinned skill whose source changed. Applies nothing."""
+    out = []
+    for cid, entry in _read(paths.lock, {}).items():
+        root, commit = fetch.sync(entry["repo"], paths.cache)
+        if commit == entry["commit"]:
+            continue
+        new, old = root / entry["path"], Path(entry["dest"])
+        diff = []
+        names = sorted({str(p.relative_to(d)) for d in (old, new) if d.exists() for p in d.rglob("*") if p.is_file()})
+        for n in names:
+            a = (old / n).read_text(errors="ignore").splitlines() if (old / n).exists() else []
+            b = (new / n).read_text(errors="ignore").splitlines() if (new / n).exists() else []
+            diff += difflib.unified_diff(a, b, f"installed/{n}", f"upstream/{n}", lineterm="")
+        if diff:
+            out.append((cid, commit, "\n".join(diff)))
+    return out

skillscout/github.py

@@ -0,0 +1,168 @@
+"""GitHub search (REST API) and shallow clones. A token is optional: GITHUB_TOKEN, or the GitHub CLI's login if `gh` is installed."""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+API = "https://api.github.com"
+MAX_WAIT = 120  # seconds to wait out one rate-limit window
+TRIES = 4
+
+
+_token = None
+
+
+def token() -> str:
+    """GITHUB_TOKEN, else the GitHub CLI's login, else empty (anonymous: 60 API requests an hour)."""
+    global _token
+    if _token is None:
+        _token = os.environ.get("GITHUB_TOKEN", "")
+        if not _token and shutil.which("gh"):
+            try:
+                _token = subprocess.run(["gh", "auth", "token"], capture_output=True, text=True, timeout=10).stdout.strip()
+            except (subprocess.SubprocessError, OSError):
+                _token = ""
+    return _token
+
+
+def _get(path: str) -> dict:
+    req = urllib.request.Request(API + path, headers={"Accept": "application/vnd.github+json",
+                                                      "User-Agent": "skillscout"})
+    if t := token():
+        req.add_header("Authorization", f"Bearer {t}")
+    for attempt in range(TRIES):
+        try:
+            with urllib.request.urlopen(req, timeout=30) as r:
+                return json.load(r)
+        except urllib.error.HTTPError as e:
+            limited = e.code == 429 or (e.code == 403 and e.headers.get("X-RateLimit-Remaining") == "0")
+            if not limited or attempt == TRIES - 1:
+                raise
+            reset = e.headers.get("Retry-After") or max(0, int(e.headers.get("X-RateLimit-Reset", 0)) - int(time.time()))
+            wait = min(int(reset) + 1, MAX_WAIT)
+            print(f"GitHub rate limit hit; waiting {wait}s" + ("" if token() else " (set GITHUB_TOKEN or log in with `gh auth login` to avoid this)"))
+            time.sleep(wait)
+
+
+def _repo(d: dict) -> dict:
+    return {"full_name": d["full_name"], "stars": d.get("stargazers_count", 0), "pushed_at": d.get("pushed_at"),
+            "license": (d.get("license") or {}).get("spdx_id"), "archived": d.get("archived", False),
+            "description": d.get("description") or "", "size_kb": d.get("size", 0)}
+
+
+def search(query: str, per_page: int) -> list[dict]:
+    q = urllib.parse.quote(query)
+    return [_repo(d) for d in _get(f"/search/repositories?q={q}&sort=stars&order=desc&per_page={per_page}")["items"]]
+
+
+def repo(full_name: str) -> dict:
+    return _repo(_get(f"/repos/{full_name}"))
+
+
+def readme(full_name: str) -> str:
+    """The README at the default branch, from raw.githubusercontent.com (no API quota used)."""
+    for name in ("README.md", "readme.md", "README.markdown", "README"):
+        req = urllib.request.Request(f"https://raw.githubusercontent.com/{full_name}/HEAD/{name}",
+                                     headers={"User-Agent": "skillscout"})
+        try:
+            with urllib.request.urlopen(req, timeout=30) as r:
+                return r.read().decode("utf-8", "replace")
+        except urllib.error.HTTPError as e:
+            if e.code != 404:
+                raise
+    raise FileNotFoundError(f"no README in {full_name}")
+
+
+# github.com paths that look like owner/repo but aren't repos
+NOT_OWNERS = {"about", "apps", "collections", "contact", "customer-stories", "enterprise", "features", "login",
+              "marketplace", "orgs", "pricing", "readme", "security", "settings", "site", "sponsors", "topics",
+              "trending", "users", "join", "explore", "notifications", "new", "codespaces", "events"}
+_LINK = re.compile(r"https?://(?:www\.)?github\.com/([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))/([A-Za-z0-9._-]{1,100})")
+
+
+def linked_repos(text: str) -> list[str]:
+    """owner/repo for every GitHub repo linked from markdown, first mention first, no duplicates."""
+    out, seen = [], set()
+    for owner, name in _LINK.findall(text):
+        name = name.removesuffix(".git").rstrip(".")
+        if owner.lower() in NOT_OWNERS or not name or name.startswith("."):
+            continue
+        full = f"{owner}/{name}"
+        if full.lower() not in seen:
+            seen.add(full.lower())
+            out.append(full)
+    return out
+
+
+def git(*args: str, cwd: Path | None = None, stdin: str | None = None) -> str:
+    return subprocess.run(["git", *args], cwd=cwd, input=stdin, check=True, capture_output=True, text=True,
+                          timeout=120, env={**os.environ, "GIT_TERMINAL_PROMPT": "0"}).stdout.strip()
+
+
+SKIP_DIRS = {"node_modules", "dist", "build", ".git"}
+
+
+# Media, fonts and archives aren't needed to judge a skill and are most of the bytes in big repos.
+# (Sizes would need every blob fetched one by one in a blobless clone, so filter by extension instead.)
+HEAVY = ["png", "jpg", "jpeg", "gif", "webp", "avif", "svg", "ico", "mp4", "mov", "webm", "mkv", "mp3", "wav",
+         "pdf", "zip", "tar", "gz", "7z", "psd", "fig", "ttf", "otf", "woff", "woff2", "bin", "onnx", "pt",
+         "safetensors", "parquet", "npy", "pkl"]
+
+
+def _skill_patterns(dest: Path, ref: str) -> list[str]:
+    """Sparse-checkout patterns: folders that hold a SKILL.md (minus heavy files and vendored dirs), plus licences."""
+    files = git("ls-tree", "-r", "--name-only", ref, cwd=dest).splitlines()
+    dirs = {str(Path(f).parent) for f in files
+            if Path(f).name == "SKILL.md" and not SKIP_DIRS & set(Path(f).parts)}
+    escape = lambda p: "".join("\\" + c if c in "*?[]!#\\" else c for c in p)
+    keep = sorted("/*" if d == "." else f"/{escape(d)}/" for d in dirs)
+    drop = [f"!*.{ext}" for ext in HEAVY] + [f"!**/{d}/" for d in sorted(SKIP_DIRS)]
+    return ["/LICENSE*", "/COPYING*"] + keep + drop
+
+
+def trees(root: Path) -> dict[str, str]:
+    """Folder path -> git tree hash at HEAD, one git call per repo. A folder's hash changes when any file in it does."""
+    out = {".": git("rev-parse", "HEAD^{tree}", cwd=root)}
+    for line in git("ls-tree", "-r", "-d", "HEAD", cwd=root).splitlines():
+        meta, path = line.split("\t", 1)
+        out[path] = meta.split()[2]
+    return out
+
+
+class Stale(Exception):
+    """The refresh failed; the cached checkout is usable but may be behind upstream."""
+
+    def __init__(self, root: Path, commit: str):
+        super().__init__(f"refresh failed, using the cached copy at {commit[:10]}")
+        self.root, self.commit = root, commit
+
+
+def sync(full_name: str, cache: Path) -> tuple[Path, str]:
+    """Sparse, shallow clone (only skill folders are downloaded) or refresh. Returns (path, commit).
+    Never runs repo code."""
+    dest = cache / full_name.replace("/", "__")
+    if (dest / ".git").exists():
+        for attempt in range(2):
+            try:
+                git("fetch", "-q", "--depth", "1", "--filter=blob:none", "origin", "HEAD", cwd=dest)
+                break
+            except subprocess.SubprocessError:
+                if attempt:     # refresh failed twice: keep the cached copy rather than dropping the repo
+                    raise Stale(dest, git("rev-parse", "HEAD", cwd=dest))
+                time.sleep(3)
+        ref = "FETCH_HEAD"
+    else:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        git("clone", "-q", "--depth", "1", "--no-tags", "--filter=blob:none", "--no-checkout",
+            f"https://github.com/{full_name}.git", str(dest))
+        ref = "HEAD"
+    git("sparse-checkout", "set", "--no-cone", "--stdin", cwd=dest, stdin="\n".join(_skill_patterns(dest, ref)) + "\n")
+    git("reset", "-q", "--hard", ref, cwd=dest)
+    return dest, git("rev-parse", "HEAD", cwd=dest)

skillscout/profile.example.toml

@@ -0,0 +1,52 @@
+# skillscout profile. `skillscout init` copies this to ~/.skillscout/profile.toml; edit that copy.
+# Keyword weights say how much a match matters. Replace them with words from your own work.
+
+[search]
+# GitHub repository-search queries, run on every `skillscout discover`.
+queries = [
+  "topic:claude-skills",
+  "topic:agent-skills",
+  "topic:claude-code-skills",
+  "topic:claude-code-plugin",
+  "\"SKILL.md\" claude in:readme",
+]
+per_query = 30          # repos per query, by stars
+min_stars = 50
+max_age_days = 365      # skip repos with no push in this window
+max_repo_mb = 300       # skip huge repos (trusted ones are always fetched)
+workers = 16            # repos fetched at once; lower it on a slow connection
+
+# Curated lists whose README links are followed (any found repo named awesome-* is followed too).
+# Each linked repo costs one API lookup: 300 a run with a token, 40 without.
+follow_lists = true
+lists = [
+  "hesreallyhim/awesome-claude-code",
+  "travisvn/awesome-claude-skills",
+  "ComposioHQ/awesome-claude-skills",
+  "VoltAgent/awesome-agent-skills",
+]
+# max_list_repos = 300
+
+# Always checked, whatever the search returns.
+trusted = [
+  "anthropics/skills",
+  "obra/superpowers",
+]
+
+[keywords]
+"python" = 2
+"typescript" = 2
+"react" = 2
+"testing" = 2
+"debugging" = 2
+"code review" = 2
+"documentation" = 1
+"api" = 1
+"database" = 1
+"security" = 1
+"design" = 1
+
+[scoring]
+recommend_at = 0.45     # combined score needed to be recommended
+min_relevance = 0.3     # and at least this much keyword overlap with your work
+overlap_at = 0.35       # description similarity that counts as a conflict with an installed skill

skillscout/scan.py

@@ -0,0 +1,110 @@
+"""Static safety checks on a skill folder. Flags things to read before installing; it can't prove a skill safe."""
+
+import hashlib
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+HIGH, MEDIUM, LOW = "high", "medium", "low"
+
+# (level, reason, regex, trigger words). Regexes run on lowercased text and only when a trigger word
+# appears, which keeps scanning fast (case-insensitive regex disables Python's literal-prefix search).
+PATTERNS = [
+    (HIGH, "pipes a download into a shell", r"(curl|wget)[^\n|]{0,200}\|\s*(sudo\s+)?(ba|z)?sh\b", ("curl", "wget")),
+    (HIGH, "runs sudo", r"\bsudo\s+\w", ("sudo",)),
+    (HIGH, "deletes recursively from a broad path", r"rm\s+-[a-z]*r[a-z]*f?\s+(/|~|\$home)(\s|$|/\*)", ("rm ",)),
+    (HIGH, "reads SSH keys or the keychain", r"~/\.ssh|\.ssh/id_|security\s+find-(generic|internet)-password|git credential fill",
+     (".ssh", "find-generic", "find-internet", "credential fill")),
+    (HIGH, "decodes and executes", r"base64\s+(-d|--decode)[^\n]{0,200}\|\s*(ba|z)?sh", ("base64",)),
+    (HIGH, "tells the agent to ignore its instructions",
+     r"ignore (all |any )?(previous|prior|above) instructions|disregard (your|the) (system|previous)", ("ignore", "disregard")),
+    (HIGH, "tells the agent to hide actions from the user",
+     r"without (telling|informing|asking) the user|(do not|don't|never) (tell|inform|show) the user (about|that you|what you)"
+     r"|(hide|conceal|keep) (this|it|these|that) (secret |hidden )?from the user", (" the user",)),
+    (HIGH, "uploads local files", r"curl[^\n]{0,200}?\s(-f|--data(-binary)?|-d)\s+@|scp\s+\S+\s+\S+@", ("curl", "scp ")),
+    (MEDIUM, "reads .env or API keys", r"cat\s+[^\n]{0,120}?\.env\b|printenv|env\s*\|\s*grep|(api|secret)_key\s*=\s*\$",
+     (".env", "printenv", "env", "_key")),
+    (MEDIUM, "pushes or force-pushes git", r"git\s+push\s+(-f|--force)", ("git push",)),
+    (MEDIUM, "edits shell profiles or Claude settings", r"(>>|>)\s*~/\.(zshrc|bashrc|profile|claude/settings)",
+     ("zshrc", "bashrc", "profile", "claude/settings")),
+    (MEDIUM, "disables permission prompts", r"dangerously-?skip-?permissions|bypasspermissions", ("dangerously", "bypasspermissions")),
+]
+HIDDEN = re.compile("[\u200b\u200c\u2060\u202a-\u202e\u2066-\u2069]")   # zero-width + bidi controls; not ZWJ (emoji) or BOM
+SCRIPT_EXT = {".sh", ".py", ".js", ".cjs", ".mjs", ".ts", ".rb", ".ps1", ".cmd", ".bat", ""}
+MAX_SCAN = 512_000   # bytes; bigger text files (minified bundles, data) are flagged unscanned
+NETWORK = re.compile(r"\b(requests\.|urllib|fetch\(|https?://|socket\.|XMLHttpRequest|axios)")
+
+
+@dataclass
+class Flag:
+    level: str
+    reason: str
+    where: str
+
+
+COMPILED = [(level, reason, re.compile(pat), words) for level, reason, pat, words in PATTERNS]
+MAX_FILES = 400       # per skill; a skill at a repo's root can otherwise mean scanning the whole repo
+_file_cache: dict[tuple[str, float], list[tuple[str, str, int | None]]] = {}
+
+
+def _scan_file(f: Path) -> list[tuple[str, str, int | None]]:
+    """(level, reason, line) findings for one file, memoised per run so nested skills don't rescan."""
+    key = (str(f), f.stat().st_mtime)
+    if key in _file_cache:
+        return _file_cache[key]
+    out: list[tuple[str, str, int | None]] = []
+    if f.stat().st_size > MAX_SCAN:
+        out.append((MEDIUM, "file too large to scan", None))
+    else:
+        try:
+            text = f.read_text(errors="strict")
+        except (UnicodeDecodeError, OSError):
+            out.append((MEDIUM, "bundled binary file", None))
+        else:
+            low = text.lower()
+            for level, reason, rx, words in COMPILED:
+                if any(w in low for w in words) and (m := rx.search(low)):
+                    out.append((level, reason, low.count("\n", 0, m.start()) + 1))
+            if HIDDEN.search(text):
+                out.append((HIGH, "contains hidden or direction-changing Unicode", None))
+            if f.suffix in SCRIPT_EXT and f.name != "SKILL.md" and (f.suffix or text.startswith("#!")):
+                net = bool(NETWORK.search(text))
+                out.append((MEDIUM if net else LOW, "bundled script that makes network calls" if net else "bundled script", None))
+    if f.name in {"hooks.json", "settings.json"}:
+        out.append((MEDIUM, "defines hooks or settings", None))
+    _file_cache[key] = out
+    return out
+
+
+# Fingerprint of the rules and of what the clone keeps (github.py): a change to either invalidates
+# every cached scan result.
+RULES = hashlib.sha256(b"".join((Path(__file__).parent / f).read_bytes() for f in ("scan.py", "github.py"))).hexdigest()[:12]
+
+
+def scan(skill_dir: Path, repo_root: Path | None = None) -> list[Flag]:
+    flags, files = [], 0
+    for f in sorted(skill_dir.rglob("*")):
+        if ".git" in f.relative_to(skill_dir).parts:
+            continue
+        rel = str(f.relative_to(skill_dir))
+        if f.is_symlink():
+            flags.append(Flag(MEDIUM, "symlink (could point outside the skill)", rel))
+            continue
+        if not f.is_file():
+            continue
+        files += 1
+        if files > MAX_FILES:
+            flags.append(Flag(MEDIUM, f"more than {MAX_FILES} files; the rest weren't scanned", "."))
+            break
+        flags += [Flag(level, reason, f"{rel}:{line}" if line else rel) for level, reason, line in _scan_file(f)]
+    if repo_root and not any((repo_root / n).exists() for n in ("LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING")):
+        flags.append(Flag(LOW, "repo has no licence file", "repo"))
+    return flags
+
+
+def worst(flags: list[Flag] | list[dict]) -> str | None:
+    levels = {f["level"] if isinstance(f, dict) else f.level for f in flags}
+    for level in (HIGH, MEDIUM, LOW):
+        if level in levels:
+            return level
+    return None

skillscout/schedule.py

@@ -0,0 +1,75 @@
+"""Weekly discovery on each platform. Writes the job's files, never turns them on."""
+
+import shutil
+import sys
+from pathlib import Path
+
+LABEL = "com.skillscout.weekly"
+
+
+def _cmd(exe: Path) -> list[str]:
+    return [str(exe), "-m", "skillscout.cli", "discover", "--notify"]
+
+
+def plan(platform: str, exe: Path, state: Path, home: Path, has_systemd: bool) -> tuple[dict[Path, str], str]:
+    """Returns the files to write and what to tell the user. Nothing here touches disk."""
+    log = state / "weekly.log"
+    if platform == "darwin":
+        plist = home / "Library" / "LaunchAgents" / f"{LABEL}.plist"
+        args = "".join(f"<string>{a}</string>" for a in _cmd(exe))
+        text = f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>{LABEL}</string>
+  <key>ProgramArguments</key><array>{args}</array>
+  <key>StartCalendarInterval</key><dict><key>Weekday</key><integer>1</integer><key>Hour</key><integer>10</integer><key>Minute</key><integer>0</integer></dict>
+  <key>StandardOutPath</key><string>{log}</string>
+  <key>StandardErrorPath</key><string>{log}</string>
+</dict></plist>
+"""
+        return {plist: text}, f"wrote {plist}\nturn it on with:  launchctl load {plist}\nturn it off with: launchctl unload {plist}"
+
+    if platform.startswith("linux") and has_systemd:
+        unit = home / ".config" / "systemd" / "user"
+        service = f"""[Unit]
+Description=skillscout weekly discovery
+
+[Service]
+Type=oneshot
+ExecStart={" ".join(f'"{a}"' for a in _cmd(exe))}
+StandardOutput=append:{log}
+StandardError=append:{log}
+"""
+        timer = """[Unit]
+Description=Run skillscout discover every Monday at 10:00
+
+[Timer]
+OnCalendar=Mon *-*-* 10:00:00
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+"""
+        files = {unit / "skillscout.service": service, unit / "skillscout.timer": timer}
+        return files, (f"wrote {unit}/skillscout.service and skillscout.timer\n"
+                       "turn it on with:  systemctl --user daemon-reload && systemctl --user enable --now skillscout.timer\n"
+                       "turn it off with: systemctl --user disable --now skillscout.timer")
+
+    if platform in ("win32", "cygwin"):
+        tr = " ".join(f'\\"{a}\\"' if " " in a else a for a in _cmd(exe))
+        return {}, ("Windows has no file to write. Turn it on in a terminal with:\n"
+                    f'  schtasks /Create /SC WEEKLY /D MON /ST 10:00 /TN skillscout-weekly /TR "{tr}"\n'
+                    "turn it off with: schtasks /Delete /TN skillscout-weekly /F")
+
+    line = f"0 10 * * 1 {' '.join(_cmd(exe))} >> {log} 2>&1"
+    return {}, f"no systemd found. Add this line with `crontab -e`:\n  {line}"
+
+
+def write(files: dict[Path, str]) -> None:
+    for path, text in files.items():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text)
+
+
+def here(state: Path) -> tuple[dict[Path, str], str]:
+    return plan(sys.platform, Path(sys.executable), state, Path.home(), shutil.which("systemctl") is not None)

skillscout/score.py

@@ -0,0 +1,61 @@
+"""Relevance to your profile, popularity, freshness, and overlap with skills you already have."""
+
+import math
+import re
+from datetime import datetime, timezone
+
+WORD = re.compile(r"[a-z0-9]+")
+STOP = set("a an and the of to for in on with when use used using or is are be this that it its your you any as by from".split())
+
+
+def tokens(text: str) -> set[str]:
+    return {w for w in WORD.findall(text.lower()) if w not in STOP and len(w) > 2}
+
+
+def relevance(text: str, keywords: dict[str, float]) -> tuple[float, list[str]]:
+    """Share of the best achievable keyword weight this text hits, capped so 3 strong matches reach 1."""
+    low = " " + " ".join(WORD.findall(text.lower())) + " "
+    hits = [k for k in keywords if f" {' '.join(WORD.findall(k.lower()))} " in low]
+    top = sorted(keywords.values(), reverse=True)[:3]
+    return min(sum(keywords[k] for k in hits) / max(sum(top), 1e-9), 1.0), hits
+
+
+def popularity(stars: int) -> float:
+    return min(math.log10(max(stars, 1)) / 4, 1.0)          # 10k stars = 1.0
+
+
+def freshness(pushed_at: str | None, now: datetime | None = None) -> float:
+    if not pushed_at:
+        return 0.0
+    now = now or datetime.now(timezone.utc)
+    days = (now - datetime.fromisoformat(pushed_at.replace("Z", "+00:00"))).days
+    return max(0.0, 1 - days / 365)
+
+
+def combined(rel: float, pop: float, fresh: float, trusted: bool) -> float:
+    return round(min(0.65 * rel + 0.2 * pop + 0.15 * fresh + (0.1 if trusted else 0), 1.0), 3)
+
+
+def similarity(a: str | set[str], b: str | set[str]) -> float:
+    ta = a if isinstance(a, set) else tokens(a)
+    tb = b if isinstance(b, set) else tokens(b)
+    return len(ta & tb) / len(ta | tb) if ta and tb else 0.0
+
+
+_token_cache: dict[str, set[str]] = {}
+
+
+def conflicts(name: str, description: str, installed: dict[str, str], overlap_at: float) -> list[str]:
+    """Installed skills with the same name or a description that would trigger on the same prompts."""
+    out, mine = [], tokens(description)
+    for other, desc in installed.items():
+        short = other.split(":")[-1]
+        if short == name:
+            out.append(f"same name as installed `{other}`")
+            continue
+        theirs = _token_cache.get(desc)
+        if theirs is None:
+            theirs = _token_cache[desc] = tokens(desc)
+        if (s := similarity(mine, theirs)) >= overlap_at:
+            out.append(f"overlaps `{other}` ({s:.0%} similar)")
+    return out

skillscout/skill.py

@@ -0,0 +1,54 @@
+"""Reading SKILL.md files."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+    path: Path                      # directory holding SKILL.md
+    files: list[str] = field(default_factory=list)
+
+
+def parse_frontmatter(text: str) -> dict[str, str]:
+    """Minimal YAML frontmatter reader: `key: value`, quoted values and folded (`>`, `|`) blocks."""
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}
+    meta, key, block = {}, None, []
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        if key and (line.startswith((" ", "\t")) or not line.strip()):
+            block.append(line.strip())
+            continue
+        if key:
+            meta[key], key, block = " ".join(b for b in block if b), None, []
+        if ":" in line and not line.startswith((" ", "\t")):
+            k, v = line.split(":", 1)
+            v = v.strip()
+            if v in (">", ">-", "|", "|-"):
+                key = k.strip()
+            else:
+                meta[k.strip()] = v.strip("\"'")
+    if key:
+        meta[key] = " ".join(b for b in block if b)
+    return meta
+
+
+def find_skills(root: Path) -> list[Skill]:
+    """Every SKILL.md under root, skipping vendored and VCS folders and duplicate names."""
+    skills, seen = [], set()
+    for md in sorted(root.rglob("SKILL.md")):
+        if any(part in {".git", "node_modules", "dist", "build"} for part in md.parts) or md.is_symlink() or not md.is_file():
+            continue
+        meta = parse_frontmatter(md.read_text(errors="ignore"))
+        name = meta.get("name") or md.parent.name
+        if name in seen:
+            continue
+        seen.add(name)
+        files = sorted(str(p.relative_to(md.parent)) for p in md.parent.rglob("*") if p.is_file() and not p.is_symlink())
+        skills.append(Skill(name, meta.get("description", ""), md.parent, files))
+    return skills

skillscout_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: skillscout-cli
+Version: 0.1.0
+Summary: Keep your agent's skills current: weekly discovery, upstream diffs, safety scans, pinned installs
+Author: Akshit Gupta
+License-Expression: MIT
+Project-URL: Homepage, https://akshit9162.github.io/skillscout
+Project-URL: Source, https://github.com/akshit9162/skillscout
+Project-URL: Issues, https://github.com/akshit9162/skillscout/issues
+Project-URL: Report, https://akshit9162.github.io/skillscout/report.html
+Keywords: claude,claude-code,agent-skills,security,supply-chain,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/akshit9162/skillscout/main/docs/assets/header.svg" width="760" alt="skillscout: keep your agent's skills current, safely" />
+</p>
+
+<p align="center">
+  <a href="https://akshit9162.github.io/skillscout">Website</a> &ensp;·&ensp;
+  <a href="https://akshit9162.github.io/skillscout/report.html">Report: what's inside 6,726 skills</a> &ensp;·&ensp;
+  <a href="#install">Install</a> &ensp;·&ensp;
+  <a href="#a-week-with-skillscout">A week with it</a> &ensp;·&ensp;
+  <a href="#how-it-works">How it works</a> &ensp;·&ensp;
+  <a href="#what-gets-flagged">What gets flagged</a>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT licence" /></a>
+  <a href="https://github.com/akshit9162/skillscout/actions/workflows/ci.yml"><img src="https://github.com/akshit9162/skillscout/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+" />
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen.svg" alt="No dependencies" />
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/akshit9162/skillscout/main/docs/assets/demo.svg" width="760" alt="Terminal demo: discover finds 216 recommended skills with 89 flagged high-risk; a high-risk skill is refused without --accept-risk; a low-risk one installs pinned to a commit" />
+</p>
+
+```bash
+claude plugin marketplace add akshit9162/skillscout && claude plugin install skillscout@skillscout
+# or the CLI on its own
+pipx install git+https://github.com/akshit9162/skillscout
+```
+
+AI tooling moves weekly. New skills, plugins and agent workflows land on GitHub every day, the ones you
+installed keep changing upstream, and last month's best practice is already stale. Nobody has time to
+watch hundreds of repos.
+
+**skillscout keeps your agent current.** Once a week it checks the skill ecosystem against what *you*
+work on, tells you what's new and worth having, and shows you exactly what changed in the skills you
+already use.
+
+Keeping up fast is only useful if it's safe. A skill is a set of instructions your agent follows
+**with your permissions**, so skillscout scans every file for dangerous patterns, installs nothing without
+your approval, pins each install to an exact commit, and re-scans every update before it can replace anything.
+
+In one run over the public ecosystem it found **6,726 skills in 95 repos**. 198 had at least one high-risk flag,
+mostly `sudo` and `curl | sh` install steps, plus prompt-injection-style text and hidden Unicode.
+The [report](https://akshit9162.github.io/skillscout/report.html) reads every one of the scariest flags: they were defenders.
+
+It's a zero-dependency Python CLI, and it also ships as a skill, so your agent can run the whole loop for you
+and still ask before every install.
+
+## A week with skillscout
+
+Example session (counts vary week to week):
+
+```text
+Monday 10:00   skillscout discover --notify     (weekly, via schedule)
+               → "4 new, 23 recommended, 11 flagged high-risk"
+You            skillscout show github/awesome-copilot:eval-driven-dev
+               → flags with file:line, the full SKILL.md, overlaps with what you have
+You            skillscout approve eval-driven-dev   → copied, pinned to its commit
+Later          skillscout updates               → upstream changed it; here's the diff
+You            skillscout approve eval-driven-dev --update   → re-scanned, then replaced
+```
+
+## Install
+
+### As a Claude Code plugin (the agent drives it)
+
+```sh
+claude plugin marketplace add akshit9162/skillscout
+claude plugin install skillscout@skillscout
+```
+
+Then ask: *"find me skills for my Python and React work"*. The agent installs the CLI, runs the search,
+summarises the report and shows you each skill's flags before asking to install it.
+
+### As a CLI
+
+```sh
+pipx install git+https://github.com/akshit9162/skillscout     # or: uv tool install git+https://...
+skillscout init                                              # writes ~/.skillscout/profile.toml
+```
+
+Edit `[keywords]` in `~/.skillscout/profile.toml` with the words from your own work, then:
+
+```sh
+skillscout discover          # search, scan, score; writes ~/.skillscout/reports/<date>.md
+skillscout list              # ranked; REC = recommended
+skillscout show <id>         # every flag plus the full SKILL.md, before you decide
+skillscout approve <id>      # copy into ~/.claude/skills and pin the commit
+```
+
+`<id>` is `owner/repo:skill-name`. The bare skill name works when it's unique.
+
+## How it works
+
+| Step | What happens |
+|---|---|
+| **Discover** | Runs your GitHub searches (topics like `claude-skills`, `agent-skills`) plus your trusted repos, then follows every repo linked from curated lists (your `lists`, plus any `awesome-*` repo it finds). Drops archived, stale (no push in a year), unpopular and huge repos. |
+| **Clone** | Sparse, shallow clones: only folders that contain a `SKILL.md`, minus media and archives, 16 repos at a time. Repos with no push since the last run aren't fetched again. Repo code is never run. |
+| **Scan** | Static checks on every file in the skill, reported with file and line ([below](#what-gets-flagged)). A skill whose folder (git tree hash) and the scanner's rules are both unchanged keeps its last result instead of being read again. |
+| **Score** | 65% relevance to your keywords, 20% stars, 15% freshness, plus a bonus for trusted repos. |
+| **Conflicts** | Compared against your `~/.claude/skills` and plugin skills: same name, or a description close enough that both would fire on the same prompt. |
+| **Report** | What's new since your last run, recommended skills, and relevant ones that are blocked and why. |
+| **Approve** | You pick one. It's copied (symlinks dropped) and pinned in `~/.skillscout/skills.lock.json` with its commit and a content hash. |
+| **Update** | `skillscout updates` diffs each pinned skill against upstream and applies nothing. Taking an update re-runs the scan. |
+
+## What gets flagged
+
+| Level | Patterns |
+|---|---|
+| **High**, blocks install | Download piped into a shell · `sudo` · broad `rm -rf` · reading SSH keys or the keychain · decode-and-execute · uploading local files · hidden or direction-changing Unicode · "ignore previous instructions" · "don't tell the user" |
+| **Medium** | Reading `.env` or API keys · force pushes · editing shell profiles or Claude settings · skipping permission prompts · hooks · scripts that make network calls · symlinks · binaries |
+| **Low** | Other bundled scripts · no licence |
+
+High-risk skills need `--accept-risk`, which the bundled skill tells the agent never to pass on its own.
+
+## Safety rails
+
+- Nothing installs without an explicit `approve`.
+- `approve` never overwrites a folder skillscout didn't install, and never follows symlinks.
+- Every install is pinned to a commit and a content hash.
+- Updates are a diff first, and re-scanned before they replace anything. The test suite includes an upstream
+  update that slips in `sudo rm -rf /`, and checks that re-approval refuses it.
+
+## Every command
+
+| Command | Does |
+|---|---|
+| `skillscout init` | Copy the example profile to `~/.skillscout/profile.toml` |
+| `skillscout discover [--full] [--notify]` | Search, scan, score, write the report. `--full` ignores the caches; `--notify` sends a desktop notification (macOS, or Linux with `notify-send`) |
+| `skillscout list [--all] [-n N]` | Ranked candidates |
+| `skillscout show <id>` | Flags, conflicts and the full SKILL.md |
+| `skillscout approve <id> [--update] [--accept-risk]` | Install and pin |
+| `skillscout installed` · `skillscout remove <id>` | Pinned skills · uninstall |
+| `skillscout updates` | Diff pinned skills against upstream |
+| `skillscout schedule` | Set up weekly discovery: launchd on macOS, a systemd timer on Linux (cron line without systemd), a `schtasks` command on Windows. It prints the one command that turns it on |
+
+Set `GITHUB_TOKEN`, or just be logged in with the GitHub CLI (`gh auth login`), for higher API rate limits (5,000 requests an hour instead of 60). Following lists costs one lookup per linked repo: up to 300 a run with a token, 40 without. A token is optional: without it, a rate limit means waiting rather than failing. A weekly run with few upstream changes takes about 25 seconds; the first run takes a few minutes. Scheduled jobs don't see your shell's environment, so add the token to the job if you want it there.
+
+## Limits
+
+- The scanner catches known patterns. It can't prove a skill is safe, so read `show` before you approve.
+- Relevance is keyword matching against your profile, not semantic search. Tune the weights.
+- Every installed skill's description loads into every agent session. Keep the total to a few dozen.
+
+## Development
+
+```sh
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+```
+
+## License
+
+MIT

skillscout_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+skillscout/__init__.py,sha256=MMpOs56DKWVinCMwDc8ddUkt-zGT8m736kRa8bo4xVg,122
+skillscout/cli.py,sha256=hjiYrYK-Cw0i7f0Vc7UunSuJYVnaZmuTDxJrmZpC3fA,4819
+skillscout/core.py,sha256=cNdIa9DAkRkTonYn5o-iiN2hsfOjiwX4N2kYR06CjPs,14275
+skillscout/github.py,sha256=y1ykP_eGbm0bv3Z7c8tIQfBPLDaUpn-SMrquart1cIU,7598
+skillscout/profile.example.toml,sha256=9M4aoxW1ZtQDrjO4F9yt0xi8b0js8JdwF4JzI9poqZ8,1635
+skillscout/scan.py,sha256=H-oq97lDLe-UxwTt3Q4LHwMh52ho-Vl54v4d_BYOf_I,5797
+skillscout/schedule.py,sha256=PUfQaUc4zbGxPd3A_uBDcp3WClL8jUHLHHHrfQ1GFaM,3112
+skillscout/score.py,sha256=Yul-87PX2kuzBMQt2LqPk--n8gUurLYPLXX2ZkPbllU,2436
+skillscout/skill.py,sha256=kycyjJusZiS2ObPaolJE_z0ZVpMYAmaj2MVAVldxbzs,1978
+skillscout_cli-0.1.0.dist-info/licenses/LICENSE,sha256=hes6NS-2Pmc39Kvspmg8gfCxag_lZWOMKAgV_VaCgJ4,1069
+skillscout_cli-0.1.0.dist-info/METADATA,sha256=hj607jkTQjsjpjs3x9VBsY9-dugJ6C3CZ_n-7m9mO1E,10158
+skillscout_cli-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+skillscout_cli-0.1.0.dist-info/entry_points.txt,sha256=xWKgTnjOc0uMtJAK1Bnm3Zh6hIaMtnAwghR9V1a1W0A,51
+skillscout_cli-0.1.0.dist-info/top_level.txt,sha256=Kh9gUf5ykVewMvBCZ5v2GLGAxTV29sxkjC6bmnAIoYc,11
+skillscout_cli-0.1.0.dist-info/RECORD,,

skillscout_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

skillscout_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+skillscout = skillscout.cli:main

skillscout_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akshit Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skillscout_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+skillscout