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

skillscout_cli-0.3.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: skillscout-cli
+Version: 0.3.0
+Summary: Keep your agent's skills current for each kind of work you do: weekly index, personas, 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,personas,subagents,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="#personas">Personas</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: init drafts keywords from one line; persona add creates a brand persona; discover scores 23,865 skills with a section for the brand persona; persona build writes its agent; claude --agent brand starts it" />
+</p>
+
+```bash
+claude plugin marketplace add akshit9162/skillscout && claude plugin install skillscout@skillscout
+# or the CLI on its own
+pipx install skillscout-cli
+```
+
+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, for each kind of work you do.** Every week a shared index of every
+public skill it can find (23,865 from 1,092 repos at the last build) is rebuilt. skillscout scores it on your
+machine 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.
+
+You probably don't do one kind of work. Coding on Monday, a landing page on Tuesday, investor emails on
+Friday. So skillscout keeps **personas**: one per kind of work, each with its own search and its own Claude
+Code agent, loaded with the best skills for that work and kept up to date as better ones appear.
+
+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 a hand-checked run on 27 Oct 2026 over **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.
+
+## Personas
+
+A persona is one side of your work, in your words. skillscout doesn't ship any: yours might be "builder",
+"brand" and "outreach", someone else's "trading" and "thesis".
+
+```text
+You     "set up personas for me"           (in Claude Code, with the plugin)
+Agent   reads your recent sessions on this machine, with your OK (skillscout history)
+        → proposes: builder · brand · outreach, each with the sessions it came from
+You     keep brand and builder, rename outreach to launches
+Agent   skillscout persona add brand --about "D2C marketing: ad copy, landing pages, Instagram reels"
+        → keywords drafted from terms skills actually use: instagram reels, ad copy, landing pages...
+        skillscout discover                → a "For your brand work" section in the report
+        skillscout persona build brand     → ~/.claude/agents/brand.md, skills: copy, landing-page-design, script...
+You     claude --agent brand
+```
+
+From then on, each weekly report has a section per persona, and `persona build` swaps in a better skill when
+one arrives (after you've read and approved it). `persona build` only ever rewrites the agent's `skills:` list:
+its prompt, tone, tools, model and memory are yours.
+
+The CLI works without the agent too:
+
+```sh
+skillscout persona add brand --about "D2C marketing: ad copy, landing pages, Instagram reels"
+skillscout persona list            # keywords, best installed skills, what's worth installing
+skillscout persona build --all     # write or update ~/.claude/agents/<name>.md
+```
+
+**Your history stays on your machine.** `skillscout history` reads `~/.claude/projects` only when you run it,
+keeps only what you typed (no tool output, no pasted blocks, no links) and sends nothing anywhere. Grouping
+sessions into personas is left to you or the agent in your own session: counting words can't tell short chat
+messages apart reliably, and a wrong persona is worse than none.
+
+## A week with skillscout
+
+Example session (counts vary week to week):
+
+```text
+Monday 10:00   skillscout discover --notify     (weekly, via schedule)
+               → "23 recommended for you (4 new this run), 11 relevant but flagged high-risk"
+               → plus a section per persona: "For your brand work", "For your builder work"
+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"*, or *"set up personas for me"*. 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 skillscout-cli     # or: uv tool install skillscout-cli
+skillscout init --about "backend in Python, code review, RL evals, Postgres"
+```
+
+`init` writes `~/.skillscout/profile.toml` and drafts `[keywords]` from your line, using only terms that skills
+actually use. Check them, then:
+
+```sh
+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. 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** (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** (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 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
+
+| 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.
+- 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.
+
+## Every command
+
+| Command | Does |
+|---|---|
+| `skillscout init` | Copy the example profile to `~/.skillscout/profile.toml` |
+| `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] [--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 init [--about "..."]` | Write the profile; `--about` drafts your keywords from one line |
+| `skillscout history [--days N]` | A local digest of your recent Claude Code sessions, to draft personas from |
+| `skillscout persona add <name> --about "..." [--keywords "a=3,b=2"]` | Add a persona; keywords drafted from the line unless given |
+| `skillscout persona list` | Each persona: keywords, best installed skills, what's worth installing |
+| `skillscout persona build <name> \| --all [--dry-run]` | Write `~/.claude/agents/<name>.md`, or update only its `skills:` list |
+| `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 |
+
+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.
+- A persona's `skills:` load in full when its agent starts. `max_skills` (default 5) keeps that small.
+
+## Development
+
+```sh
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+```
+
+## License
+
+MIT

skillscout_cli-0.3.0/README.md

@@ -0,0 +1,210 @@
+<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="#personas">Personas</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: init drafts keywords from one line; persona add creates a brand persona; discover scores 23,865 skills with a section for the brand persona; persona build writes its agent; claude --agent brand starts it" />
+</p>
+
+```bash
+claude plugin marketplace add akshit9162/skillscout && claude plugin install skillscout@skillscout
+# or the CLI on its own
+pipx install skillscout-cli
+```
+
+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, for each kind of work you do.** Every week a shared index of every
+public skill it can find (23,865 from 1,092 repos at the last build) is rebuilt. skillscout scores it on your
+machine 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.
+
+You probably don't do one kind of work. Coding on Monday, a landing page on Tuesday, investor emails on
+Friday. So skillscout keeps **personas**: one per kind of work, each with its own search and its own Claude
+Code agent, loaded with the best skills for that work and kept up to date as better ones appear.
+
+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 a hand-checked run on 27 Oct 2026 over **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.
+
+## Personas
+
+A persona is one side of your work, in your words. skillscout doesn't ship any: yours might be "builder",
+"brand" and "outreach", someone else's "trading" and "thesis".
+
+```text
+You     "set up personas for me"           (in Claude Code, with the plugin)
+Agent   reads your recent sessions on this machine, with your OK (skillscout history)
+        → proposes: builder · brand · outreach, each with the sessions it came from
+You     keep brand and builder, rename outreach to launches
+Agent   skillscout persona add brand --about "D2C marketing: ad copy, landing pages, Instagram reels"
+        → keywords drafted from terms skills actually use: instagram reels, ad copy, landing pages...
+        skillscout discover                → a "For your brand work" section in the report
+        skillscout persona build brand     → ~/.claude/agents/brand.md, skills: copy, landing-page-design, script...
+You     claude --agent brand
+```
+
+From then on, each weekly report has a section per persona, and `persona build` swaps in a better skill when
+one arrives (after you've read and approved it). `persona build` only ever rewrites the agent's `skills:` list:
+its prompt, tone, tools, model and memory are yours.
+
+The CLI works without the agent too:
+
+```sh
+skillscout persona add brand --about "D2C marketing: ad copy, landing pages, Instagram reels"
+skillscout persona list            # keywords, best installed skills, what's worth installing
+skillscout persona build --all     # write or update ~/.claude/agents/<name>.md
+```
+
+**Your history stays on your machine.** `skillscout history` reads `~/.claude/projects` only when you run it,
+keeps only what you typed (no tool output, no pasted blocks, no links) and sends nothing anywhere. Grouping
+sessions into personas is left to you or the agent in your own session: counting words can't tell short chat
+messages apart reliably, and a wrong persona is worse than none.
+
+## A week with skillscout
+
+Example session (counts vary week to week):
+
+```text
+Monday 10:00   skillscout discover --notify     (weekly, via schedule)
+               → "23 recommended for you (4 new this run), 11 relevant but flagged high-risk"
+               → plus a section per persona: "For your brand work", "For your builder work"
+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"*, or *"set up personas for me"*. 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 skillscout-cli     # or: uv tool install skillscout-cli
+skillscout init --about "backend in Python, code review, RL evals, Postgres"
+```
+
+`init` writes `~/.skillscout/profile.toml` and drafts `[keywords]` from your line, using only terms that skills
+actually use. Check them, then:
+
+```sh
+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. 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** (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** (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 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
+
+| 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.
+- 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.
+
+## Every command
+
+| Command | Does |
+|---|---|
+| `skillscout init` | Copy the example profile to `~/.skillscout/profile.toml` |
+| `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] [--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 init [--about "..."]` | Write the profile; `--about` drafts your keywords from one line |
+| `skillscout history [--days N]` | A local digest of your recent Claude Code sessions, to draft personas from |
+| `skillscout persona add <name> --about "..." [--keywords "a=3,b=2"]` | Add a persona; keywords drafted from the line unless given |
+| `skillscout persona list` | Each persona: keywords, best installed skills, what's worth installing |
+| `skillscout persona build <name> \| --all [--dry-run]` | Write `~/.claude/agents/<name>.md`, or update only its `skills:` list |
+| `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 |
+
+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.
+- A persona's `skills:` load in full when its agent starts. `max_skills` (default 5) keeps that small.
+
+## 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 → skillscout_cli-0.3.0}/pyproject.toml

@@ -4,14 +4,14 @@ 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"
+version = "0.3.0"
+description = "Keep your agent's skills current for each kind of work you do: weekly index, personas, 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"]
+keywords = ["claude", "claude-code", "agent-skills", "personas", "subagents", "security", "supply-chain", "llm"]
 classifiers = [
   "Development Status :: 4 - Beta",
   "Environment :: Console",