skillscout-cli 0.1.0__tar.gz

skillscout_cli-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,155 @@
+<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/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "skillscout-cli"
+version = "0.1.0"
+description = "Keep your agent's skills current: weekly discovery, upstream diffs, safety scans, pinned installs"
+requires-python = ">=3.11"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Akshit Gupta" }]
+keywords = ["claude", "claude-code", "agent-skills", "security", "supply-chain", "llm"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: Software Development",
+]
+
+[project.urls]
+Homepage = "https://akshit9162.github.io/skillscout"
+Source = "https://github.com/akshit9162/skillscout"
+Issues = "https://github.com/akshit9162/skillscout/issues"
+Report = "https://akshit9162.github.io/skillscout/report.html"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+skillscout = "skillscout.cli:main"
+
+[tool.setuptools]
+packages = ["skillscout"]
+
+[tool.setuptools.package-data]
+skillscout = ["profile.example.toml"]

skillscout_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

skillscout_cli-0.1.0/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-0.1.0/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()