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

{skillscout_cli-0.3.0/skillscout_cli.egg-info → skillscout_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillscout-cli
-Version: 0.3.0
+Version: 0.4.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
@@ -27,7 +27,7 @@ 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" />
+  <img src="https://akshit9162.github.io/skillscout/assets/header.svg" width="760" alt="skillscout: keep your agent's skills current, for every kind of work you do" />
 </p>
 
 <p align="center">
@@ -48,7 +48,7 @@ Dynamic: license-file
 </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" />
+  <img src="https://akshit9162.github.io/skillscout/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
@@ -62,7 +62,7 @@ installed keep changing upstream, and last month's best practice is already stal
 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
+public skill it can find (32,360 from 1,173 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.
 
@@ -98,6 +98,30 @@ Agent   skillscout persona add brand --about "D2C marketing: ad copy, landing pa
 You     claude --agent brand
 ```
 
+### Switch persona, and the rest stays out of the way
+
+Every installed skill's description loads into every Claude Code session, so a big collection crowds out
+the work. Switch to the persona you're in and Claude Code lists only its skills:
+
+```sh
+skillscout persona use brand            # or say "switch to brand" to the agent
+#  active: brand
+#    hid 31: fastapi, postgres-patterns, seo-audit, ...
+#    plugins on 1: marketing@knowledge-work-plugins
+#    plugins off 2: sales@knowledge-work-plugins, android-skills@android-skills
+skillscout persona use brand builder    # several at once
+skillscout persona start brand          # switch, then start Claude Code (with brand's agent if built)
+skillscout persona use --core           # no persona: only [switch] core and unclaimed skills
+skillscout persona use --clear          # everything back as it was
+```
+
+It writes `skillOverrides` and `enabledPlugins` in `~/.claude/settings.json`: nothing moves on disk.
+A persona claims the skills that fit its keywords, plus any you pin with `skills = [...]`, minus `exclude`.
+Plugins switch whole, so you pin them with `plugins = [...]` (`persona add` drafts them from the plugins
+whose skills fit). skillscout restores only what it changed, never overwrites an override you set, and a
+skill you approve later joins whichever personas it fits. A new session picks the switch up; in an open
+one, run `/reload-skills` and `/reload-plugins`.
+
 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.
@@ -214,6 +238,8 @@ High-risk skills need `--accept-risk`, which the bundled skill tells the agent n
 | `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 persona use [<name>...] [--core] [--clear]` | List only these personas' skills and plugins in Claude Code; `--clear` undoes it |
+| `skillscout persona start <name>...` | `persona use`, then start Claude Code |
 | `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.
@@ -223,7 +249,8 @@ With the index, `discover` makes no GitHub API calls at all. For `--local` and `
 - 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.
+- Every installed skill's description loads into every agent session. `persona use` keeps only the active
+  personas' skills listed; without it, 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

{skillscout_cli-0.3.0 → skillscout_cli-0.4.0}/README.md

@@ -1,5 +1,5 @@
 <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" />
+  <img src="https://akshit9162.github.io/skillscout/assets/header.svg" width="760" alt="skillscout: keep your agent's skills current, for every kind of work you do" />
 </p>
 
 <p align="center">
@@ -20,7 +20,7 @@
 </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" />
+  <img src="https://akshit9162.github.io/skillscout/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
@@ -34,7 +34,7 @@ installed keep changing upstream, and last month's best practice is already stal
 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
+public skill it can find (32,360 from 1,173 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.
 
@@ -70,6 +70,30 @@ Agent   skillscout persona add brand --about "D2C marketing: ad copy, landing pa
 You     claude --agent brand
 ```
 
+### Switch persona, and the rest stays out of the way
+
+Every installed skill's description loads into every Claude Code session, so a big collection crowds out
+the work. Switch to the persona you're in and Claude Code lists only its skills:
+
+```sh
+skillscout persona use brand            # or say "switch to brand" to the agent
+#  active: brand
+#    hid 31: fastapi, postgres-patterns, seo-audit, ...
+#    plugins on 1: marketing@knowledge-work-plugins
+#    plugins off 2: sales@knowledge-work-plugins, android-skills@android-skills
+skillscout persona use brand builder    # several at once
+skillscout persona start brand          # switch, then start Claude Code (with brand's agent if built)
+skillscout persona use --core           # no persona: only [switch] core and unclaimed skills
+skillscout persona use --clear          # everything back as it was
+```
+
+It writes `skillOverrides` and `enabledPlugins` in `~/.claude/settings.json`: nothing moves on disk.
+A persona claims the skills that fit its keywords, plus any you pin with `skills = [...]`, minus `exclude`.
+Plugins switch whole, so you pin them with `plugins = [...]` (`persona add` drafts them from the plugins
+whose skills fit). skillscout restores only what it changed, never overwrites an override you set, and a
+skill you approve later joins whichever personas it fits. A new session picks the switch up; in an open
+one, run `/reload-skills` and `/reload-plugins`.
+
 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.
@@ -186,6 +210,8 @@ High-risk skills need `--accept-risk`, which the bundled skill tells the agent n
 | `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 persona use [<name>...] [--core] [--clear]` | List only these personas' skills and plugins in Claude Code; `--clear` undoes it |
+| `skillscout persona start <name>...` | `persona use`, then start Claude Code |
 | `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.
@@ -195,7 +221,8 @@ With the index, `discover` makes no GitHub API calls at all. For `--local` and `
 - 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.
+- Every installed skill's description loads into every agent session. `persona use` keeps only the active
+  personas' skills listed; without it, 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

{skillscout_cli-0.3.0 → skillscout_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillscout-cli"
-version = "0.3.0"
+version = "0.4.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"

{skillscout_cli-0.3.0 → skillscout_cli-0.4.0}/skillscout/cli.py

@@ -7,7 +7,7 @@ import subprocess
 import sys
 from pathlib import Path
 
-from . import __doc__ as ABOUT, core, github, history, index, persona, schedule
+from . import __doc__ as ABOUT, core, github, history, index, persona, schedule, switch
 
 EXAMPLE = Path(__file__).resolve().parent / "profile.example.toml"
 USER_PROFILE = Path.home() / ".skillscout" / "profile.toml"
@@ -64,6 +64,12 @@ def main(argv: list[str] | None = None) -> None:
     pb.add_argument("name", nargs="?")
     pb.add_argument("--all", action="store_true")
     pb.add_argument("--dry-run", action="store_true")
+    pu = psub.add_parser("use", help="list only these personas' skills and plugins in Claude Code (no names: show what's active)")
+    pu.add_argument("names", nargs="*")
+    pu.add_argument("--clear", action="store_true", help="undo every change skillscout made: all skills and plugins as before")
+    pu.add_argument("--core", action="store_true", help="no persona: hide every persona's skills and plugins, keep [switch] core")
+    ps = psub.add_parser("start", help="`persona use` these personas, then start Claude Code")
+    ps.add_argument("names", nargs="+")
     a = p.parse_args(argv)
 
     paths = core.Paths()
@@ -123,6 +129,9 @@ def main(argv: list[str] | None = None) -> None:
     elif a.cmd == "approve":
         c = core.find(cands, a.id)
         print(f"installed {c['id']} -> {core.approve(c, paths, a.accept_risk, a.update, fetch=github)}")
+        if on := switch.active(paths):                 # a new skill for an inactive persona stays out of view
+            names = [n for n in on if n != switch.CORE]
+            say_switch(switch.use(profile, paths, names, core.installed_skills(paths), not names), on, quiet=True)
     elif a.cmd == "remove":
         print(f"removed {core.remove(a.id, paths)}")
     elif a.cmd == "rollback":
@@ -147,6 +156,32 @@ def main(argv: list[str] | None = None) -> None:
         print(message)
 
 
+def say_switch(done: dict, names: list[str], quiet: bool = False) -> None:
+    parts = [f"{label} {len(done[k])}: {', '.join(done[k][:8])}{' ...' if len(done[k]) > 8 else ''}"
+             for k, label in (("hidden", "hid"), ("shown", "showed"), ("plugins_off", "plugins off"), ("plugins_on", "plugins on"))
+             if done[k]]
+    if done["kept_yours"]:
+        parts.append(f"left your own skillOverrides alone for {', '.join(done['kept_yours'])}")
+    if quiet and not parts:
+        return
+    print((f"active: {', '.join(names)}" if names else "cleared: every skill and plugin as before skillscout switched them"))
+    for line in parts:
+        print(f"  {line}")
+    if parts:
+        print("A new Claude Code session picks this up; in an open one, run /reload-skills and /reload-plugins.")
+
+
+def start_claude(names: list[str], known: dict, paths: core.Paths) -> None:
+    claude = shutil.which("claude")
+    if not claude:
+        raise SystemExit("claude isn't on PATH; the switch is done, start Claude Code yourself")
+    cmd = [claude]
+    agent = known[names[0]]["agent"] if len(names) == 1 else None
+    if agent and (paths.agents / f"{agent}.md").exists():
+        cmd += ["--agent", agent]
+    sys.exit(subprocess.run(cmd, check=False).returncode)
+
+
 def vocabulary(profile: dict, paths: core.Paths) -> dict[str, int]:
     """Terms skills use, from the cached index (downloaded first if there isn't one)."""
     try:
@@ -167,19 +202,34 @@ def run_persona(a, profile: dict, paths: core.Paths, cands: list[dict]) -> None:
         path = a.profile or USER_PROFILE
         if not path.exists():
             raise SystemExit(f"no profile at {path}; run `skillscout init` first")
-        print(persona.add(path, a.name, a.about, kw, a.agent))
+        print(persona.add(path, a.name, a.about, kw, a.agent, switch.draft_plugins(paths, kw)))
         print(f"\nadded to {path}. Next: `skillscout discover`, then `skillscout persona build {a.name}`")
         return
+    installed = core.installed_skills(paths)
+    if a.action in ("use", "start"):
+        if a.action == "use" and not a.names and not a.clear and not a.core:
+            on = switch.active(paths)
+            print(f"active: {', '.join(on)}" if on else "no persona active: Claude Code lists every skill")
+            return
+        names = [] if a.action == "use" and a.clear else a.names
+        core_only = a.action == "use" and a.core and not a.clear
+        say_switch(switch.use(profile, paths, names, installed, core_only), names or ([switch.CORE] if core_only else []))
+        if a.action == "start":
+            start_claude(names, known, paths)
+        return
     if not known:
         raise SystemExit("no personas yet: add one with `skillscout persona add <name> --about \"...\"`")
-    installed = core.installed_skills(paths)
     if a.action == "list":
+        on = switch.active(paths)
+        by = switch.claims(profile, switch.own_skills(installed))
         for name, p in known.items():
             fits = persona.fitting(installed, p["keywords"], p["max_skills"])
             agent = paths.agents / f"{p['agent']}.md"
             print(f"{name}: {p['description']}\n  keywords: {', '.join(p['keywords'])}\n"
                   f"  agent: {agent}{'' if agent.exists() else ' (not built yet)'}\n"
-                  f"  best installed skills: {', '.join(n for n, _ in fits) or 'none fit yet'}")
+                  f"  best installed skills: {', '.join(n for n, _ in fits) or 'none fit yet'}\n"
+                  f"  switches: {len(by[name])} of your skills, plugins: {', '.join(p['plugins']) or 'none'}"
+                  + ("  (active)" if name in on else ""))
             pending = [c for c in cands if core.recommended(c, profile) and c.get("personas", {}).get(name, 0) >= 0.3][:3]
             if pending:
                 print(f"  worth installing: {', '.join(c['id'] for c in pending)}")

{skillscout_cli-0.3.0 → skillscout_cli-0.4.0}/skillscout/core.py

@@ -74,7 +74,10 @@ def installed_skills(paths: Paths) -> dict[str, str]:
     for root, is_plugin in ((paths.skills, False), (paths.plugins, True)):
         if not root.exists():
             continue
-        for md in root.rglob("SKILL.md"):
+        found = set(root.rglob("SKILL.md"))
+        if not is_plugin:      # rglob doesn't follow folder links (Python 3.13+); skills are often linked in
+            found |= {d / "SKILL.md" for d in root.iterdir() if (d.is_symlink() or getattr(d, "is_junction", bool)()) and (d / "SKILL.md").is_file()}
+        for md in sorted(found):
             if ".git" in md.parts or "node_modules" in md.parts:
                 continue
             plugin = md.relative_to(root).parts[1] if is_plugin and len(md.relative_to(root).parts) > 2 else None
@@ -164,7 +167,7 @@ def crawl(s: dict, paths: Paths, fetch=github, full: bool = False) -> list[dict]
         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", []):
+    for name in [*s.get("trusted", []), *s.get("include", [])]:
         try:
             repos[name] = repos.get(name) or fetch.repo(name)
         except Exception as e:
@@ -176,8 +179,8 @@ def crawl(s: dict, paths: Paths, fetch=github, full: bool = False) -> list[dict]
             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 (
+    always = set(s.get("trusted", [])) | set(s.get("include", []))     # kept whatever their stars or age
+    keep = [r for r in repos.values() if r["full_name"] in always 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)]

{skillscout_cli-0.3.0 → skillscout_cli-0.4.0}/skillscout/persona.py

@@ -12,11 +12,13 @@ NAME = re.compile(r"[a-z0-9][a-z0-9-]{0,39}")
 
 
 def personas(profile: dict) -> dict[str, dict]:
-    """name -> {"description", "keywords", "agent", "max_skills"} from the profile's [personas.*] tables."""
+    """name -> {"description", "keywords", "agent", "max_skills", "skills", "exclude", "plugins"} from the
+    profile's [personas.*] tables. `skills`/`exclude` pin skills in or out; `plugins` are switched with it."""
     out = {}
     for name, p in profile.get("personas", {}).items():
         out[name] = {"description": p.get("description", ""), "keywords": p.get("keywords", {}),
-                     "agent": p.get("agent", name), "max_skills": p.get("max_skills", 5)}
+                     "agent": p.get("agent", name), "max_skills": p.get("max_skills", 5),
+                     "skills": p.get("skills", []), "exclude": p.get("exclude", []), "plugins": p.get("plugins", [])}
     return out
 
 
@@ -26,7 +28,8 @@ def keyword_sets(profile: dict) -> dict[str, dict[str, float]]:
     return sets | {n: p["keywords"] for n, p in personas(profile).items() if p["keywords"]}
 
 
-def add(profile_path: Path, name: str, description: str, keywords: dict[str, int], agent: str | None = None) -> str:
+def add(profile_path: Path, name: str, description: str, keywords: dict[str, int], agent: str | None = None,
+        plugins: list[str] | None = None) -> str:
     """Append a [personas.<name>] table to the profile file. Refuses a name that's taken."""
     if not NAME.fullmatch(name):
         raise SystemExit(f"persona names are lowercase letters, digits and dashes: {name!r}")
@@ -38,7 +41,9 @@ def add(profile_path: Path, name: str, description: str, keywords: dict[str, int
     block = [f"\n[personas.{name}]", f"description = {json.dumps(description)}"]
     if agent and agent != name:
         block.append(f"agent = {json.dumps(agent)}")
-    block += ["max_skills = 5", f"[personas.{name}.keywords]"] + [f"{json.dumps(k)} = {v}" for k, v in keywords.items()]
+    block += ["max_skills = 5", "skills = []    # always part of this persona", "exclude = []   # never part of it",
+              f"plugins = {json.dumps(plugins or [])}   # switched on with this persona, off when only others are active",
+              f"[personas.{name}.keywords]"] + [f"{json.dumps(k)} = {v}" for k, v in keywords.items()]
     profile_path.write_text(text.rstrip("\n") + "\n" + "\n".join(block) + "\n", encoding="utf-8")
     return "\n".join(block).strip()
 

{skillscout_cli-0.3.0 → skillscout_cli-0.4.0}/skillscout/profile.example.toml

@@ -62,11 +62,20 @@ trusted = [
 # [personas.brand]
 # description = "D2C brand marketing: ad copy, landing pages, Instagram reels"
 # max_skills = 5          # skills preloaded into the agent; each loads in full, so keep it small
+# skills = ["copy"]       # always part of this persona, whatever the keywords say
+# exclude = []            # never part of it
+# plugins = ["marketing"] # on when this persona is active, off when only others are (`persona add` drafts these)
 # [personas.brand.keywords]
 # "ad copy" = 4
 # "landing pages" = 3
 # "instagram" = 2
 
+# `skillscout persona use <name>...` lists only those personas' skills in Claude Code (skillOverrides) and
+# switches pinned plugins (enabledPlugins). It never touches entries you set yourself; --clear undoes it.
+# [switch]
+# core = ["graphify"]     # always listed, whichever persona is active
+# others = "on"           # skills no persona claims: "on" keeps them listed, "off" hides them too
+
 [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

skillscout_cli-0.4.0/skillscout/switch.py

@@ -0,0 +1,169 @@
+"""Switching personas: Claude Code lists only the skills and plugins for the work at hand.
+
+Every installed skill's description loads into every session, so a big collection crowds the context.
+`persona use brand` hides your own skills that belong to other personas (`skillOverrides: "off"` in
+~/.claude/settings.json) and turns off plugins pinned only to other personas (`enabledPlugins`; plugins
+switch whole). Nothing moves on disk.
+
+skillscout only changes back what it changed: it remembers each entry's value before it first touched it,
+restores that when the entry is no longer needed, and leaves alone anything you edited in between. Your own
+skillOverrides entries are never overwritten. `persona use --clear` puts everything back."""
+
+import json
+from pathlib import Path
+
+from .persona import fitting, personas
+from .skill import parse_frontmatter
+
+SELF = "skillscout"          # its own skill and plugin are never hidden
+ALL = 10**6
+
+
+def plugin_skills(paths) -> dict[str, dict[str, str]]:
+    """plugin name -> {skill: description} for every plugin in the cache, enabled or not."""
+    out: dict[str, dict[str, str]] = {}
+    if not paths.plugins.exists():
+        return out
+    for md in paths.plugins.rglob("SKILL.md"):
+        rel = md.relative_to(paths.plugins).parts
+        if len(rel) < 3 or ".git" in rel or "node_modules" in rel:
+            continue
+        meta = parse_frontmatter(md.read_text(encoding="utf-8", errors="ignore"))
+        out.setdefault(rel[1], {})[meta.get("name") or md.parent.name] = meta.get("description", "")
+    return out
+
+
+def draft_plugins(paths, keywords: dict, at: float = 0.25) -> list[str]:
+    """Plugins most of whose skills fit a persona's keywords (at least two, and a quarter of them)."""
+    out = []
+    for name, skills in sorted(plugin_skills(paths).items()):
+        if name == SELF:
+            continue
+        fit = len(fitting(skills, keywords, ALL))
+        if fit >= 2 and fit >= at * len(skills):
+            out.append(name)
+    return out
+
+
+def own_skills(installed: dict[str, str]) -> dict[str, str]:
+    return {n: d for n, d in installed.items() if ":" not in n}
+
+
+def claims(profile: dict, own: dict[str, str]) -> dict[str, set[str]]:
+    """persona -> the user's own skills it claims: those fitting its keywords, plus `skills`, minus `exclude`."""
+    out = {}
+    for name, p in personas(profile).items():
+        fit = {n for n, _ in fitting(own, p["keywords"], ALL)} if p["keywords"] else set()
+        out[name] = (fit | set(p["skills"])) - set(p["exclude"])
+    return out
+
+
+def plugin_keys(pins: list[str], enabled: dict) -> set[str]:
+    """Resolve `marketing` or `marketing@market` to the keys used in enabledPlugins."""
+    keys = set()
+    for pin in pins:
+        keys |= {k for k in enabled if k == pin or k.split("@")[0] == pin}
+    return keys
+
+
+def plan(profile: dict, own: dict[str, str], enabled: dict, active: list[str]) -> tuple[set[str], dict[str, bool]]:
+    """(own skills to hide, plugin key -> on/off) for this set of active personas."""
+    known = personas(profile)
+    cfg = profile.get("switch", {})
+    by = claims(profile, own)
+    active = [a for a in active if a in known]
+    keep = set(cfg.get("core", [])) | {SELF} | set().union(*(by[a] for a in active))
+    pool = set(own) if cfg.get("others", "on") == "off" else set().union(*by.values())
+    hide = {s for s in pool - keep if s in own}
+    pinned = {n: plugin_keys(p["plugins"], enabled) for n, p in known.items()}
+    on = set().union(*(pinned[a] for a in active))
+    plugins = {k: k in on for k in set().union(*pinned.values()) if k.split("@")[0] != SELF}
+    return hide, plugins
+
+
+def _load(path: Path, default):
+    return json.loads(path.read_text(encoding="utf-8")) if path.exists() else default
+
+
+def _save(path: Path, data) -> None:
+    """Atomic, and keeps the file's key order (settings.json is yours, not ours to reshuffle)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".skillscout.tmp")
+    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    tmp.replace(path)
+
+
+def apply(paths, active: list[str], hide: set[str], plugins: dict[str, bool]) -> dict:
+    """Make settings.json match the plan and report what changed. State (~/.skillscout/switch.json) keeps,
+    for each entry skillscout set, the value it had before; an entry you changed since is yours again."""
+    state_path = paths.state / "switch.json"
+    state = _load(state_path, {"active": [], "skills": {}, "plugins": {}})
+    settings = _load(paths.settings, {})
+    over = dict(settings.get("skillOverrides", {}))
+    ep = dict(settings.get("enabledPlugins", {}))
+    done = {"hidden": [], "shown": [], "plugins_on": [], "plugins_off": [], "kept_yours": []}
+
+    for name, before in sorted(state["skills"].items()):
+        if over.get(name) != "off":                            # you changed it since: yours now
+            del state["skills"][name]
+        elif name not in hide:                                 # ours and no longer needed: restore
+            over.pop(name) if before is None else over.__setitem__(name, before)
+            del state["skills"][name]
+            done["shown"].append(name)
+    for name in sorted(hide - set(state["skills"])):
+        if name in over:                                       # your own entry: never overwritten
+            done["kept_yours"].append(name)
+            continue
+        state["skills"][name] = None
+        over[name] = "off"
+        done["hidden"].append(name)
+
+    for key, (before, was_set) in sorted(state["plugins"].items()):
+        if ep.get(key) != was_set:
+            del state["plugins"][key]
+        elif key not in plugins:
+            ep[key] = before
+            del state["plugins"][key]
+            done["plugins_on" if before else "plugins_off"].append(key)
+    for key, want in sorted(plugins.items()):
+        before = state["plugins"][key][0] if key in state["plugins"] else ep.get(key, False)
+        if ep.get(key, False) != want:
+            ep[key] = want
+            done["plugins_on" if want else "plugins_off"].append(key)
+        if want == before:
+            state["plugins"].pop(key, None)                    # back where it started: nothing to undo
+        else:
+            state["plugins"][key] = [before, want]
+
+    if over != settings.get("skillOverrides", {}) or ep != settings.get("enabledPlugins", {}):
+        if over:
+            settings["skillOverrides"] = over
+        else:
+            settings.pop("skillOverrides", None)
+        if ep or "enabledPlugins" in settings:
+            settings["enabledPlugins"] = ep
+        _save(paths.settings, settings)
+    state["active"] = active
+    _save(state_path, state)
+    return done
+
+
+def active(paths) -> list[str]:
+    return _load(paths.state / "switch.json", {}).get("active", [])
+
+
+CORE = "(core only)"
+
+
+def use(profile: dict, paths, names: list[str], installed: dict[str, str], core_only: bool = False) -> dict:
+    """Activate these personas; none and not core_only means clear. core_only hides every persona's skills
+    and pinned plugins, leaving `[switch] core` and whatever no persona claims."""
+    known = personas(profile)
+    unknown = [n for n in names if n not in known]
+    if unknown:
+        raise SystemExit(f"unknown persona {', '.join(unknown)}; you have {', '.join(known) or 'none'}")
+    if not names and not core_only:
+        return apply(paths, [], set(), {})
+    enabled = _load(paths.settings, {}).get("enabledPlugins", {})
+    hide, plugins = plan(profile, own_skills(installed), enabled, names)
+    return apply(paths, names or [CORE], hide, plugins)

{skillscout_cli-0.3.0 → skillscout_cli-0.4.0/skillscout_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillscout-cli
-Version: 0.3.0
+Version: 0.4.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
@@ -27,7 +27,7 @@ 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" />
+  <img src="https://akshit9162.github.io/skillscout/assets/header.svg" width="760" alt="skillscout: keep your agent's skills current, for every kind of work you do" />
 </p>
 
 <p align="center">
@@ -48,7 +48,7 @@ Dynamic: license-file
 </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" />
+  <img src="https://akshit9162.github.io/skillscout/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
@@ -62,7 +62,7 @@ installed keep changing upstream, and last month's best practice is already stal
 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
+public skill it can find (32,360 from 1,173 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.
 
@@ -98,6 +98,30 @@ Agent   skillscout persona add brand --about "D2C marketing: ad copy, landing pa
 You     claude --agent brand
 ```
 
+### Switch persona, and the rest stays out of the way
+
+Every installed skill's description loads into every Claude Code session, so a big collection crowds out
+the work. Switch to the persona you're in and Claude Code lists only its skills:
+
+```sh
+skillscout persona use brand            # or say "switch to brand" to the agent
+#  active: brand
+#    hid 31: fastapi, postgres-patterns, seo-audit, ...
+#    plugins on 1: marketing@knowledge-work-plugins
+#    plugins off 2: sales@knowledge-work-plugins, android-skills@android-skills
+skillscout persona use brand builder    # several at once
+skillscout persona start brand          # switch, then start Claude Code (with brand's agent if built)
+skillscout persona use --core           # no persona: only [switch] core and unclaimed skills
+skillscout persona use --clear          # everything back as it was
+```
+
+It writes `skillOverrides` and `enabledPlugins` in `~/.claude/settings.json`: nothing moves on disk.
+A persona claims the skills that fit its keywords, plus any you pin with `skills = [...]`, minus `exclude`.
+Plugins switch whole, so you pin them with `plugins = [...]` (`persona add` drafts them from the plugins
+whose skills fit). skillscout restores only what it changed, never overwrites an override you set, and a
+skill you approve later joins whichever personas it fits. A new session picks the switch up; in an open
+one, run `/reload-skills` and `/reload-plugins`.
+
 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.
@@ -214,6 +238,8 @@ High-risk skills need `--accept-risk`, which the bundled skill tells the agent n
 | `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 persona use [<name>...] [--core] [--clear]` | List only these personas' skills and plugins in Claude Code; `--clear` undoes it |
+| `skillscout persona start <name>...` | `persona use`, then start Claude Code |
 | `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.
@@ -223,7 +249,8 @@ With the index, `discover` makes no GitHub API calls at all. For `--local` and `
 - 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.
+- Every installed skill's description loads into every agent session. `persona use` keeps only the active
+  personas' skills listed; without it, 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

{skillscout_cli-0.3.0 → skillscout_cli-0.4.0}/skillscout_cli.egg-info/SOURCES.txt

@@ -13,10 +13,12 @@ skillscout/scan.py
 skillscout/schedule.py
 skillscout/score.py
 skillscout/skill.py
+skillscout/switch.py
 skillscout_cli.egg-info/PKG-INFO
 skillscout_cli.egg-info/SOURCES.txt
 skillscout_cli.egg-info/dependency_links.txt
 skillscout_cli.egg-info/entry_points.txt
 skillscout_cli.egg-info/requires.txt
 skillscout_cli.egg-info/top_level.txt
+tests/test_include.py
 tests/test_skillscout.py

skillscout_cli-0.4.0/tests/test_include.py

@@ -0,0 +1,21 @@
+from skillscout import core
+
+from test_skillscout import PROFILE, FakeGitHub, link, make_repo, skill_md
+
+
+def test_include_keeps_a_repo_below_min_stars_without_trust(tmp_path):
+    paths = core.Paths(tmp_path / "state", tmp_path / "skills", tmp_path / "plugins")
+    paths.skills.mkdir()
+    new = tmp_path / "src" / "new"
+    make_repo(new, {"LICENSE": "MIT", "skills/think/SKILL.md": skill_md("think", "Mental models for a GST eval decision")})
+    gh = FakeGitHub({"me/new": (new, 0)})
+    paths.cache.mkdir(parents=True)
+    link(paths.cache / "me__new", new)
+
+    assert not core.crawl(PROFILE["search"], paths, fetch=gh, full=True)
+
+    s = {**PROFILE["search"], "include": ["me/new"]}
+    records = core.crawl(s, paths, fetch=gh, full=True)
+    assert [r["name"] for r in records] == ["think"]
+    cands = core.discover({**PROFILE, "search": s}, paths, fetch=gh)
+    assert cands and not any(c["trusted"] for c in cands)

{skillscout_cli-0.3.0 → skillscout_cli-0.4.0}/tests/test_skillscout.py

@@ -566,3 +566,86 @@ def test_plugin_skills_use_plugin_names_and_only_enabled_plugins(tmp_path):
     (paths.skills / "copy" / "SKILL.md").write_text(skill_md("copy", "ad copy"), encoding="utf-8")
     paths.settings.write_text(json.dumps({"enabledPlugins": {"marketing@market": True, "unused@market": False}}), encoding="utf-8")
     assert core.installed_skills(paths) == {"copy": "ad copy", "marketing:draft": "marketing drafting"}
+    real = tmp_path / "elsewhere" / "linked"                  # a skill folder linked in from another place
+    real.mkdir(parents=True)
+    (real / "SKILL.md").write_text(skill_md("linked", "from a link"), encoding="utf-8")
+    link(paths.skills / "linked", real)
+    assert core.installed_skills(paths)["linked"] == "from a link"
+
+
+def switch_env(tmp_path):
+    import json
+    claude = tmp_path / ".claude"
+    paths = core.Paths(tmp_path / "state", claude / "skills", claude / "plugins" / "cache")
+    for name, desc in {"copy": "ad copy for landing pages", "seo-audit": "seo audit of landing pages",
+                       "fastapi": "python fastapi backend", "pg": "postgres backend queries",
+                       "graphify": "knowledge graph", "skillscout": "keep skills current", "mine": "my thing"}.items():
+        (paths.skills / name).mkdir(parents=True)
+        (paths.skills / name / "SKILL.md").write_text(skill_md(name, desc), encoding="utf-8")
+    for plugin, skills in {"marketing": ["ad copy", "landing pages", "email"], "superpowers": ["planning"]}.items():
+        for s in skills:
+            md = paths.plugins / "mk" / plugin / "1.0" / "skills" / s.replace(" ", "-") / "SKILL.md"
+            md.parent.mkdir(parents=True)
+            md.write_text(skill_md(s.replace(" ", "-"), f"{s} work"), encoding="utf-8")
+    original = {"theme": "dark", "skillOverrides": {"mine": "name-only", "pg": "name-only"},
+                "enabledPlugins": {"marketing@mk": False, "superpowers@mk": True}, "z": 1}
+    paths.settings.write_text(json.dumps(original, indent=2) + "\n", encoding="utf-8")
+    profile = {"switch": {"core": ["graphify"]}, "personas": {
+        "brand": {"keywords": {"ad copy": 3, "landing pages": 2, "seo": 2}, "plugins": ["marketing"], "exclude": ["seo-audit"]},
+        "builder": {"keywords": {"backend": 3, "python": 2}, "skills": ["mine"]}}}
+    return paths, profile, original
+
+
+def test_persona_use_hides_other_personas_and_clear_restores_settings_exactly(tmp_path):
+    import json
+    from skillscout import switch
+    paths, profile, original = switch_env(tmp_path)
+    before = paths.settings.read_text(encoding="utf-8")
+    installed = core.installed_skills(paths)
+
+    done = switch.use(profile, paths, ["brand"], installed)
+    s = json.loads(paths.settings.read_text(encoding="utf-8"))
+    # builder's skills are hidden; brand's, core, skillscout and unclaimed ones stay; excluded seo-audit is unclaimed
+    assert s["skillOverrides"] == {"mine": "name-only", "pg": "name-only", "fastapi": "off"}
+    assert done["hidden"] == ["fastapi"] and done["kept_yours"] == ["mine", "pg"]
+    assert s["enabledPlugins"] == {"marketing@mk": True, "superpowers@mk": True}       # unpinned plugin untouched
+    assert list(s) == ["theme", "skillOverrides", "enabledPlugins", "z"]                # your key order kept
+
+    switch.use(profile, paths, ["builder"], core.installed_skills(paths))
+    s = json.loads(paths.settings.read_text(encoding="utf-8"))
+    assert s["skillOverrides"] == {"mine": "name-only", "pg": "name-only", "copy": "off"}
+    assert s["enabledPlugins"]["marketing@mk"] is False
+    assert switch.active(paths) == ["builder"]
+
+    switch.use(profile, paths, [], core.installed_skills(paths), core_only=True)        # --core
+    s = json.loads(paths.settings.read_text(encoding="utf-8"))
+    assert {k for k, v in s["skillOverrides"].items() if v == "off"} == {"copy", "fastapi"}
+    assert s["enabledPlugins"]["marketing@mk"] is False and switch.active(paths) == [switch.CORE]
+
+    switch.use(profile, paths, [], core.installed_skills(paths))                         # --clear
+    assert paths.settings.read_text(encoding="utf-8") == before
+
+
+def test_persona_use_leaves_entries_you_changed_in_between(tmp_path):
+    import json
+    from skillscout import switch
+    paths, profile, _ = switch_env(tmp_path)
+    switch.use(profile, paths, ["builder"], core.installed_skills(paths))
+    s = json.loads(paths.settings.read_text(encoding="utf-8"))
+    s["skillOverrides"]["copy"] = "name-only"            # you set it yourself after skillscout hid it
+    paths.settings.write_text(json.dumps(s), encoding="utf-8")
+    switch.use(profile, paths, [], core.installed_skills(paths))
+    assert json.loads(paths.settings.read_text(encoding="utf-8"))["skillOverrides"]["copy"] == "name-only"
+
+
+def test_others_off_hides_unclaimed_skills_and_plugins_are_drafted(tmp_path):
+    import json
+    from skillscout import switch
+    paths, profile, _ = switch_env(tmp_path)
+    profile["switch"]["others"] = "off"
+    switch.use(profile, paths, ["brand"], core.installed_skills(paths))
+    hidden = {k for k, v in json.loads(paths.settings.read_text(encoding="utf-8"))["skillOverrides"].items() if v == "off"}
+    assert hidden == {"fastapi", "seo-audit"}            # mine/pg are yours; graphify core; skillscout never
+    assert switch.draft_plugins(paths, {"ad copy": 3, "landing pages": 2}) == ["marketing"]
+    with pytest.raises(SystemExit, match="unknown persona"):
+        switch.use(profile, paths, ["nope"], {})