skillscout-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{skillscout_cli-0.1.0 → skillscout_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillscout-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Keep your agent's skills current: weekly discovery, upstream diffs, safety scans, pinned installs
 Author: Akshit Gupta
 License-Expression: MIT
@@ -53,7 +53,7 @@ Dynamic: license-file
 ```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
+pipx install skillscout-cli
 ```
 
 AI tooling moves weekly. New skills, plugins and agent workflows land on GitHub every day, the ones you
@@ -104,33 +104,37 @@ summarises the report and shows you each skill's flags before asking to install
 ### As a CLI
 
 ```sh
-pipx install git+https://github.com/akshit9162/skillscout     # or: uv tool install git+https://...
+pipx install skillscout-cli     # or: uv tool install skillscout-cli
 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 discover          # score this week's index; 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.
+`<id>` is `owner/repo:skill-name`. The bare skill name works when it's unique. If one repo has two skills with the same name, the second is `owner/repo:path/to/skill`.
 
 ## How it works
 
+The crawl is the same for everyone, so it runs once a week in this repo's [index workflow](.github/workflows/index.yml) and is published as `index.json.gz`. `skillscout discover` downloads that one file (seconds, no GitHub token, your keywords never leave your machine) and scores it locally. `show` and `approve` fetch the skill and scan it again on your machine, so nothing is installed on the index's word. `discover --local` runs the whole crawl yourself instead.
+
+Each published index carries a signed [build attestation](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations): proof that this repo's index workflow built that exact file. Check one with `gh attestation verify ~/.skillscout/index.json.gz --repo akshit9162/skillscout`, or set `verify = true` under `[index]` and `discover` checks every download and refuses one that fails.
+
 | 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. |
+| **Discover** (weekly job, or `--local`) | 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. |
+| **Score** (your machine) | 65% relevance to your keywords (phrases match in order, singular or plural), 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. |
+| **Approve** | You pick one. It's fetched and scanned again on your machine (that scan decides), then 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, builds the new copy beside the old one and swaps them; if any step fails, the old copy and its pin stay. `skillscout rollback <id>` puts back the version an update replaced. |
 
 ## What gets flagged
 
@@ -146,6 +150,7 @@ High-risk skills need `--accept-risk`, which the bundled skill tells the agent n
 
 - Nothing installs without an explicit `approve`.
 - `approve` never overwrites a folder skillscout didn't install, and never follows symlinks.
+- A skill can't name its way out of the skills folder: a `name:` like `../../x` falls back to the folder's own name, and a path that leads outside its repo is refused. The install name comes from the `SKILL.md` fetched on your machine, not from the index.
 - 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.
@@ -155,20 +160,22 @@ High-risk skills need `--accept-risk`, which the bundled skill tells the agent n
 | 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 discover [--local [--full]] [--notify]` | Score the weekly index against your profile and write the report. `--local` crawls and scans GitHub on your machine instead; `--full` then ignores the caches; `--notify` sends a desktop notification (macOS, or Linux with `notify-send`) |
+| `skillscout index [--out FILE]` | Crawl and scan the ecosystem and write the shared index (what the weekly job runs) |
 | `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 approve <id> [--update] [--accept-risk] [--to DIR]` | Install and pin. `--to`, or `dir` under `[install]` in your profile, installs into another agent's skills folder |
+| `skillscout installed` · `skillscout remove <id>` · `skillscout rollback <id>` | Pinned skills · uninstall · undo the last update |
 | `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.
+With the index, `discover` makes no GitHub API calls at all. For `--local` and `index`, 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 1,500 a run with a token, 40 without; links not yet checked go first, so later runs reach the rest. 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.
+- The scanner is pattern rules, deliberately: a skill is text written to steer a model, so a model judging it can be steered by it. The rules make you read; they don't decide.
 - Every installed skill's description loads into every agent session. Keep the total to a few dozen.
 
 ## Development

{skillscout_cli-0.1.0 → skillscout_cli-0.2.0}/README.md

@@ -25,7 +25,7 @@
 ```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
+pipx install skillscout-cli
 ```
 
 AI tooling moves weekly. New skills, plugins and agent workflows land on GitHub every day, the ones you
@@ -76,33 +76,37 @@ summarises the report and shows you each skill's flags before asking to install
 ### As a CLI
 
 ```sh
-pipx install git+https://github.com/akshit9162/skillscout     # or: uv tool install git+https://...
+pipx install skillscout-cli     # or: uv tool install skillscout-cli
 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 discover          # score this week's index; 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.
+`<id>` is `owner/repo:skill-name`. The bare skill name works when it's unique. If one repo has two skills with the same name, the second is `owner/repo:path/to/skill`.
 
 ## How it works
 
+The crawl is the same for everyone, so it runs once a week in this repo's [index workflow](.github/workflows/index.yml) and is published as `index.json.gz`. `skillscout discover` downloads that one file (seconds, no GitHub token, your keywords never leave your machine) and scores it locally. `show` and `approve` fetch the skill and scan it again on your machine, so nothing is installed on the index's word. `discover --local` runs the whole crawl yourself instead.
+
+Each published index carries a signed [build attestation](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations): proof that this repo's index workflow built that exact file. Check one with `gh attestation verify ~/.skillscout/index.json.gz --repo akshit9162/skillscout`, or set `verify = true` under `[index]` and `discover` checks every download and refuses one that fails.
+
 | 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. |
+| **Discover** (weekly job, or `--local`) | 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. |
+| **Score** (your machine) | 65% relevance to your keywords (phrases match in order, singular or plural), 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. |
+| **Approve** | You pick one. It's fetched and scanned again on your machine (that scan decides), then 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, builds the new copy beside the old one and swaps them; if any step fails, the old copy and its pin stay. `skillscout rollback <id>` puts back the version an update replaced. |
 
 ## What gets flagged
 
@@ -118,6 +122,7 @@ High-risk skills need `--accept-risk`, which the bundled skill tells the agent n
 
 - Nothing installs without an explicit `approve`.
 - `approve` never overwrites a folder skillscout didn't install, and never follows symlinks.
+- A skill can't name its way out of the skills folder: a `name:` like `../../x` falls back to the folder's own name, and a path that leads outside its repo is refused. The install name comes from the `SKILL.md` fetched on your machine, not from the index.
 - 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.
@@ -127,20 +132,22 @@ High-risk skills need `--accept-risk`, which the bundled skill tells the agent n
 | 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 discover [--local [--full]] [--notify]` | Score the weekly index against your profile and write the report. `--local` crawls and scans GitHub on your machine instead; `--full` then ignores the caches; `--notify` sends a desktop notification (macOS, or Linux with `notify-send`) |
+| `skillscout index [--out FILE]` | Crawl and scan the ecosystem and write the shared index (what the weekly job runs) |
 | `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 approve <id> [--update] [--accept-risk] [--to DIR]` | Install and pin. `--to`, or `dir` under `[install]` in your profile, installs into another agent's skills folder |
+| `skillscout installed` · `skillscout remove <id>` · `skillscout rollback <id>` | Pinned skills · uninstall · undo the last update |
 | `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.
+With the index, `discover` makes no GitHub API calls at all. For `--local` and `index`, 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 1,500 a run with a token, 40 without; links not yet checked go first, so later runs reach the rest. 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.
+- The scanner is pattern rules, deliberately: a skill is text written to steer a model, so a model judging it can be steered by it. The rules make you read; they don't decide.
 - Every installed skill's description loads into every agent session. Keep the total to a few dozen.
 
 ## Development

{skillscout_cli-0.1.0 → skillscout_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillscout-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Keep your agent's skills current: weekly discovery, upstream diffs, safety scans, pinned installs"
 requires-python = ">=3.11"
 readme = "README.md"

{skillscout_cli-0.1.0 → skillscout_cli-0.2.0}/skillscout/cli.py

@@ -7,7 +7,7 @@ import subprocess
 import sys
 from pathlib import Path
 
-from . import __doc__ as ABOUT, core, schedule
+from . import __doc__ as ABOUT, core, github, index, schedule
 
 EXAMPLE = Path(__file__).resolve().parent / "profile.example.toml"
 USER_PROFILE = Path.home() / ".skillscout" / "profile.toml"
@@ -25,20 +25,27 @@ def main(argv: list[str] | None = None) -> None:
     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 = sub.add_parser("discover", help="score this week's shared index against your profile and write a report")
+    d.add_argument("--local", action="store_true", help="crawl and scan GitHub on this machine instead of using the index")
+    d.add_argument("--full", action="store_true", help="with --local: 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")
+    ix = sub.add_parser("index", help="crawl and scan the ecosystem and write the shared index (what the weekly job runs)")
+    ix.add_argument("--out", type=Path, default=Path("index.json.gz"))
+    ix.add_argument("--full", action="store_true", help="ignore caches: fetch every repo and re-scan every skill")
+    sh = sub.add_parser("show", help="fetch a candidate, scan it here, print its 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 = sub.add_parser("approve", help="install one skill (into ~/.claude/skills unless [install] dir says otherwise) and pin it")
     ap.add_argument("id")
+    ap.add_argument("--to", type=Path, help="install into this skills folder instead, e.g. another agent's")
     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")
+    rb = sub.add_parser("rollback", help="restore the copy the last `approve --update` replaced")
+    rb.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)")
@@ -49,36 +56,51 @@ def main(argv: list[str] | None = None) -> None:
         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())
+        USER_PROFILE.write_text(EXAMPLE.read_text(encoding="utf-8"), encoding="utf-8")
         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))
+    if folder := getattr(a, "to", None) or profile.get("install", {}).get("dir"):
+        paths.skills = Path(folder).expanduser()
     cands = core._read(paths.candidates, [])
 
     if a.cmd == "discover":
-        cands = core.discover(profile, paths, full=a.full)
+        url = profile.get("index", {}).get("url", index.URL)
+        if a.local or not url:
+            cands = core.discover(profile, paths, full=a.full)
+        else:
+            try:
+                cands = core.discover_from_index(profile, paths, url, profile.get("index", {}).get("verify", False))
+            except index.Unavailable as e:
+                raise SystemExit(str(e))
         out, summary = core.report(cands, profile, paths)
         print(f"{summary}\nreport: {out}")
         if a.notify:
             notify(summary)
+    elif a.cmd == "index":
+        records = core.crawl(profile["search"], paths, full=a.full)
+        data = index.build(records, a.out, core.RULES)
+        print(f"wrote {a.out}: {len(data['skills'])} skills from {len({r['repo'] for r in records})} repos")
     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)
+        c = core.ensure_local(core.find(cands, a.id), paths)
         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"))
+        print((src / "SKILL.md").read_text(encoding="utf-8", 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)}")
+        print(f"installed {c['id']} -> {core.approve(c, paths, a.accept_risk, a.update, fetch=github)}")
     elif a.cmd == "remove":
         print(f"removed {core.remove(a.id, paths)}")
+    elif a.cmd == "rollback":
+        print(f"restored the previous {a.id} -> {core.rollback(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']}")